===== Aufbau eines Online-Repositories für Jameica-Plugins =====

Der in Jameica integrierte Plugin-Manager (zu finden im Menü unter "Datei->Einstellungen->Plugins") bietet die Möglichkeit, neben den "ab Werk" vorhandenen Plugin-Quellen (Repositories) weitere eigene hinzuzufügen.

Diese Anleitung beschreibt den Aufbau eines solchen Repositories.

==== Grundlagen ====

Für ein Online-Repository ist abgesehen von einem Webserver keine weitere Software nötig. Im Basis-Verzeichnis des Online-Repositories (hier im Beispiel "https://www.willuhn.de/projects/jameica/updates" muss sich lediglich eine Datei "repository.xml" befinden, welche auf die Plugins verweist.

==== Aufbau der repository.xml ====

Das technische Dateiformat ist in dieser [[http://www.willuhn.de/schema/jameica-repository-1.0.xsd|XML-Schema-Datei]] beschrieben. Beispielhafter Aufbau:

<code xml>
<?xml version="1.0" encoding="ISO-8859-1"?>

<repository xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://www.willuhn.de/schema/jameica-repository-1.0.xsd"
  name="Updates für Jameica-Plugins">

   <plugins name="Jameica" certificate="https://www.willuhn.de/products/jameica/updates/jameica.update-pem.crt">
     <plugin url="https://www.willuhn.de/products/jameica/updates/jameica.webadmin" />
     <plugin url="https://www.willuhn.de/products/jameica/updates/jameica.xmlrpc" />
     [...]
   </plugins>
   
   <plugins name="Hibiscus" certificate="https://www.willuhn.de/products/jameica/updates/jameica.update-pem.crt">
     <plugin url="https://www.willuhn.de/products/jameica/updates/hibiscus/1.12" />
     <plugin url="https://www.willuhn.de/products/jameica/updates/hibiscus/1.13-nightly" />
     <plugin url="https://www.willuhn.de/products/jameica/updates/hibiscus.xmlrpc" />
   </plugins>

   <plugins name="SynTAX" certificate="https://www.willuhn.de/products/jameica/updates/jameica.update-pem.crt">
     <plugin url="https://www.willuhn.de/products/jameica/updates/syntax/1.6" />
     <plugin url="https://www.willuhn.de/products/jameica/updates/syntax/1.7-nightly" />
   </plugins>
   
</repository>
</code>

=== Header ===

<code xml>
<repository ... name="Updates für Jameica-Plugins">
</code>

| name | Bezeichnung des Repositories. |


=== Plugins ===

<code xml>
<plugins name="Jameica" certificate="https://www.willuhn.de/products/jameica/updates/jameica.update-pem.crt">
  [...]
</plugins>
</code>

| plugins     | Container-Element, welches eine Liste von Plugins enthält. Das Element darf mehrfach vorkommen, falls das Repository mehrere Gruppen von Plugins enthält. |
| name        | Optionale Angabe eines Namens für die Gruppe der Plugins. |
| certificate | Optionale Angabe der URL eines PEM/DER-codierten Aussteller-Zertifikates, mit dem die Plugins signiert sind. |

=== Plugin ===

<code xml>
[...]
<plugin url="https://www.willuhn.de/products/jameica/updates/jameica.webadmin" />
[...]
</code>

| plugin  | Ein einzelnes Plugin |
| url     | URL zum Plugin-Verzeichnis. In diesem Verzeichnis muss sich die "plugin.xml" des Plugins befinden. |


==== Plugin-Verzeichnis ====

Die in "repository.xml" referenzierten Verzeichnisse müssen jeweils eine "plugin.xml" enthalten. Hierbei handelt es sich schlicht um eine Kopie der "plugin.xml" aus dem jeweiligen Plugin. Diese Datei wird verwendet, um die Download-URL des Plugins sowie Abhängigkeiten zu anderen Plugins zu ermitteln. Das Format ist in [[develop:plugin.xml]] beschrieben. Daher hier beispielhaft nur der für das Online-Update relevante Teil am Beispiel "Hibiscus".

<code xml>
<?xml version="1.0" encoding="ISO-8859-1"?>

<plugin xmlns="http://www.willuhn.de/schema/jameica-plugin"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.willuhn.de/schema/jameica-plugin http://www.willuhn.de/schema/jameica-plugin-1.0.xsd"
        name="hibiscus" version="1.12" class="de.willuhn.jameica.hbci.HBCI">

  <description>HBCI-Onlinebanking-Plugin für Jameica</description>
  <url>https://www.willuhn.de/products/hibiscus/releases/1.12/hibiscus.zip</url>
  [...]
</plugin>
</code>

Das Element "url" muss die Download-URL des Plugins enthalten. Das Archiv muss im ZIP-Format vorliegen und alle Dateien in einem Unterverzeichnis enthalten, dessen Name mit dem Namen des Plugins identisch ist. In unserem Beispiel also "hibiscus".

Die "plugin.xml" kann weiterhin Abhängigkeiten zu weiteren Plugins definieren. Das Format ist in [[develop:plugin.xml#dependencies]] beschrieben.


==== Installationsvoraussetzungen für Plugins ====

Damit ein Plugin via Online-Update installiert werden kann, müssen folgende Voraussetzungen erfüllt sein. Andernfalls wird der Menu-Eintrag "Herunterladen und installieren..." von Jameica deaktiviert bzw. beim Versuch der Installation wird eine Fehlermeldung angezeigt:

  * Es muss ein beschreibbarer Plugin-Ordner auf dem Computer des Nutzers vorhanden sein. Entweder direkt im Programmordner oder im Jameica-Benutzerordner. Falls im Programmordner keine Schreibzugriffe für den Benutzer erlaubt sind (weil Jameica z.Bsp. in einem Verzeichnis installiert ist, in dem nur Root/Administrator) Schreibzugriff besitzt, dann wählt Jameica bei der Installation automatisch den Benutzerordner. Sind beide beschreibbar, zeigt Jameica einen Auswahldialog an, in dem der Nutzer selbst entscheiden kann.
  * Falls das Plugin Abhängigkeit zu weiteren Plugins besitzt und diese von Jameica nicht automatisch aufgelöst werden können (Jameica sucht die abhängigen Plugins über alle eingerichteten Repositories und installiert diese automatisch mit), müssen sie vom Benutzer vorher manuell installiert werden.
  * Die in "<requires jameica="$version"> angegebene Jameica-Version muss kompatibel zur installierten Jameica-Version sein.


==== Ablauf der Installation ====

Erfüllt ein Plugin alle Installationsvoraussetzungen, kann es durch den User mittels Klick auf "Installieren..." heruntergeladen werden. Hierbei wird die ZIP-Datei im Ordner "deploy" (je nach Auswahl entweder im Jameica-Benutzerordner oder im Programmordner) gespeichert. Beim nächsten Start von Jameica überprüft der "DeployService", ob sich in diesem Verzeichnis neue zu installierende Plugins befinden. Ist das der Fall, entpackt Jameica sie. Ist das Plugin in diesem Verzeichnis bereits in einer gleichen oder älteren Version installiert, wird die Vorversion automatisch gelöscht. Durch das Löschen wird verhindert, dass eine neuere Version über die alte "drüberkopiert" wird und hierbei Programmfragmente der Vorversion erhalten bleiben könnten. Hat der User also manuelle Änderungen am Plugin-Verzeichnis vorgenommen (aus welchen Gründen auch immer), gehen diese hierbei verloren.



==== FAQ ====

  * **Frage** Wie kann ich ein Plugin in mehreren Versionen anbieten?\\ **Antwort** Wenn die [[develop:plugin.xml#dependencies|Plugin-Abhängigkeiten]] korrekt formuliert sind, kann das Plugin in verschiedenen Versionen im Repository angeboten werden. Der Update-Manager bietet dem Benutzer dann all jene Versionen an, die zur aktuellen Jameica-Installation des Users kompatibel sind.