Änderungen von Dokument Plugin-Entwicklung

Von 7.1 nach 6.3 Von 10.11 nach 10.10

Von Version 10.10

bearbeitet von awa
am 02.12.2022, 21:18

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

Auf Version 7.1

bearbeitet von awa
am 25.02.2022, 15:11

Änderungskommentar: Uploaded new attachment "pom.xml", version 1.4

Rohform
Im Layout

Zusammenfassung

Seiteneigenschaften (1 geändert, 0 hinzugefügt, 0 gelöscht)
Anhänge (1 geändert, 0 hinzugefügt, 0 gelöscht)
- pom.xml

Details

Seiteneigenschaften

Inhalt

@@ -5,7 +5,7 @@
  == API-Dokumentation ==
--Die API-Dokumentation für {{formcycle/}} findet sich hier auf unserer Seite: [[JavaScript und JavaDocs>>https://docs.formcycle.eu/]]
++Die API-Dokumentation für {{formcycle/}} findet sich hier auf unserer Seite: [[Javadocs>>https://docs.formcycle.eu/]]
  == Maven-Setup ==
@@ -65,11 +65,11 @@
  {{/code}}
  {{/panel}}
--== Maven-Projekteinrichtung ==
++== 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>>||anchor="HMaven-Archetypes"]].
--=== Artekfakte und Abhängigkeiten ===
++=== Artekfakte und Abhängigkeiten
  {{info}}
  Alle Abhängigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren!
@@ -77,7 +77,7 @@
  Eine fertige einfache //pom.xml// können Sie [[hier herunterladen>>attach:pom.xml||rel="__blank"]].
--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 [[unsererer Downloadseite zur Verfügung>>url:http://artifactory.xima-services.de/artifactory/fc-plugin-dev/de/xima/fc/fc-plugin-common||rel="noopener noreferrer" target="_blank"]].
++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 [[unsererer Downloadseite zur Verfügung>>url:http://artifactory.xima-services.de/artifactory/fc-plugin-dev/de/xima/fc/fc-plugin-common||target="_blank"]].
  In der //pom.xml// des Plugin-Projekts kann diese Abhängigkeit wie folgt eingebunden werden:
@@ -109,37 +109,20 @@
  Eine entsprechende Benutzung ist vor allem bei der Verwendung der Datenbankschnittstelle sowie bei der Implementierung von eigenen Verarbeitungen nötig.
--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). Solche Abhängigkeit sind auch im Scope //provided// zu definieren. Eine einfache Möglichkeit, Fehler zu vermeiden, ist das Importieren der FORMCYCLE-Bom:
++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).
--{{code language="xml"}}
--	<dependencyManagement>
--		<dependencies>
--			<!--Import dependency versions from FORMCYCLE -->
--			<dependency>
--				<groupId>de.xima.fc</groupId>
--				<artifactId>fc</artifactId>
--				<version>${xfc.version}</version>
--				<type>pom</type>
--				<scope>import</scope>
--			</dependency>
--		</dependencies>
--	</dependencyManagement>
--{{/code}}
++=== Manifest und Fat JAR
--Dann einfach die gewünschte Abhängigkeit ohne {{code}}<version>...</version>{{/code}} definieren. Wenn FORMCYCLE die Abhängigkeit schon enthält, gibt es keinen Build-Fehler. Andernfalls muss diese im Plugin mitgeliefert werden. In dem Fall die Version hinzufügen und den Provided-Scope entfernen.
--
--=== Manifest und Fat JAR ===
--
  In der //META-INF/MANIFEST.MF// in der Plugin-JAR-Datei sollten folgende Informationen stehen:
  ; 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.
++: 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; Diese wird z.B. in der Oberfläche angezeigt.
++: 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.
++: 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.
++: 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.
@@ -219,7 +219,7 @@
    Auswahl eines Archetypes beim Erstellen eines Maven-Projekts in Eclipse
  {{/figure}}
--Für einige häufig verwendete Plugin-Typen stehen [[Maven-Archetypes>>url:https://maven.apache.org/guides/introduction/introduction-to-archetypes.html||rel="noopener noreferrer" target="_blank"]] bereits, um schnell ein Maven-Projekt aufsetzen zu können.
++Für einige häufig verwendete Plugin-Typen stehen [[Maven-Archetypes>>url:https://maven.apache.org/guides/introduction/introduction-to-archetypes.html||target="_blank"]] bereits, um schnell ein Maven-Projekt aufsetzen zu können.
  Voraussetzung für die Verwendung ist, dass in den //~~/.m2/settings.xml// wie oben beschrieben das XIMA-Artifactory eingerichtet wurde. Dann kann etwa über die Kommandozeile wie folgt eine Archetype generiert werden:
@@ -229,15 +229,13 @@
  Es werden dann einige wenige Informationen wie die gewünschten Maven-Koordinaten des neuen Plugin-Projekts abgefragt und anschließend ein neues vorkonfiguriertes Projekt erstellt.
--Alle vorhandenen Archetypes und deren Versionen können im [[Archetype-Katalog>>url:https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml||rel="noopener noreferrer" target="_blank"]] eingesehen werden.
++Alle vorhandenen Archetypes und deren Versionen können im [[Archetype-Katalog>>url:https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml||target="_blank"]] eingesehen werden.
  In Eclipse kann der Archetype-Katalog in den Einstellungen hinzugefügt werden. Bei der Erstellung eines neuen Maven-Projekt werden dann alle verfügbaren Archetypes angezeigt:
--{{code language="plaintext"}}
--https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml
--{{/code}}
++{{code language="plaintext"}}https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml{{/code}}
--== Deploy-Plugin ==
++== Deploy-Plugin
  Um beim Entwickeln nicht jedes Mal eine neue Plugin-Version manuell über die Oberfläche hochladen zu müssen, kann das Deploy-Plugin verwendet werden. Dieses besteht aus 2 Teilen:
@@ -244,41 +244,39 @@
  * Ein Maven-Plugin, welches nach dem Bauen das Plugin via HTTP an einen laufenden {{formcycle/}}-Server sendet
  * Ein Plugin für {{formcycle/}}, welche die Gegenstelle in {{formcycle/}} bereitstellt und das Plugin aus dem HTTP-Request in {{formcycle/}} installiert.
--Weitere Details können im [[Hilfe-Artikel zum Deploy-Plugin>>doc:Formcycle.PluginDocumentation.FormcycleDeployPluginPlugin]] nachgelesen werden. Für die meisten Fälle reicht folgende Konfiguration in der //pom.xml// des Plugin-Projekts aus, wo nur die Version definiert wird.
++Weitere Details können im [[Hilfe-Artikel zum Deploy-Plugin>>doc:Formcycle.PluginDocumentation.FormcycleDeployPluginPlugin]] nachgelesen werden. Für die meisten Fälle reicht folgende Konfiguration in der //pom.xml// des Plugin-Projekts aus:
  {{code language="xml"}}
    <properties>
--    <fc-deploy-plugin-maven-plugin.version>7.0.1<fc-deploy-plugin-maven-plugin.version></fc-deploy-plugin-maven-plugin>
++    <fc-deploy-plugin-maven-plugin.version>7.0.1<fc-deploy-plugin-maven-plugin.version/>
    <build>
      <plugins>
--   <plugin>
++	  <plugin>
          <groupId>de.xima.fc.maven.plugin</groupId>
          <artifactId>fc-deploy-plugin-maven-plugin</artifactId>
          <version>${fc-deploy-plugin-maven-plugin.version}</version>
++        <executions>
++          <execution>
++            <id>upload</id>
++            <phase>install</phase>
++            <goals>
++              <goal>deploy</goal>
++            </goals>
++          </execution>
++        </executions>
        </plugin>
      </plugins>
    </build>
  {{/code}}
--Sofern das Deploy-Plugin bereits in {{formcycle/}} installiert ist, kann das Plugin-Projekt dann wie folgt gebaut und hochgeladen werden:
++Sofern das Deploy-Plugin bereits in {{formcycle/}} installiert ist, kann das Plugin-Projekt dann beim Bauen wie folgt hochgeladen werden:
  {{code language="bash"}}
--mvn fc-deploy:deploy
++mvn clean install -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin
  {{/code}}
--Es wird hierbei davon ausgegangen, dass {{formcycle/}} unter der Standard-URL {{code}}http://localhost:8080/xima-formcycle{{/code}} läuft und das Standard-Passwort "admin" für das Deploy-Plugin verwendet wird. Ist dies nicht der Fall, können die Werte auch angepasst werden:
++Wird Eclipse benutzt, kann auch eine Launch-Configuration mit den //fcDeployUrl// und dem //fcDeployToken// angelegt werden.
--{{code language="bash"}}
--mvn package fc-deploy:deploy -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin
--{{/code}}
--
--{{info}}
--Bis einschließlich Version 7.x von {{formcycle/}} und dem Maven-Plugin ist es noch erforderlich, die package-Phase explizit aufzuführen. Zudem müssen die URL und das Passwort angegeben werden. Ab Version 8.x sind die Standardwerte gesetzt und die package-Phase wird automatisch ausgeführt.
--{{/info}}
--
--Wird Eclipse benutzt, kann auch eine Launch-Configuration mit den //fcDeployUrl// und dem //fcDeployToken// angelegt werden. Das Plugin wird dann unter den System-Plugins registriert.
--Soll das Plugin im Bereich eines bestimmten Mandanten registriert werden, so kann dies über den zusätzlichen Launch-Configuration Parameter //fcDeployClientId //erreicht werden. Dieser Parameter muss als Wert die Id des Mandanten enthalten.
--
  == FC-Server-Plugin ==
  Zum Testen eines Plugins ist es erforderlich, einen laufenden {{formcycle/}}-Server zu haben. Zur Vereinfachung der Entwicklung gibt es das //fc-server-maven-plugin//, welches mittels eines einzigen Befehls ein fertig eingerichtetes {{formcycle/}} lokal startet, wo auch bereits das Deploy-Plugin vorinstalliert ist.
@@ -286,28 +286,10 @@
  Sofern wie oben beschrieben in //~~/.m2/settings.xml// die //pluginGroup// hinterlegt wurde, kann in einem beliebiegen Verzeichnis wie folgt ein {{formcycle/}}-Server per Maven gestartet werden:
  {{code language="bash"}}
--# Aktuelle Version starten
--mvn fc-server:run-ms-war
--
--# Spezifische Version starten
--mvn de.xima.fc.maven.plugin:fc-server-maven-plugin:7.0.4:run-ms-war -DxfcVersion=7.0.16
++mvn fc-server:run-ms-war -DxfcVersion=7.0.10
  {{/code}}
--{{info}}
--Wir empfehlen die Nutzung von Java 11. Bei Nutzung von Java 17 kann es aktuell zu Problemen beim Starten von {{formcycle/}} kommen.
--{{/info}}
++Nach kurzer Wartezeit (beim ersten Mal kann es länger dauern) ist dann ein {{formcycle/}}-Server gestartet. Die URL steht am Ende in der Kommandozeile, standardmäßig http://localhost:8080/xima-formcycle
--{{info}}
--Bis einschließlich Version 7.x von {{formcycle/}} und dem Maven-Plugin ist es noch erforderlich, die package-Phase explizit aufzuführen: {{code}}mvn package fc-server:run-ms-war{{/code}}. Ab Version 8.x geschieht dies automatisch.
--{{/info}}
++Dies funktioniert auch in einem Ordner ohne Maven-Projekt. Falls keine {{formcycle/}} angegeben ist, wird eine Standard-Version genommen. Wird der Befehl innerhalb eines Plugin-Maven-Projekts ausgeführt, wird versucht, die Version von {{formcycle/}} aus dem Plugin-Projekt auszulesen.
--{{info}}
--Die Major- und Minor-Version des Maven-Plugins sollte immer der Major- und Minor-Version des zu startenden {{formcycle case="gen"/}} entsprechen. Für {{formcycle/}} 7.0.x sollte also das Maven-Plugin in Version 7.0.x verwendet werde, für {{formcycle/}} 7.1.x das Maven-Plugin in Version 7.1.x usw.
--{{/info}}
--
--Nach kurzer Wartezeit (beim ersten Mal kann es länger dauern) ist dann ein {{formcycle/}}-Server gestartet. Die URL steht am Ende in der Kommandozeile, standardmäßig http://localhost:8080/xima-formcycle Der Zugang für den Superadmin ist {{code language="plaintext"}}sadmin{{/code}} (Passwort {{code language="plaintext"}}admin{{/code}}), der Zugang für den Mandantadministrator {{code language="plaintext"}}admin{{/code}} (Passwort {{code language="plaintext"}}/admin_{{/code}}).
--
--Falls der Befehl in einem Maven-Projekt eines {{formcycle/}}-Plugins ausgeführt wird, dann wird das Plugin automatisch gebaut und nach dem Starten des Servers hochgeladen und installiert. Zudem wird versucht, die {{formcycle/}}-Version aus dem Plugin-Projekt auszulesen.
--
--Dies funktioniert auch in einem Ordner ohne Maven-Projekt. Falls keine {{formcycle/}}-Version angegeben ist, wird eine Standard-Version genommen, abhängig von der Maven-Plugin-Version.
--

pom.xml

Größe

@@ -1,1 +1,1 @@
--5.7 KB
++6.1 KB

Inhalt

@@ -27,6 +27,14 @@
  		<fc-server-maven-plugin.version>7.0.1</fc-server-maven-plugin.version>
  	</properties>
++	<repositories>
++		<repository>
++			<id>xima</id>
++			<name>fc-plugin-dev</name>
++			<url>http://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
++		</repository>
++	</repositories>
++
  	<dependencies>
  		<!-- Reference FORMCYCLE libraries. The plugin is installed in a running -->
  		<!-- FORMCYCLE system, , so you do not need to include the FORMCYCLE libraries -->
@@ -58,11 +58,20 @@
  		<plugins>
  			<!-- Upload the plugin to a running FORMCYCLE server as part of the Maven build process -->
--			<!-- mvn package fc-deploy:deploy -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin -->
++			<!-- mvn clean install -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin -->
  			<plugin>
  				<groupId>de.xima.fc.maven.plugin</groupId>
  				<artifactId>fc-deploy-plugin-maven-plugin</artifactId>
  				<version>${fc-deploy-plugin-maven-plugin.version}</version>
++				<executions>
++					<execution>
++						<id>upload</id>
++						<phase>install</phase>
++						<goals>
++							<goal>deploy</goal>
++						</goals>
++					</execution>
++				</executions>
  			</plugin>
  			<!-- Start a preconfigured FORMCYCLE server-->