| ... |
... |
@@ -1,6 +1,5 @@ |
| 1 |
1 |
{{content/}} |
| 2 |
2 |
|
| 3 |
|
-== Plugins für zusätzliche Funktionalitäten == |
| 4 |
4 |
|
| 5 |
5 |
{{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. |
| 6 |
6 |
|
| ... |
... |
@@ -10,9 +10,9 @@ |
| 10 |
10 |
|
| 11 |
11 |
== Maven-Setup == |
| 12 |
12 |
|
| 13 |
|
-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. |
| 14 |
14 |
|
| 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. |
|
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. |
| 16 |
16 |
|
| 17 |
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 |
|
| ... |
... |
@@ -34,7 +34,7 @@ |
| 34 |
34 |
<enabled>false</enabled> |
| 35 |
35 |
</snapshots> |
| 36 |
36 |
<id>xima</id> |
| 37 |
|
- <name>libs-release</name> |
|
36 |
+ <name>fc-plugin-dev</name> |
| 38 |
38 |
<url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url> |
| 39 |
39 |
</repository> |
| 40 |
40 |
</repositories> |
| ... |
... |
@@ -45,7 +45,7 @@ |
| 45 |
45 |
<enabled>false</enabled> |
| 46 |
46 |
</snapshots> |
| 47 |
47 |
<id>xima</id> |
| 48 |
|
- <name>plugins-release</name> |
|
47 |
+ <name>fc-plugin-dev</name> |
| 49 |
49 |
<url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url> |
| 50 |
50 |
</pluginRepository> |
| 51 |
51 |
</pluginRepositories> |
| ... |
... |
@@ -66,18 +66,20 @@ |
| 66 |
66 |
{{/code}} |
| 67 |
67 |
{{/panel}} |
| 68 |
68 |
|
| 69 |
|
-== Maven-Projekteinrichtung |
|
68 |
+== Maven-Projekteinrichtung === |
| 70 |
70 |
|
| 71 |
71 |
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"]]. |
| 72 |
72 |
|
| 73 |
|
-=== Artekfakte und Abhängigkeiten |
|
72 |
+=== Artekfakte und Abhängigkeiten === |
| 74 |
74 |
|
| 75 |
75 |
{{info}} |
| 76 |
76 |
Alle Abhängigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren! |
| 77 |
77 |
{{/info}} |
| 78 |
78 |
|
| 79 |
|
-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 |
+Eine fertige einfache //pom.xml// können Sie [[hier herunterladen>>attach:pom.xml||rel="__blank"]]. |
| 80 |
80 |
|
|
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 |
+ |
| 81 |
81 |
In der //pom.xml// des Plugin-Projekts kann diese Abhängigkeit wie folgt eingebunden werden: |
| 82 |
82 |
|
| 83 |
83 |
{{code language="xml"}} |
| ... |
... |
@@ -95,7 +95,7 @@ |
| 95 |
95 |
</dependencies> |
| 96 |
96 |
{{/code}} |
| 97 |
97 |
|
| 98 |
|
-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: |
| 99 |
99 |
|
| 100 |
100 |
{{code language="xml"}} |
| 101 |
101 |
<dependency> |
| ... |
... |
@@ -106,22 +106,22 @@ |
| 106 |
106 |
</dependency> |
| 107 |
107 |
{{/code}} |
| 108 |
108 |
|
| 109 |
|
-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. |
| 110 |
110 |
|
| 111 |
111 |
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 |
112 |
|
| 113 |
|
-=== Manifest und Fat JAR |
|
114 |
+=== Manifest und Fat JAR === |
| 114 |
114 |
|
| 115 |
115 |
In der //META-INF/MANIFEST.MF// in der Plugin-JAR-Datei sollten folgende Informationen stehen: |
| 116 |
116 |
|
| 117 |
117 |
; formcycle-version-requirement |
| 118 |
|
-: Erforderlich. Version von {{formcycle/}}, für die das Plugin gedacht ist.Ist erforderlich, damit {{formcycle/}} bei der Installation die Kompatibilität prüfen kann. |
|
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. |
| 119 |
119 |
; Implementation-Version |
| 120 |
|
-: Erforderlich. Version des Plugins, wird etwa in der Oberfläche angezeigt. |
|
121 |
+: Erforderlich. Version des Plugins; Diese wird z.B. in der Oberfläche angezeigt. |
| 121 |
121 |
; Build-Time oder Build-Timestamp |
| 122 |
|
-: Optional, wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren. |
|
123 |
+: Optional. Wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren. |
| 123 |
123 |
; Implementation-Title |
| 124 |
|
-: Optional, wird standardmäßig etwa vom Deploy-Plugin verwendet, um das Plugin zu identifzieren. |
|
125 |
+: Optional. Wird standardmäßig etwa vom Deploy-Plugin verwendet, um das Plugin zu identifzieren. |
| 125 |
125 |
|
| 126 |
126 |
Diese Informationen können wie unten beschrieben mittels des //maven-assembly-plugin// in die Manifest-Datei geschrieben werden. |
| 127 |
127 |
|
| ... |
... |
@@ -137,7 +137,7 @@ |
| 137 |
137 |
<maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version> |
| 138 |
138 |
</properties> |
| 139 |
139 |
<build> |
| 140 |
|
- <finalName>${project.parent.artifactId}</finalName> |
|
141 |
+ <finalName>${project.artifactId}</finalName> |
| 141 |
141 |
<plugins> |
| 142 |
142 |
<plugin> |
| 143 |
143 |
<groupId>org.apache.maven.plugins</groupId> |
| ... |
... |
@@ -151,7 +151,7 @@ |
| 151 |
151 |
<goal>single</goal> |
| 152 |
152 |
</goals> |
| 153 |
153 |
<configuration> |
| 154 |
|
- <finalName>${project.parent.artifactId}</finalName> |
|
155 |
+ <finalName>${project.artifactId}</finalName> |
| 155 |
155 |
<appendAssemblyId>false</appendAssemblyId> |
| 156 |
156 |
<descriptorRefs> |
| 157 |
157 |
<descriptorRef>jar-with-dependencies</descriptorRef> |
| ... |
... |
@@ -197,8 +197,12 @@ |
| 197 |
197 |
Hinzufügen des Archetypes-Katalogs in Eclipse |
| 198 |
198 |
{{/figure}} |
| 199 |
199 |
|
| 200 |
|
-Für einige häufig verwendete Plugin-Typen stehen [[Maven-Archetypes>>url:https://maven.apache.org/guides/introduction/introduction-to-archetypes.html]] bereits, um schnell ein Maven-Projekt aufsetzen zu können. |
|
201 |
+{{figure image="eclipse-archetype-select.png" width="500"}} |
|
202 |
+ Auswahl eines Archetypes beim Erstellen eines Maven-Projekts in Eclipse |
|
203 |
+{{/figure}} |
| 201 |
201 |
|
|
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 |
+ |
| 202 |
202 |
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: |
| 203 |
203 |
|
| 204 |
204 |
{{code}} |
| ... |
... |
@@ -207,18 +207,63 @@ |
| 207 |
207 |
|
| 208 |
208 |
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. |
| 209 |
209 |
|
| 210 |
|
-Alle vorhandenen Archetypes und deren Versionen können im [[Archetype-Katalog>>url:https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml]] eingesehen werden. |
|
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. |
| 211 |
211 |
|
| 212 |
212 |
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: |
| 213 |
213 |
|
| 214 |
214 |
{{code language="plaintext"}}https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml{{/code}} |
| 215 |
215 |
|
| 216 |
|
-== Deploy-Plugin |
|
221 |
+== Deploy-Plugin == |
| 217 |
217 |
|
| 218 |
|
-TODO |
|
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: |
| 219 |
219 |
|
| 220 |
|
-== FC-Server-Plugin |
|
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. |
| 221 |
221 |
|
| 222 |
|
-TODO |
|
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: |
| 223 |
223 |
|
|
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}} |
| 224 |
224 |
|
|
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 |
|
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. |
|
274 |
+ |
