Änderungen von Dokument Plugin-Entwicklung

Von 2.1 nach 3.1 Von 3.10 nach 3.11

Von Version 3.1

bearbeitet von awa
am 25.02.2022, 11:37

Änderungskommentar: settings.xml

Auf Version 3.10

bearbeitet von awa
am 25.02.2022, 12:17

Änderungskommentar: Es gibt keinen Kommentar für diese Version

Rohform
Im Layout

Zusammenfassung

Seiteneigenschaften (1 geändert, 0 hinzugefügt, 0 gelöscht)

Details

Seiteneigenschaften

Inhalt

@@ -8,17 +8,17 @@
  Die API-Dokumentation für {{formcycle/}} findet sich hier auf unserer Seite: [[Javadocs>>https://docs.formcycle.eu/]]
--== Projekt-Setup ==
++== Maven-Setup ==
  Zu Beginn der Entwicklung eines Plugins ist es nötig das entsprechende Entwicklungsprojekt aufzusetzten und zu konfigurieren.
  Für letzteres empfehlen wir hierbei das Build-Management-Tool [[Apache Maven>>url:https://maven.apache.org/||rel="__blank"]] zum Einsatz. Andere Build-Tools können prinzipiell benutzt werden, hier können wir aber keine Hilfe bereitstellen.
--Um die entsprechenden Abhängigkeiten zu {{formcycle case="dat"/}} bereitzustellen, ist das Repository unter der URL [[https:~~/~~/artifactory.xima-services.de/artifactory/fc-plugin-dev>>url:https://artifactory.xima-services.de/artifactory/fc-plugin-dev]] zu benutzen. Dieses enthält alle öffentlich zur Verfügung stehenden Artefakte, welche dem Plugin zur Laufzeit bereitgestellt und während der Entwicklung benötigt werden. Ausgangspunkt ist hierbei das Artefakt //fc-plugin-common//, welches die einzelnen Plugin-Schnittstellen beinhaltet und auch auf [[unserere Downloadseite zur Verfügung steht>>url:http://artifactory.xima-services.de/artifactory/fc-plugin-dev/de/xima/fc/fc-plugin-common/]].
++Um die entsprechenden Abhängigkeiten zu {{formcycle case="dat"/}} bereitzustellen, ist das Repository unter der URL [[https:~~/~~/artifactory.xima-services.de/artifactory/fc-plugin-dev>>url:https://artifactory.xima-services.de/artifactory/fc-plugin-dev]] zu benutzen. Dieses enthält alle öffentlich zur Verfügung stehenden Artefakte, welche dem Plugin zur Laufzeit bereitgestellt und während der Entwicklung benötigt werden.
  Damit das Repository auch beim Bauen mit Maven verwendet wird, sollte folgendes in die Maven-Konfigurationsdatei //settings.xml// geschrieben werden. Diese Datei findet sich in der Regeln im //.m2//-Ordner im Home-Verzeichnis des aktuellen Nutzers. Unter Linux //~/.m2/settings.xml// und unter Windows //%homepath%\.m2\settings.xml//:
--{{panel title="~/.m2/settings.xml" fullwidth="true" initial="hidden" triggerable="true"}}
++{{panel title="~~~~/.m2/settings.xml" fullwidth="true" initial="hidden" triggerable="true"}}
  {{code language="xml"}}
  <?xml version="1.0" encoding="UTF-8"?>
  <settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd" xmlns="http://maven.apache.org/SETTINGS/1.1.0"
@@ -27,6 +27,7 @@
    <!-- Add XIMA artifactory -->
    <profiles>
      <profile>
++      <!-- FORMCYCLE dependencies -->
        <repositories>
          <repository>
            <snapshots>
@@ -37,6 +37,7 @@
            <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
          </repository>
        </repositories>
++      <!-- Maven plugins for FORMCYCLE -->
        <pluginRepositories>
          <pluginRepository>
            <snapshots>
@@ -64,8 +64,20 @@
  {{/code}}
  {{/panel}}
--In der //pom.xml// des Plugin-Projekts kann die Abhängigkeit dann wie folgt eingebunden werden:
++== Maven-Projekteinrichtung
++Im Folgenden werden einige Punkte beschrieben, die beim Einrichten eines Maven-Projekts für ein {{formcycle/}}-Plugin beachtet werden müssen. Für den schnellen Einstieg gibt auch einige [[Maven-Archetypes>>#HMaven-Archetypes]].
++
++=== Artekfakte und Abhängigkeiten
++
++{{info}}
++Alle Abhängigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren!
++{{/info}}
++
++Ausgangspunkt für die Entwicklung von Plugin ist das Maven-Artefakt //fc-plugin-common//. Dieses enthält die einzelnen Plugin-Schnittstellen und steht auch auf [[unserere Downloadseite zur Verfügung>>url:http://artifactory.xima-services.de/artifactory/fc-plugin-dev/de/xima/fc/fc-plugin-common/]].
++
++In der //pom.xml// des Plugin-Projekts kann diese Abhängigkeit wie folgt eingebunden werden:
++
  {{code language="xml"}}
    <properties>
      <xfc.version>7.0.10</xfc.version>
@@ -96,14 +96,99 @@
  Ferner ist zu beachten, dass sämtliche Abhängigkeiten zu {{formcycle case="dat"/}} im scope //provided //anzugeben sind. Dies verhindert neben Classpath-Problemen auch das unnötige Anschwellen der Plugin-Größe. Ebenso sollten diesbezüglich Abhängigkeiten auf bereits von {{formcycle case="dat"/}} benutzten und damit bereitstehenden Bibliotheken wiederverwendet werden (z.B. diverse Apache Commons-Implementierungen).
--{{info}}
--Alle Abhangigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren!
--{{/info}}
++=== Manifest und Fat JAR
--Basierend auf der hiermit zur Verfügung stehenden Infrastruktur steht der Entwicklung von eigenen Plugin-Implementierungen nichts mehr im Wege. Die Installation erfolgt anschließend je nach Verwendungszweck über die Oberflächen [[Mandant-Plugins>>doc:Formcycle.UserInterface.Client.Plugins]] oder [[System-Plugins>>doc:Formcycle.SystemSettings.UserInterface.SystemPlugins]].
++In der //META-INF/MANIFEST.MF// in der Plugin-JAR-Datei sollten folgende Informationen stehen:
--== Archetypes ==
++; formcycle-version-requirement
++: Erforderlich. Version von {{formcycle/}}, für die das Plugin gedacht ist.Ist erforderlich, damit {{formcycle/}} bei der Installation die Kompatibilität prüfen kann.
++; Implementation-Version
++: Erforderlich. Version des Plugins, wird etwa in der Oberfläche angezeigt.
++; Build-Time oder Build-Timestamp
++: Optional, wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren.
++; Implementation-Title
++: Optional, wird standardmäßig etwa vom Deploy-Plugin verwendet, um das Plugin zu identifzieren.
++Diese Informationen können wie unten beschrieben mittels des //maven-assembly-plugin// in die Manifest-Datei geschrieben werden.
++
++Weiterhin ist beim Bauen zu beachten, dass eine sogenannte Fat-JAR gebaut werden muss. Abhängigkeiten zu {{formcycle case="dat"/}} sowie anderen Bibliotheken, welche bereits durch {{formcycle case="acc"/}} mitgeliefert werden, sollten wie bereits erwähnt im scope //provided// eingebunden werden. Falls im Plugin aber noch andere Abhängigkeiten benutzt werden, müssen diese in der JAR-Datei inkludiert werden (Fat JAR).
++
++Dies kann entweder über das [[maven-assembly-plugin>>url:https://maven.apache.org/plugins/maven-assembly-plugin/]] oder das [[maven-shade-plugin>>url:https://maven.apache.org/plugins/maven-shade-plugin/]] erfolgen. Letzteres ist für forgeschrittene Anwendungsfälle gedacht, wenn etwa mehrere Abhängigkeiten die gleichen Dateien mitbringen und zusammengeführt werden müssen.
++
++Für einfache Plugins ist das //maven-assembly-plugin// ausreichend. Dieses kann in der //pom.xml// wie folgt konfiguriert werden:
++
++{{panel title="maven-assembly-plugin in pom.xml" fullwidth="true" initial="hidden" triggerable="true"}}
++{{code language="java"}}
++  <properties>
++    <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
++  </properties>
++  <build>
++    <finalName>${project.parent.artifactId}</finalName>
++    <plugins>
++      <plugin>
++        <groupId>org.apache.maven.plugins</groupId>
++        <artifactId>maven-assembly-plugin</artifactId>
++        <version>${maven-assembly-plugin.version}</version>
++        <executions>
++          <execution>
++            <id>fat-jar</id>
++            <phase>package</phase>
++            <goals>
++              <goal>single</goal>
++            </goals>
++            <configuration>
++              <finalName>${project.parent.artifactId}</finalName>
++              <appendAssemblyId>false</appendAssemblyId>
++              <descriptorRefs>
++                <descriptorRef>jar-with-dependencies</descriptorRef>
++              </descriptorRefs>
++              <archive>
++                <manifest>
++                  <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
++                </manifest>
++                <manifestEntries>
++                  <formcycle-version-requirement>${xfc-version}</formcycle-version-requirement>
++                  <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
++                  <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
++                  <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
++                  <Implementation-Version>${project.version}</Implementation-Version>
++                </manifestEntries>
++              </archive>
++            </configuration>
++          </execution>
++        </executions>
++      </plugin>
++    </plugins>
++  </build>
++{{/code}}
++{{/panel}}
++
++=== Bauen und Installieren ===
++
++Der genaue Befehl zum Bauen hängt von den konkreten Einstellungen in der //pom.xml// ab. In der Regel sollte aber folgender Standardbefehl im Plugin-Verzeichnis funktionieren:
++
++{{code}}
++  mvn clean install
++{{/code}}
++
++Nachdem das Plugin erfolgreich gebaut wurde, kann die so entstandene JAR-Datei in {{formcycle/}} über die Oberfläche [[Mandant-Plugins>>doc:Formcycle.UserInterface.Client.Plugins]] beziehungsweise [[System-Plugins>>doc:Formcycle.SystemSettings.UserInterface.SystemPlugins]] hochgeladen werden.
++
++Zum automatischen Hochladen gibt es zudem das Deploy-Plugin, siehe unten.
++
++Zum Starten eines einfachen {{formcycle/}}-Servers gibt es das FC-Server-Plugin, siehe ebenfalls unten.
++
++== Maven-Archetypes ==
++
  TODO
  Um einen besseren Einstieg in die Plugin-Entwicklung zu finden, [[bieten wir auf unserer Downloadseite>>url:https://customer.formcycle.eu/index.php/s/PgdMrNOvbYEzhmr]]
++
++== Deploy-Plugin
++
++TODO
++
++== FC-Server-Plugin
++
++TODO
++
++