| ... |
... |
@@ -5,13 +5,13 @@ |
| 5 |
5 |
|
| 6 |
6 |
== API-Dokumentation == |
| 7 |
7 |
|
| 8 |
|
-Die API-Dokumentation für {{formcycle/}} findet sich hier auf unserer Seite: [[Javadocs>>https://docs.formcycle.eu/]] |
|
8 |
+Die API-Dokumentation für {{formcycle/}} findet sich hier auf unserer Seite: [[JavaScript und JavaDocs>>https://docs.formcycle.eu/]] |
| 9 |
9 |
|
| 10 |
10 |
== Maven-Setup == |
| 11 |
11 |
|
| 12 |
|
-Zu Beginn der Entwicklung eines Plugins ist es nötig das entsprechende Entwicklungsprojekt aufzusetzten und zu konfigurieren. |
|
12 |
+Zu Beginn der Entwicklung eines Plugins ist es nötig, das entsprechende Entwicklungsprojekt aufzusetzten und zu konfigurieren. |
| 13 |
13 |
|
| 14 |
|
-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. |
|
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 |
15 |
|
| 16 |
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 |
17 |
|
| ... |
... |
@@ -65,23 +65,25 @@ |
| 65 |
65 |
{{/code}} |
| 66 |
66 |
{{/panel}} |
| 67 |
67 |
|
| 68 |
|
-== Maven-Projekteinrichtung |
|
68 |
+== Maven-Projekteinrichtung == |
| 69 |
69 |
|
| 70 |
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 |
71 |
|
| 72 |
|
-=== Artekfakte und Abhängigkeiten |
|
72 |
+=== Artekfakte und Abhängigkeiten === |
| 73 |
73 |
|
| 74 |
74 |
{{info}} |
| 75 |
75 |
Alle Abhängigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren! |
| 76 |
76 |
{{/info}} |
| 77 |
77 |
|
| 78 |
|
-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||target="_blank"]]. |
|
78 |
+Eine fertige einfache //pom.xml// können Sie [[hier herunterladen>>attach:pom.xml||rel="__blank"]]. |
| 79 |
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||rel="noopener noreferrer" target="_blank"]]. |
|
81 |
+ |
| 80 |
80 |
In der //pom.xml// des Plugin-Projekts kann diese Abhängigkeit wie folgt eingebunden werden: |
| 81 |
81 |
|
| 82 |
82 |
{{code language="xml"}} |
| 83 |
83 |
<properties> |
| 84 |
|
- <xfc.version>7.0.10</xfc.version> |
|
86 |
+ <xfc.version>7.2.1</xfc.version> |
| 85 |
85 |
</properties> |
| 86 |
86 |
|
| 87 |
87 |
<dependencies> |
| ... |
... |
@@ -94,7 +94,7 @@ |
| 94 |
94 |
</dependencies> |
| 95 |
95 |
{{/code}} |
| 96 |
96 |
|
| 97 |
|
-Ferner steht je nach Tiefe der Integration in die bestehende Umgebung von {{formcycle case="dat"/}} und dessen Benutzung als höchste Implementierung das Artefakt //fc-logic// zur Verfügung. Dieses wird wie folgt als weitere (oder einzige) Abhängigkeit definiert: |
|
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: |
| 98 |
98 |
|
| 99 |
99 |
{{code language="xml"}} |
| 100 |
100 |
<dependency> |
| ... |
... |
@@ -105,23 +105,44 @@ |
| 105 |
105 |
</dependency> |
| 106 |
106 |
{{/code}} |
| 107 |
107 |
|
| 108 |
|
-Eine entsprechende Benutzung ist vor allem bei der Verwendung der Datenbankschnittstelle sowie bei der Implementierung von eigenen Verarbeitungen nötig. Eine Vorlage für ein somit entstehendes Project Object Model finden Sie [[hier>>attach:pom.xml||rel="__blank"]]. |
|
110 |
+Eine entsprechende Benutzung ist vor allem bei der Verwendung der Datenbankschnittstelle sowie bei der Implementierung von eigenen Verarbeitungen nötig. |
| 109 |
109 |
|
| 110 |
|
-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). |
|
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: |
| 111 |
111 |
|
| 112 |
|
-=== Manifest und Fat JAR |
|
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}} |
| 113 |
113 |
|
|
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. |
|
130 |
+ |
|
131 |
+=== Manifest und Fat JAR === |
|
132 |
+ |
| 114 |
114 |
In der //META-INF/MANIFEST.MF// in der Plugin-JAR-Datei sollten folgende Informationen stehen: |
| 115 |
115 |
|
| 116 |
116 |
; formcycle-version-requirement |
| 117 |
|
-: Erforderlich. Version von {{formcycle/}}, für die das Plugin gedacht ist.Ist erforderlich, damit {{formcycle/}} bei der Installation die Kompatibilität prüfen kann. |
|
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. |
| 118 |
118 |
; Implementation-Version |
| 119 |
|
-: Erforderlich. Version des Plugins, wird etwa in der Oberfläche angezeigt. |
|
138 |
+: Erforderlich. Version des Plugins; Diese wird z.B. in der Oberfläche angezeigt. |
|
139 |
+; Plugin-Key |
|
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}}. |
| 120 |
120 |
; Build-Time oder Build-Timestamp |
| 121 |
|
-: Optional, wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren. |
| 122 |
|
-; Implementation-Title |
| 123 |
|
-: Optional, wird standardmäßig etwa vom Deploy-Plugin verwendet, um das Plugin zu identifzieren. |
|
142 |
+: Optional. Wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren. |
| 124 |
124 |
|
|
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 |
+ |
| 125 |
125 |
Diese Informationen können wie unten beschrieben mittels des //maven-assembly-plugin// in die Manifest-Datei geschrieben werden. |
| 126 |
126 |
|
| 127 |
127 |
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). |
| ... |
... |
@@ -200,7 +200,7 @@ |
| 200 |
200 |
Auswahl eines Archetypes beim Erstellen eines Maven-Projekts in Eclipse |
| 201 |
201 |
{{/figure}} |
| 202 |
202 |
|
| 203 |
|
-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. |
|
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. |
| 204 |
204 |
|
| 205 |
205 |
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: |
| 206 |
206 |
|
| ... |
... |
@@ -210,13 +210,15 @@ |
| 210 |
210 |
|
| 211 |
211 |
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. |
| 212 |
212 |
|
| 213 |
|
-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. |
|
236 |
+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. |
| 214 |
214 |
|
| 215 |
215 |
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: |
| 216 |
216 |
|
| 217 |
|
-{{code language="plaintext"}}https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml{{/code}} |
|
240 |
+{{code language="plaintext"}} |
|
241 |
+https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml |
|
242 |
+{{/code}} |
| 218 |
218 |
|
| 219 |
|
-== Deploy-Plugin |
|
244 |
+== Deploy-Plugin == |
| 220 |
220 |
|
| 221 |
221 |
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: |
| 222 |
222 |
|
| ... |
... |
@@ -223,39 +223,40 @@ |
| 223 |
223 |
* Ein Maven-Plugin, welches nach dem Bauen das Plugin via HTTP an einen laufenden {{formcycle/}}-Server sendet |
| 224 |
224 |
* Ein Plugin für {{formcycle/}}, welche die Gegenstelle in {{formcycle/}} bereitstellt und das Plugin aus dem HTTP-Request in {{formcycle/}} installiert. |
| 225 |
225 |
|
| 226 |
|
-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: |
|
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: |
| 227 |
227 |
|
| 228 |
228 |
{{code language="xml"}} |
| 229 |
229 |
<properties> |
| 230 |
|
- <fc-deploy-plugin-maven-plugin.version>7.0.1<fc-deploy-plugin-maven-plugin.version/> |
|
255 |
+ <fc-deploy-plugin-maven-plugin.version>7.0.1<fc-deploy-plugin-maven-plugin.version></fc-deploy-plugin-maven-plugin> |
| 231 |
231 |
<build> |
| 232 |
232 |
<plugins> |
| 233 |
|
- <plugin> |
|
258 |
+ <plugin> |
| 234 |
234 |
<groupId>de.xima.fc.maven.plugin</groupId> |
| 235 |
235 |
<artifactId>fc-deploy-plugin-maven-plugin</artifactId> |
| 236 |
236 |
<version>${fc-deploy-plugin-maven-plugin.version}</version> |
| 237 |
|
- <executions> |
| 238 |
|
- <execution> |
| 239 |
|
- <id>upload</id> |
| 240 |
|
- <phase>install</phase> |
| 241 |
|
- <goals> |
| 242 |
|
- <goal>deploy</goal> |
| 243 |
|
- </goals> |
| 244 |
|
- </execution> |
| 245 |
|
- </executions> |
| 246 |
246 |
</plugin> |
| 247 |
247 |
</plugins> |
| 248 |
248 |
</build> |
| 249 |
249 |
{{/code}} |
| 250 |
250 |
|
| 251 |
|
-Sofern das Deploy-Plugin bereits in {{formcycle/}} installiert ist, kann das Plugin-Projekt dann beim Bauen wie folgt hochgeladen werden: |
|
267 |
+Sofern das Deploy-Plugin bereits in {{formcycle/}} installiert ist, kann das Plugin-Projekt dann wie folgt gebaut und hochgeladen werden: |
| 252 |
252 |
|
| 253 |
253 |
{{code language="bash"}} |
| 254 |
|
-mvn clean install -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin |
|
270 |
+mvn fc-deploy:deploy |
| 255 |
255 |
{{/code}} |
| 256 |
256 |
|
| 257 |
|
-Wird Eclipse benutzt, kann auch eine Launch-Configuration mit den //fcDeployUrl// und dem //fcDeployToken// angelegt werden. |
|
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: |
| 258 |
258 |
|
|
275 |
+{{code language="bash"}} |
|
276 |
+mvn package fc-deploy:deploy -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin |
|
277 |
+{{/code}} |
|
278 |
+ |
|
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 |
+ |
|
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. |
|
284 |
+ |
| 259 |
259 |
== FC-Server-Plugin == |
| 260 |
260 |
|
| 261 |
261 |
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. |
| ... |
... |
@@ -263,10 +263,28 @@ |
| 263 |
263 |
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: |
| 264 |
264 |
|
| 265 |
265 |
{{code language="bash"}} |
| 266 |
|
-mvn fc-server:run-ms-war -DxfcVersion=7.0.10 |
|
292 |
+# Aktuelle Version starten |
|
293 |
+mvn fc-server:run-ms-war |
|
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 |
| 267 |
267 |
{{/code}} |
| 268 |
268 |
|
| 269 |
|
-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 |
|
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}} |
| 270 |
270 |
|
| 271 |
|
-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. |
|
303 |
+{{info}} |
|
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. |
|
305 |
+{{/info}} |
| 272 |
272 |
|
|
307 |
+{{info}} |
|
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 |
+ |
|
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}}). |
|
312 |
+ |
|
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. |
|
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 |
+ |
