Wiki-Quellcode von Plugin-Entwicklung

Verstecke letzte Bearbeiter

version	line-number	content
1.1	1	{{content/}}
	2
	3
	4	{{formcycle/}} bietet ein Vielzahl von Einstiegspunkten für die Erweiterung der Standard-Funktionalitäten durch Plugins. Basierend auf den einzelnen [[Plugin-Typen>>doc:Formcycle.PluginDevelopment.Types.WebHome]] werden diese zu gewissen Zeitpunkten automatisch oder manuell angesprochen und erlauben es somit von der Ersetzung eigener Platzhalter bis hin zur Implementierung eigener Verarbeitungslogik {{formcycle/}} anzupassen. Als fundamentaler erster Schritt für die Entwicklung eigener Plugins ist hierbei das Erstellen eines entsprechenden Java-Projekts anzusehen.
	5
	6	== API-Dokumentation ==
	7
10.4	8	Die API-Dokumentation für {{formcycle/}} findet sich hier auf unserer Seite: [[JavaScript und JavaDocs>>https://docs.formcycle.eu/]]
1.1	9
3.5	10	== Maven-Setup ==
1.1	11
6.3	12	Zu Beginn der Entwicklung eines Plugins ist es nötig, das entsprechende Entwicklungsprojekt aufzusetzten und zu konfigurieren.
1.1	13
6.3	14	Für letzteres empfehlen wir hierbei das Build-Management-Tool [[Apache Maven>>url:https://maven.apache.org/\|\|rel="__blank"]] zu verwenden. Andere Build-Tools können prinzipiell auch genutzt werden, hier können wir aber keine Hilfe bereitstellen.
1.1	15
3.5	16	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.
1.1	17
4.2	18	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//:
1.1	19
3.3	20	{{panel title="~~~~/.m2/settings.xml" fullwidth="true" initial="hidden" triggerable="true"}}
3.1	21	{{code language="xml"}}
	22	<?xml version="1.0" encoding="UTF-8"?>
	23	<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"
	24	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
1.1	25
3.1	26	<!-- Add XIMA artifactory -->
	27	<profiles>
	28	<profile>
3.4	29	<!-- FORMCYCLE dependencies -->
3.1	30	<repositories>
	31	<repository>
	32	<snapshots>
	33	<enabled>false</enabled>
	34	</snapshots>
	35	<id>xima</id>
5.9	36	<name>fc-plugin-dev</name>
3.1	37	<url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
	38	</repository>
	39	</repositories>
3.4	40	<!-- Maven plugins for FORMCYCLE -->
3.1	41	<pluginRepositories>
	42	<pluginRepository>
	43	<snapshots>
	44	<enabled>false</enabled>
	45	</snapshots>
	46	<id>xima</id>
5.9	47	<name>fc-plugin-dev</name>
3.1	48	<url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
	49	</pluginRepository>
	50	</pluginRepositories>
	51	<id>xima-artifactory</id>
	52	</profile>
	53	</profiles>
1.1	54
3.1	55	<!-- Enable XIMA artifactory by default -->
	56	<activeProfiles>
	57	<activeProfile>xima-artifactory</activeProfile>
	58	</activeProfiles>
1.1	59
3.1	60	<!-- FORMCYCLE specific Maven plugins provided by XIMA -->
	61	<pluginGroups>
	62	<pluginGroup>de.xima.fc.maven.plugin</pluginGroup>
	63	</pluginGroups>
	64	</settings>
	65	{{/code}}
	66	{{/panel}}
1.1	67
10.3	68	== Maven-Projekteinrichtung ==
1.1	69
3.13	70	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"]].
3.8	71
7.2	72	=== Artekfakte und Abhängigkeiten ===
3.5	73
	74	{{info}}
	75	Alle Abhängigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren!
	76	{{/info}}
	77
6.2	78	Eine fertige einfache //pom.xml// können Sie [[hier herunterladen>>attach:pom.xml\|\|rel="__blank"]].
	79
10.3	80	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"]].
3.5	81
	82	In der //pom.xml// des Plugin-Projekts kann diese Abhängigkeit wie folgt eingebunden werden:
	83
3.1	84	{{code language="xml"}}
	85	<properties>
10.15	86	<xfc.version>7.2.1</xfc.version>
3.1	87	</properties>
1.1	88
3.1	89	<dependencies>
	90	<dependency>
	91	<groupId>de.xima.fc</groupId>
	92	<artifactId>fc-plugin-common</artifactId>
	93	<version>${xfc.version}</version>
	94	<scope>provided</scope>
	95	</dependency>
	96	</dependencies>
1.1	97	{{/code}}
	98
6.3	99	Ferner steht je nach Tiefe der Integration in die bestehende Umgebung von {{formcycle case="dat"/}} und deren Benutzung als höchste Implementierung das Artefakt //fc-logic// zur Verfügung. Dieses wird wie folgt als weitere (oder einzige) Abhängigkeit definiert:
1.1	100
	101	{{code language="xml"}}
	102	<dependency>
	103	<groupId>de.xima.fc</groupId>
	104	<artifactId>fc-logic</artifactId>
	105	<version>${xfc.version}</version>
	106	<scope>provided</scope>
	107	</dependency>
	108	{{/code}}
	109
6.2	110	Eine entsprechende Benutzung ist vor allem bei der Verwendung der Datenbankschnittstelle sowie bei der Implementierung von eigenen Verarbeitungen nötig.
1.1	111
10.6	112	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:
1.1	113
10.6	114	{{code language="xml"}}
	115	<dependencyManagement>
	116	<dependencies>
	117	<!--Import dependency versions from FORMCYCLE -->
	118	<dependency>
	119	<groupId>de.xima.fc</groupId>
	120	<artifactId>fc</artifactId>
	121	<version>${xfc.version}</version>
	122	<type>pom</type>
	123	<scope>import</scope>
	124	</dependency>
	125	</dependencies>
	126	</dependencyManagement>
	127	{{/code}}
	128
10.7	129	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.
10.6	130
7.2	131	=== Manifest und Fat JAR ===
1.1	132
3.5	133	In der //META-INF/MANIFEST.MF// in der Plugin-JAR-Datei sollten folgende Informationen stehen:
1.1	134
3.5	135	; formcycle-version-requirement
7.2	136	: Erforderlich. Version von {{formcycle/}}, für die das Plugin gedacht ist. Ist erforderlich, damit {{formcycle/}} bei der Installation die Kompatibilität prüfen kann.
3.5	137	; Implementation-Version
7.2	138	: Erforderlich. Version des Plugins; Diese wird z.B. in der Oberfläche angezeigt.
10.13	139	; Plugin-Key
10.14	140	: Erforderlch. Wird zur Identifizierung des Plugin innherhalb von {{formcycle/}} verwendet, und auch von etwa dem Deploy-Plugin oder Server-Plugin. Empfohlener Wert ist {{code}}${project.groupId}:${project.artifactId}{{/code}}.
3.5	141	; Build-Time oder Build-Timestamp
7.2	142	: Optional. Wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren.
1.1	143
10.13	144	{{info}}
	145	Bis einschließlich Version 7.x von {{formcycle/}} ist noch {{code}}Implementation-Title{{/code}} mit dem gleichen Wert wie {{code}}Plugin-Key{{/code}} erforderlich.
	146	{{/info}}
	147
3.5	148	Diese Informationen können wie unten beschrieben mittels des //maven-assembly-plugin// in die Manifest-Datei geschrieben werden.
	149
	150	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).
	151
	152	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.
	153
	154	Für einfache Plugins ist das //maven-assembly-plugin// ausreichend. Dieses kann in der //pom.xml// wie folgt konfiguriert werden:
	155
3.6	156	{{panel title="maven-assembly-plugin in pom.xml" fullwidth="true" initial="hidden" triggerable="true"}}
3.5	157	{{code language="java"}}
	158	<properties>
	159	<maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
	160	</properties>
	161	<build>
5.10	162	<finalName>${project.artifactId}</finalName>
3.5	163	<plugins>
	164	<plugin>
	165	<groupId>org.apache.maven.plugins</groupId>
	166	<artifactId>maven-assembly-plugin</artifactId>
	167	<version>${maven-assembly-plugin.version}</version>
	168	<executions>
	169	<execution>
	170	<id>fat-jar</id>
	171	<phase>package</phase>
	172	<goals>
	173	<goal>single</goal>
	174	</goals>
	175	<configuration>
5.10	176	<finalName>${project.artifactId}</finalName>
3.5	177	<appendAssemblyId>false</appendAssemblyId>
	178	<descriptorRefs>
	179	<descriptorRef>jar-with-dependencies</descriptorRef>
	180	</descriptorRefs>
	181	<archive>
	182	<manifest>
	183	<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
	184	</manifest>
	185	<manifestEntries>
	186	<formcycle-version-requirement>${xfc-version}</formcycle-version-requirement>
	187	<Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
	188	<Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
	189	<Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
	190	<Implementation-Version>${project.version}</Implementation-Version>
	191	</manifestEntries>
	192	</archive>
	193	</configuration>
	194	</execution>
	195	</executions>
	196	</plugin>
	197	</plugins>
	198	</build>
	199	{{/code}}
3.6	200	{{/panel}}
3.5	201
	202	=== Bauen und Installieren ===
	203
	204	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:
	205
	206	{{code}}
	207	mvn clean install
	208	{{/code}}
	209
3.15	210	Nachdem das Plugin erfolgreich gebaut wurde, kann die so entstandene JAR-Datei im //target//-Verzeichnis in {{formcycle/}} über die Oberfläche [[Mandant-Plugins>>doc:Formcycle.UserInterface.Client.Plugins]] beziehungsweise [[System-Plugins>>doc:Formcycle.SystemSettings.UserInterface.SystemPlugins]] hochgeladen werden.
3.5	211
3.14	212	Siehe [[Deploy-Plugin>>\|\|anchor="HDeploy-Plugin"]] zum automatischen Hochladen beim Maven-Build.
3.5	213
3.14	214	Siehe [[FC-Server-Plugin>>\|\|anchor="HFC-Server-Plugin"]] zum Starten eines einfachen {{formcycle/}}-Servers.
3.5	215
	216	== Maven-Archetypes ==
	217
4.3	218	{{figure image="eclipse-archetype.png" width="500"}}
4.11	219	Hinzufügen des Archetypes-Katalogs in Eclipse
4.2	220	{{/figure}}
3.1	221
5.2	222	{{figure image="eclipse-archetype-select.png" width="500"}}
	223	Auswahl eines Archetypes beim Erstellen eines Maven-Projekts in Eclipse
	224	{{/figure}}
	225
10.3	226	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.
4.2	227
	228	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
	230	{{code}}
	231	mvn archetype:generate -DarchetypeArtifactId=plugin-archetype-workflow-element-simple -DarchetypeGroupId=de.xima.fc.archetype -DarchetypeVersion=7.0.4
	232	{{/code}}
	233
	234	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.
	235
16.1	236	Alle vorhandenen Archetypes und deren Versionen können im [[Archetype-Katalog>>url:https://artifactory.xima-services.de/artifactory/fc-plugin-dev/archetype-catalog.xml\|\|rel="noopener noreferrer" target="_blank"]] eingesehen werden.
4.2	237
4.14	238	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:
4.2	239
10.3	240	{{code language="plaintext"}}
16.1	241	https://artifactory.xima-services.de/artifactory/fc-plugin-dev/archetype-catalog.xml
10.3	242	{{/code}}
4.14	243
7.2	244	== Deploy-Plugin ==
3.5	245
5.5	246	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:
3.5	247
5.5	248	* Ein Maven-Plugin, welches nach dem Bauen das Plugin via HTTP an einen laufenden {{formcycle/}}-Server sendet
	249	* Ein Plugin für {{formcycle/}}, welche die Gegenstelle in {{formcycle/}} bereitstellt und das Plugin aus dem HTTP-Request in {{formcycle/}} installiert.
	250
10.12	251	Weitere Details können im [[Hilfe-Artikel zum Deploy-Plugin>>doc:Formcycle.PluginDocumentation.FormcycleDeployPluginPlugin]] nachgelesen werden. Für die meisten Fälle ist kene Konfiguration in der //pom.xml// erforderlich. Es empfiehlt sich aber, wenigstens die Version festzusetzen:
5.5	252
	253	{{code language="xml"}}
	254	<properties>
15.2	255	<fc-deploy-plugin-maven-plugin.version>7.0.1</fc-deploy-plugin-maven-plugin.version>
5.5	256	<build>
	257	<plugins>
10.3	258	<plugin>
5.5	259	<groupId>de.xima.fc.maven.plugin</groupId>
	260	<artifactId>fc-deploy-plugin-maven-plugin</artifactId>
	261	<version>${fc-deploy-plugin-maven-plugin.version}</version>
	262	</plugin>
	263	</plugins>
	264	</build>
	265	{{/code}}
	266
10.10	267	Sofern das Deploy-Plugin bereits in {{formcycle/}} installiert ist, kann das Plugin-Projekt dann wie folgt gebaut und hochgeladen werden:
5.5	268
	269	{{code language="bash"}}
10.10	270	mvn fc-deploy:deploy
	271	{{/code}}
	272
	273	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:
	274
	275	{{code language="bash"}}
10.2	276	mvn package fc-deploy:deploy -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin
5.5	277	{{/code}}
	278
10.10	279	{{info}}
	280	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.
	281	{{/info}}
	282
10.3	283	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.
3.5	284
5.6	285	== FC-Server-Plugin ==
3.5	286
5.6	287	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.
3.5	288
5.6	289	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:
	290
	291	{{code language="bash"}}
10.5	292	# Aktuelle Version starten
10.8	293	mvn fc-server:run-ms-war
10.5	294
	295	# Spezifische Version starten
	296	mvn de.xima.fc.maven.plugin:fc-server-maven-plugin:7.0.4:run-ms-war -DxfcVersion=7.0.16
5.6	297	{{/code}}
	298
10.5	299	{{info}}
	300	Wir empfehlen die Nutzung von Java 11. Bei Nutzung von Java 17 kann es aktuell zu Problemen beim Starten von {{formcycle/}} kommen.
	301	{{/info}}
	302
	303	{{info}}
10.10	304	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.
10.8	305	{{/info}}
	306
	307	{{info}}
10.5	308	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.
	309	{{/info}}
	310
9.2	311	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}}).
5.6	312
10.9	313	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.
10.8	314
	315	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.
	316
14.2	317	Für fortgeschrittenen Gebrauch siehe die [[README.md>>attach:README-FC-SERVER.md\|\|rel="__blank"]].
12.2	318