PicApport Plug-in Guide

Allgemeines

Versionen

• Plug-ins wurden in Version 4.0.0 eingeführt. Alles was man benötigt ist picapport.jar oder picapport.exe mit Version 4.0 oder höher.
  
  
• Seit Version 6.2 kann das Zielverzeichnis der Stellvertreterdateien (Shadow-Files) eingestellt werden:
  plugin.shadow.path (Pfad zu den Schattendateien/Substitutdateien(Shadow-Files) (*.$.jpg Dateien))
  Wenn gesetzt, werden beim nächsten Serverstart vorhandene S.jpg Dateien dort hin verschoben und Neue direkt dort angelegt.
  Beispiel: plugin.shadow.path=E\:\\picaport\\shadow
  
  

Verfügbare  Plug-ins

Aktuell (Feb 2015) sind folgende Plug-ins verfügbar. Aktualisierte Infos siehe: http://picapport.de/plugins.php

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

brew install dcraw

Installation (manuell ohne Installer)

Bevor ein Plug-in installiert wird, muss bekannt sein, wo das .picapport Verzeichnis des Servers liegt.

Während des Serverstarts wird das Plug-in Verzeichnis etwa wie folgt angezeigt:: MSG  @ 14:56:03.268 Search for plugins in C:\Users\username\.picapport\plugins

Die gewünschten Plug-ins einfach in das  .picapport/plugins Verzeichnis kopieren und den PicApport Server neu starten. Fertig.

Nachdem der Server neu gestartet wurde kann anhand der aktuellen Logdatei in  .picapport/logfiles geprüft werden, ob die Plug-in Installation
erfolgreich war. Abhängig vom Plug-in Typ sollte die Logdatei etwa folgenden Text enthalten:

........
MSG @ 14:53:18.045 Plugin loaded: PicApport GIF plugin 1.0 (c) 2014 Contecon Software GmbH .gif image/gif (hideSubstitutes=true) implements IOtherFileFormat
MSG @ 14:53:18.045 Plugin loaded: PicApport PNG plugin 1.0 (c) 2014 Contecon Software GmbH .png image/png (hideSubstitutes=true) implements IOtherFileFormat
MSG @ 14:53:18.047 Plugin loaded: PicApport PDF plugin 1.0 (c) 2015 Contecon Software GmbH .pdf application/pdf (hideSubstitutes=true) implements IOtherFileFormat
......

Rot zeigt die Dateierweiterung für die dieses Plug-in registriert ist und grün den mime-type der Originaldatei.

Wie es funktioniert

Dies ist eigentlich nur für Administratoren bzw. Programmierer interessant.

Start von PicApport

• Während des Starts wird das .picapport/plugins Verzeichnis nach .zip Dateien durchsucht.
• Für jede gefundene .zip Datei wird ein verstecktes Verzeichnis mit dem selben Namen erzeugt und der Inhalt
  der .zip Datei hineinkopiert. Dieses Verzeichnis wird plugin-directory genannt.

• Dann wird für jede .jar Datei im plugin-directory die Manifest.mf Datei nach einem gültigen PicApport-Plugin: Eintrag untersucht

• Die init() Methode des Plug-ins wird gerufen (einmalig während des Starts)
  Die folgenden Informationen werden an die Init() Methode übergeben::
  

  • File pluginDirectory
    Verzeichnis von wo das Plug-in geladen wurde. Diese Information kann vom Plug-in genutzt werden um z.B. weitere
    Konfigurationsdaten zu speichern.
    Ein Plug-in sollte nicht auf Daten außerhalb des Plugin-Directorys zugreifen.

  • Properties props
    Wenn eine .properties Datei mit dem selben Namen wie das Plug-in existiert, wird diese von PicApport geladen und an die init() Methode 
    des Plug-ins übergeben. Ein Plug-in Entwickler sollte sicherstellen, dass props an den Konstruktor der OtherFormatsDescriptor Instanzen
    übergeben wird, die während init() erzeugt werden.
    Das Plug-in kann die Properties nutzen um weitere Konfigurationsdaten zu speichern. Siehe auch PicApportPdfPlugin-src.zip wie dies verwendet werden kann.
    Beispiel: PicApportPdfPlugin.properties:

    # if resolution is not set the default will be 96 
    pdf.resolution=96
    
    menudownload.text=Show PDF
    menudownload.text.en=Show PDF
    menudownload.text.de=PDF anzeigen
    
    keywords=$nonjpg
    
    

    Der Eintrag menudownload.text[.iso language] kann verwendet werden um den Text des "Download-Buttons" in der PicApport Slideshow anzupassen.
    Ist kein Text für die aktuelle Sprache konfiguriert, wird der Eintrag (menudownload.text) benutzt. (Solle immer Englisch sein)

  • IPicApportPlugInLogger logger
    Der logger sollte in den privaten Memberdaten der Plug-in Instanz gesichert werden und für Debug Ausgaben verwendet werden.

• Die init() Methode muss mindestens eine OtherFormatsDescriptor Instanz erzeugen und in  List<OtherFormatsDescriptor> zurückgeben.

  Descriptoren erzeugen

   return  Arrays.asList(
                new OtherFormatsDescriptor[] {
                    new OtherFormatsDescriptor(".gif",          // One of the file extensions this plugin will be called 
                        "image/gif",                            // Mime type of the original file
                        true,                                   // If true, substitute files will be hidden 
                        "PicApport GIF plugin",                 // Name of the plug-in
                        "(c) 2014 Contecon Software GmbH",      // Copyright
                        "1.0",                                  // Version 
                        props),                                 // always use props passed to the init() method
                        
                     new OtherFormatsDescriptor(".png", 
                        "image/png", 
                        true, 
                        "PicApport PNG plugin", 
                        "(c) 2014 Contecon Software GmbH", 
                        "1.0", 
                        props),    
                });  

Während des Scannens der Foto Verzeichnisse

• Wenn PicApport ein Foto-Verzeichnis scannt, werden alle nicht Jpeg-Dateien geprüft ob dafür ein Plug-in registriert wurde.
• Wurde ein Plug-in registered:
  • PicApport prüft ob eine Stellvertreter-Datei (substitute-file) existiert 
    Die Stellvertreter-Datei ist die jpg Repräsentation der Originaldatei. PicApport fügt .$.jpg an den Namen der Originaldatei an um den Stellvertreter Namen zu erzeugen.
    Wenn die Stellvertreter-Datei nicht existiert oder älter ist als die Originaldatei wird die createJpegFile() Methode des Plug-ins gerufen um die Stellvertreter-Datei zu erzeugen.
    Die folgenden Informationen werden an die createJpegFile() Methode übergeben:

    • File otherFormatFile
      Vollständiger Pfad der Originaldatei

    • File jpegFileToCreate
      Vollständiger Pfad der zu erzeugenden Stellvertreter-Datei

    • CcXMPMetaData metaDataIn
      Optionale Metadaten für die Stellvertreter-Datei. Sind keine Metadaten verfügbar sollte createJpegFile() null zurückgeben.
      Sind Metadaten verfügbar, sollten diese in metaDataIn  gesetzt werden und  metaDataIn sollte anstatt null zurückgegeben werden.
      Siehe auch: Javadoc http://picapport.de/plugins/javadoc/ für weitere Details von CcXMPMetaData .

Programmierung

Plug-ins werden in Java erstellt.

Es muss sichergestellt sein, dass ein picapport.jar mindestens mit Version 4.0.0 im classpath des Compilers eingetragen ist

Ein PicApport Plug-in zu erstellen ist sehr einfach. Einfach eine Java-Klasse erstellen die zwei Methoden implementiert:

• public List<OtherFormatsDescriptor> init(File pluginDirectory, Properties props, IPicApportPlugInLogger logger)

• public CcXMPMetaData createJpegFile(File otherFormatFile, File jpegFileToCreate, CcXMPMetaData metaDataIn)

Siehe auch: Javadoc http://picapport.de/plugins/javadoc/ für weitere Details.

Beispiel PicApport Plug-in for .gif and .png Unterstützung

package de.contecon.picapport.plugin.javaimage;
import java.awt.Color;
import java.awt.Graphics2D;
import java.awt.image.BufferedImage;
import java.io.File;
import java.util.Arrays;
import java.util.Calendar;
import java.util.Date;
import java.util.List;
import java.util.Properties;
import javax.imageio.ImageIO;
import de.contecon.imageutils.CcXMPMetaData;
import de.contecon.picapport.plugins.IPicApportPlugInLogger;
import de.contecon.picapport.plugins.otherformats.IOtherFileFormat;
import de.contecon.picapport.plugins.otherformats.OtherFormatsDescriptor;
/**
 * This is a simple example of a PicApport plugin. 
 * To compile this at least a picapport.jar version 3.3 or newer is required.
 * This Plugin supports .gif and .png files.
 * 
 * PicApport plugins for other fileformats must implement de.contecon.picapport.plugins.otherformats.IOtherFileFormat
 * 
 * Please have in mind that a valid PicApport plugin .jar files MUST have a Manifest.mf file
 * with a PicApport-Plugin: entry. 
 *  
 * Example Manifest.mf:
 * <pre>
 * Manifest-Version: 1.0
 * Sealed: true
 * PicApport-Plugin: de.contecon.picapport.plugin.javaimage.JavaImagePlugin
 * <pre>
 * 10.02.2015
 * @author Eric
 */
public class JavaImagePlugin implements IOtherFileFormat {
  private IPicApportPlugInLogger logger;
  
  @Override
  public List<OtherFormatsDescriptor> init(File pluginDirectory, Properties props, IPicApportPlugInLogger logger) {
    this.logger = logger;
    
    return  Arrays.asList(
              new OtherFormatsDescriptor[] {
                  new OtherFormatsDescriptor(".gif", 
                      "image/gif", 
                      true, 
                      "PicApport GIF plugin", 
                      "(c) 2014 Contecon Software GmbH", 
                      "1.0", 
                      props),
                      
                   new OtherFormatsDescriptor(".png", 
                      "image/png", 
                      true, 
                      "PicApport PNG plugin", 
                      "(c) 2014 Contecon Software GmbH", 
                      "1.0", 
                      props),    
              });   
  }
  
  
  
  @Override
  public CcXMPMetaData createJpegFile(File otherFormatFile, File jpegFileToCreate, CcXMPMetaData metaDataIn) throws Exception {
    BufferedImage bi = ImageIO.read(otherFormatFile);
    
    BufferedImage bufferedImageJpg = new BufferedImage(bi.getWidth(), bi.getHeight(), BufferedImage.TYPE_INT_RGB);
    Graphics2D g2 = bufferedImageJpg.createGraphics();
    g2.drawImage(bi, 0, 0, bufferedImageJpg.getWidth(), bufferedImageJpg.getHeight(), Color.WHITE, null);
    javax.imageio.ImageIO.write(bufferedImageJpg,"jpeg", jpegFileToCreate);
    g2.dispose();
    
    Calendar dateCreated = Calendar.getInstance();
    dateCreated.setTime(new Date(otherFormatFile.lastModified()));
    metaDataIn.setCreationDate(dateCreated);
    metaDataIn.setTitle(otherFormatFile.getName());
    metaDataIn.setDescription("PicApport JavaImagePlugin");
    
    return(metaDataIn);
  }
}

Die Manifest Datei

Ein PicApport Plug-in wird durch eine .jar Datei repräsentiert. Diese .jar Datei MUSS eine Manifest.mf Datei enthalten mit einem PicApport-Plugin: Eintrag in welchem die Klasse deklariert wird, welche de.contecon.picapport.plugins.otherformats.IOtherFileFormat implementiert.

Manifest-Version: 1.0
Sealed: true
PicApport-Plugin: de.contecon.picapport.plugin.javaimage.JavaImagePlugin

Die Plug-in .zip Datei

Als letzter Schritt wird eine .zip Datei für das Plug-in erstellt. Der Dateiname sollte dem Klassennamen des Plug-ins entsprechen.

Die .zip Datei muss mindestens folgende Dateien beinhalten::

• Die .jar Datei des Plug-ins
• Die.properties Datei des Plug-ins

Optionaler Inhalt könnte sein::

• Weitere .jar Dateien die vom Plug-in benötigt werden
• Lizenz Informationen
• Weitere Dateien