Änderungen von Dokument Plugin-Entwicklung

Zusammenfassung

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

Details

Seiteneigenschaften

Inhalt

...	...	@@ -8,13 +8,13 @@
8	8
9	9	Die API-Dokumentation für {{formcycle/}} findet sich hier auf unserer Seite: [[Javadocs>>https://docs.formcycle.eu/]]
10	10
11		-== Projekt-Setup ==
	11	+== Maven-Setup ==
12	12
13	13	Zu Beginn der Entwicklung eines Plugins ist es nötig das entsprechende Entwicklungsprojekt aufzusetzten und zu konfigurieren.
14	14
15	15	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.
16	16
17		-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/]].
	17	+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.
18	18
19	19	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//:
20	20
...	...	@@ -27,6 +27,7 @@
27	27	<!-- Add XIMA artifactory -->
28	28	<profiles>
29	29	<profile>
	30	+ <!-- FORMCYCLE dependencies -->
30	30	<repositories>
31	31	<repository>
32	32	<snapshots>
...	...	@@ -37,6 +37,7 @@
37	37	<url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
38	38	</repository>
39	39	</repositories>
	41	+ <!-- Maven plugins for FORMCYCLE -->
40	40	<pluginRepositories>
41	41	<pluginRepository>
42	42	<snapshots>
...	...	@@ -64,8 +64,18 @@
64	64	{{/code}}
65	65	{{/panel}}
66	66
67		-In der //pom.xml// des Plugin-Projekts kann die Abhängigkeit dann wie folgt eingebunden werden:
	69	+== Projekt-Setup
68	68
	71	+=== Artekfakte und Abhängigkeiten
	72	+
	73	+{{info}}
	74	+Alle Abhängigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren!
	75	+{{/info}}
	76	+
	77	+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/]].
	78	+
	79	+In der //pom.xml// des Plugin-Projekts kann diese Abhängigkeit wie folgt eingebunden werden:
	80	+
69	69	{{code language="xml"}}
70	70	<properties>
71	71	<xfc.version>7.0.10</xfc.version>
...	...	@@ -96,14 +96,97 @@
96	96
97	97	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).
98	98
99		-{{info}}
100		-Alle Abhangigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren!
101		-{{/info}}
	111	+=== Manifest und Fat JAR
102	102
103		-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]].
	113	+In der //META-INF/MANIFEST.MF// in der Plugin-JAR-Datei sollten folgende Informationen stehen:
104	104
105		-== Archetypes ==
	115	+; formcycle-version-requirement
	116	+: Erforderlich. Version von {{formcycle/}}, für die das Plugin gedacht ist.Ist erforderlich, damit {{formcycle/}} bei der Installation die Kompatibilität prüfen kann.
	117	+; Implementation-Version
	118	+: Erforderlich. Version des Plugins, wird etwa in der Oberfläche angezeigt.
	119	+; Build-Time oder Build-Timestamp
	120	+: Optional, wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren.
	121	+; Implementation-Title
	122	+: Optional, wird standardmäßig etwa vom Deploy-Plugin verwendet, um das Plugin zu identifzieren.
106	106
	124	+Diese Informationen können wie unten beschrieben mittels des //maven-assembly-plugin// in die Manifest-Datei geschrieben werden.
	125	+
	126	+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).
	127	+
	128	+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.
	129	+
	130	+Für einfache Plugins ist das //maven-assembly-plugin// ausreichend. Dieses kann in der //pom.xml// wie folgt konfiguriert werden:
	131	+
	132	+{{code language="java"}}
	133	+ <properties>
	134	+ <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
	135	+ </properties>
	136	+ <build>
	137	+ <finalName>${project.parent.artifactId}</finalName>
	138	+ <plugins>
	139	+ <plugin>
	140	+ <groupId>org.apache.maven.plugins</groupId>
	141	+ <artifactId>maven-assembly-plugin</artifactId>
	142	+ <version>${maven-assembly-plugin.version}</version>
	143	+ <executions>
	144	+ <execution>
	145	+ <id>fat-jar</id>
	146	+ <phase>package</phase>
	147	+ <goals>
	148	+ <goal>single</goal>
	149	+ </goals>
	150	+ <configuration>
	151	+ <finalName>${project.parent.artifactId}</finalName>
	152	+ <appendAssemblyId>false</appendAssemblyId>
	153	+ <descriptorRefs>
	154	+ <descriptorRef>jar-with-dependencies</descriptorRef>
	155	+ </descriptorRefs>
	156	+ <archive>
	157	+ <manifest>
	158	+ <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
	159	+ </manifest>
	160	+ <manifestEntries>
	161	+ <formcycle-version-requirement>${xfc-version}</formcycle-version-requirement>
	162	+ <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
	163	+ <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
	164	+ <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
	165	+ <Implementation-Version>${project.version}</Implementation-Version>
	166	+ </manifestEntries>
	167	+ </archive>
	168	+ </configuration>
	169	+ </execution>
	170	+ </executions>
	171	+ </plugin>
	172	+ </plugins>
	173	+ </build>
	174	+{{/code}}
	175	+
	176	+=== Bauen und Installieren ===
	177	+
	178	+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:
	179	+
	180	+{{code}}
	181	+ mvn clean install
	182	+{{/code}}
	183	+
	184	+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.
	185	+
	186	+Zum automatischen Hochladen gibt es zudem das Deploy-Plugin, siehe unten.
	187	+
	188	+Zum Starten eines einfachen {{formcycle}}-Servers gibt es das FC-Server-Plugin, siehe ebenfalls unten.
	189	+
	190	+== Maven-Archetypes ==
	191	+
107	107	TODO
108	108
109	109	Um einen besseren Einstieg in die Plugin-Entwicklung zu finden, [[bieten wir auf unserer Downloadseite>>url:https://customer.formcycle.eu/index.php/s/PgdMrNOvbYEzhmr]]
	195	+
	196	+== Deploy-Plugin
	197	+
	198	+TODO
	199	+
	200	+== FC-Server-Plugin
	201	+
	202	+TODO
	203	+
	204	+