Wiki-Quellcode von Plugin-Entwicklung

Zeige letzte Bearbeiter
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
8 Die API-Dokumentation für {{formcycle/}} findet sich hier auf unserer Seite: [[Javadocs>>https://docs.formcycle.eu/]]
9
10 == Maven-Setup ==
11
12 Zu Beginn der Entwicklung eines Plugins ist es nötig, das entsprechende Entwicklungsprojekt aufzusetzten und zu konfigurieren.
13
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.
15
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.
17
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//:
19
20 {{panel title="~~~~/.m2/settings.xml" fullwidth="true" initial="hidden" triggerable="true"}}
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">
25
26 <!-- Add XIMA artifactory -->
27 <profiles>
28 <profile>
29 <!-- FORMCYCLE dependencies -->
30 <repositories>
31 <repository>
32 <snapshots>
33 <enabled>false</enabled>
34 </snapshots>
35 <id>xima</id>
36 <name>fc-plugin-dev</name>
37 <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
38 </repository>
39 </repositories>
40 <!-- Maven plugins for FORMCYCLE -->
41 <pluginRepositories>
42 <pluginRepository>
43 <snapshots>
44 <enabled>false</enabled>
45 </snapshots>
46 <id>xima</id>
47 <name>fc-plugin-dev</name>
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>
54
55 <!-- Enable XIMA artifactory by default -->
56 <activeProfiles>
57 <activeProfile>xima-artifactory</activeProfile>
58 </activeProfiles>
59
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}}
67
68 == Maven-Projekteinrichtung ===
69
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"]].
71
72 === Artekfakte und Abhängigkeiten ===
73
74 {{info}}
75 Alle Abhängigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren!
76 {{/info}}
77
78 Eine fertige einfache //pom.xml// können Sie [[hier herunterladen>>attach:pom.xml||rel="__blank"]].
79
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||target="_blank"]].
81
82 In der //pom.xml// des Plugin-Projekts kann diese Abhängigkeit wie folgt eingebunden werden:
83
84 {{code language="xml"}}
85 <properties>
86 <xfc.version>7.0.10</xfc.version>
87 </properties>
88
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>
97 {{/code}}
98
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:
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
110 Eine entsprechende Benutzung ist vor allem bei der Verwendung der Datenbankschnittstelle sowie bei der Implementierung von eigenen Verarbeitungen nötig.
111
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).
113
114 === Manifest und Fat JAR ===
115
116 In der //META-INF/MANIFEST.MF// in der Plugin-JAR-Datei sollten folgende Informationen stehen:
117
118 ; formcycle-version-requirement
119 : Erforderlich. Version von {{formcycle/}}, für die das Plugin gedacht ist. Ist erforderlich, damit {{formcycle/}} bei der Installation die Kompatibilität prüfen kann.
120 ; Implementation-Version
121 : Erforderlich. Version des Plugins; Diese wird z.B. in der Oberfläche angezeigt.
122 ; Build-Time oder Build-Timestamp
123 : Optional. Wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren.
124 ; Implementation-Title
125 : Optional. Wird standardmäßig etwa vom Deploy-Plugin verwendet, um das Plugin zu identifzieren.
126
127 Diese Informationen können wie unten beschrieben mittels des //maven-assembly-plugin// in die Manifest-Datei geschrieben werden.
128
129 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).
130
131 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.
132
133 Für einfache Plugins ist das //maven-assembly-plugin// ausreichend. Dieses kann in der //pom.xml// wie folgt konfiguriert werden:
134
135 {{panel title="maven-assembly-plugin in pom.xml" fullwidth="true" initial="hidden" triggerable="true"}}
136 {{code language="java"}}
137 <properties>
138 <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
139 </properties>
140 <build>
141 <finalName>${project.artifactId}</finalName>
142 <plugins>
143 <plugin>
144 <groupId>org.apache.maven.plugins</groupId>
145 <artifactId>maven-assembly-plugin</artifactId>
146 <version>${maven-assembly-plugin.version}</version>
147 <executions>
148 <execution>
149 <id>fat-jar</id>
150 <phase>package</phase>
151 <goals>
152 <goal>single</goal>
153 </goals>
154 <configuration>
155 <finalName>${project.artifactId}</finalName>
156 <appendAssemblyId>false</appendAssemblyId>
157 <descriptorRefs>
158 <descriptorRef>jar-with-dependencies</descriptorRef>
159 </descriptorRefs>
160 <archive>
161 <manifest>
162 <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
163 </manifest>
164 <manifestEntries>
165 <formcycle-version-requirement>${xfc-version}</formcycle-version-requirement>
166 <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
167 <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
168 <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
169 <Implementation-Version>${project.version}</Implementation-Version>
170 </manifestEntries>
171 </archive>
172 </configuration>
173 </execution>
174 </executions>
175 </plugin>
176 </plugins>
177 </build>
178 {{/code}}
179 {{/panel}}
180
181 === Bauen und Installieren ===
182
183 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:
184
185 {{code}}
186 mvn clean install
187 {{/code}}
188
189 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.
190
191 Siehe [[Deploy-Plugin>>||anchor="HDeploy-Plugin"]] zum automatischen Hochladen beim Maven-Build.
192
193 Siehe [[FC-Server-Plugin>>||anchor="HFC-Server-Plugin"]] zum Starten eines einfachen {{formcycle/}}-Servers.
194
195 == Maven-Archetypes ==
196
197 {{figure image="eclipse-archetype.png" width="500"}}
198 Hinzufügen des Archetypes-Katalogs in Eclipse
199 {{/figure}}
200
201 {{figure image="eclipse-archetype-select.png" width="500"}}
202 Auswahl eines Archetypes beim Erstellen eines Maven-Projekts in Eclipse
203 {{/figure}}
204
205 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.
206
207 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:
208
209 {{code}}
210 mvn archetype:generate -DarchetypeArtifactId=plugin-archetype-workflow-element-simple -DarchetypeGroupId=de.xima.fc.archetype -DarchetypeVersion=7.0.4
211 {{/code}}
212
213 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.
214
215 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.
216
217 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:
218
219 {{code language="plaintext"}}https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml{{/code}}
220
221 == Deploy-Plugin ==
222
223 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:
224
225 * Ein Maven-Plugin, welches nach dem Bauen das Plugin via HTTP an einen laufenden {{formcycle/}}-Server sendet
226 * Ein Plugin für {{formcycle/}}, welche die Gegenstelle in {{formcycle/}} bereitstellt und das Plugin aus dem HTTP-Request in {{formcycle/}} installiert.
227
228 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:
229
230 {{code language="xml"}}
231 <properties>
232 <fc-deploy-plugin-maven-plugin.version>7.0.1<fc-deploy-plugin-maven-plugin.version/>
233 <build>
234 <plugins>
235 <plugin>
236 <groupId>de.xima.fc.maven.plugin</groupId>
237 <artifactId>fc-deploy-plugin-maven-plugin</artifactId>
238 <version>${fc-deploy-plugin-maven-plugin.version}</version>
239 <executions>
240 <execution>
241 <id>upload</id>
242 <phase>package</phase>
243 <goals>
244 <goal>deploy</goal>
245 </goals>
246 </execution>
247 </executions>
248 </plugin>
249 </plugins>
250 </build>
251 {{/code}}
252
253 Sofern das Deploy-Plugin bereits in {{formcycle/}} installiert ist, kann das Plugin-Projekt dann beim Bauen wie folgt hochgeladen werden:
254
255 {{code language="bash"}}
256 mvn package -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin
257 {{/code}}
258
259 Wird Eclipse benutzt, kann auch eine Launch-Configuration mit den //fcDeployUrl// und dem //fcDeployToken// angelegt werden.
260
261 == FC-Server-Plugin ==
262
263 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.
264
265 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:
266
267 {{code language="bash"}}
268 mvn package fc-server:run-ms-war -DxfcVersion=7.0.10
269 {{/code}}
270
271 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}}).
272
273 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.