| ... |
... |
@@ -8,15 +8,15 @@ |
| 8 |
8 |
|
| 9 |
9 |
Die API-Dokumentation für {{formcycle/}} findet sich hier auf unserer Seite: [[Javadocs>>https://docs.formcycle.eu/]] |
| 10 |
10 |
|
| 11 |
|
-== Maven-Setup == |
|
11 |
+== Projekt-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. |
|
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/]]. |
| 18 |
18 |
|
| 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//: |
|
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 |
|
| 21 |
21 |
{{panel title="~~~~/.m2/settings.xml" fullwidth="true" initial="hidden" triggerable="true"}} |
| 22 |
22 |
{{code language="xml"}} |
| ... |
... |
@@ -66,20 +66,8 @@ |
| 66 |
66 |
{{/code}} |
| 67 |
67 |
{{/panel}} |
| 68 |
68 |
|
| 69 |
|
-== Maven-Projekteinrichtung |
|
69 |
+In der //pom.xml// des Plugin-Projekts kann die Abhängigkeit dann wie folgt eingebunden werden: |
| 70 |
70 |
|
| 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 |
|
- |
| 73 |
|
-=== Artekfakte und Abhängigkeiten |
| 74 |
|
- |
| 75 |
|
-{{info}} |
| 76 |
|
-Alle Abhängigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren! |
| 77 |
|
-{{/info}} |
| 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/]]. |
| 80 |
|
- |
| 81 |
|
-In der //pom.xml// des Plugin-Projekts kann diese Abhängigkeit wie folgt eingebunden werden: |
| 82 |
|
- |
| 83 |
83 |
{{code language="xml"}} |
| 84 |
84 |
<properties> |
| 85 |
85 |
<xfc.version>7.0.10</xfc.version> |
| ... |
... |
@@ -110,113 +110,14 @@ |
| 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 |
|
101 |
+{{info}} |
|
102 |
+Alle Abhangigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren! |
|
103 |
+{{/info}} |
| 114 |
114 |
|
| 115 |
|
-In der //META-INF/MANIFEST.MF// in der Plugin-JAR-Datei sollten folgende Informationen stehen: |
|
105 |
+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]]. |
| 116 |
116 |
|
| 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 |
|
-; Implementation-Version |
| 120 |
|
-: Erforderlich. Version des Plugins, wird etwa in der Oberfläche angezeigt. |
| 121 |
|
-; Build-Time oder Build-Timestamp |
| 122 |
|
-: Optional, wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren. |
| 123 |
|
-; Implementation-Title |
| 124 |
|
-: Optional, wird standardmäßig etwa vom Deploy-Plugin verwendet, um das Plugin zu identifzieren. |
|
107 |
+== Archetypes == |
| 125 |
125 |
|
| 126 |
|
-Diese Informationen können wie unten beschrieben mittels des //maven-assembly-plugin// in die Manifest-Datei geschrieben werden. |
| 127 |
|
- |
| 128 |
|
-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). |
| 129 |
|
- |
| 130 |
|
-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. |
| 131 |
|
- |
| 132 |
|
-Für einfache Plugins ist das //maven-assembly-plugin// ausreichend. Dieses kann in der //pom.xml// wie folgt konfiguriert werden: |
| 133 |
|
- |
| 134 |
|
-{{panel title="maven-assembly-plugin in pom.xml" fullwidth="true" initial="hidden" triggerable="true"}} |
| 135 |
|
-{{code language="java"}} |
| 136 |
|
- <properties> |
| 137 |
|
- <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version> |
| 138 |
|
- </properties> |
| 139 |
|
- <build> |
| 140 |
|
- <finalName>${project.parent.artifactId}</finalName> |
| 141 |
|
- <plugins> |
| 142 |
|
- <plugin> |
| 143 |
|
- <groupId>org.apache.maven.plugins</groupId> |
| 144 |
|
- <artifactId>maven-assembly-plugin</artifactId> |
| 145 |
|
- <version>${maven-assembly-plugin.version}</version> |
| 146 |
|
- <executions> |
| 147 |
|
- <execution> |
| 148 |
|
- <id>fat-jar</id> |
| 149 |
|
- <phase>package</phase> |
| 150 |
|
- <goals> |
| 151 |
|
- <goal>single</goal> |
| 152 |
|
- </goals> |
| 153 |
|
- <configuration> |
| 154 |
|
- <finalName>${project.parent.artifactId}</finalName> |
| 155 |
|
- <appendAssemblyId>false</appendAssemblyId> |
| 156 |
|
- <descriptorRefs> |
| 157 |
|
- <descriptorRef>jar-with-dependencies</descriptorRef> |
| 158 |
|
- </descriptorRefs> |
| 159 |
|
- <archive> |
| 160 |
|
- <manifest> |
| 161 |
|
- <addDefaultImplementationEntries>true</addDefaultImplementationEntries> |
| 162 |
|
- </manifest> |
| 163 |
|
- <manifestEntries> |
| 164 |
|
- <formcycle-version-requirement>${xfc-version}</formcycle-version-requirement> |
| 165 |
|
- <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp> |
| 166 |
|
- <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title> |
| 167 |
|
- <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id> |
| 168 |
|
- <Implementation-Version>${project.version}</Implementation-Version> |
| 169 |
|
- </manifestEntries> |
| 170 |
|
- </archive> |
| 171 |
|
- </configuration> |
| 172 |
|
- </execution> |
| 173 |
|
- </executions> |
| 174 |
|
- </plugin> |
| 175 |
|
- </plugins> |
| 176 |
|
- </build> |
| 177 |
|
-{{/code}} |
| 178 |
|
-{{/panel}} |
| 179 |
|
- |
| 180 |
|
-=== Bauen und Installieren === |
| 181 |
|
- |
| 182 |
|
-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: |
| 183 |
|
- |
| 184 |
|
-{{code}} |
| 185 |
|
- mvn clean install |
| 186 |
|
-{{/code}} |
| 187 |
|
- |
| 188 |
|
-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. |
| 189 |
|
- |
| 190 |
|
-Siehe [[Deploy-Plugin>>||anchor="HDeploy-Plugin"]] zum automatischen Hochladen beim Maven-Build. |
| 191 |
|
- |
| 192 |
|
-Siehe [[FC-Server-Plugin>>||anchor="HFC-Server-Plugin"]] zum Starten eines einfachen {{formcycle/}}-Servers. |
| 193 |
|
- |
| 194 |
|
-== Maven-Archetypes == |
| 195 |
|
- |
| 196 |
|
-{{figure image="eclipse-archetype.png" width="500"}} |
| 197 |
|
- Hinzufügen des Archetypes-Katalogs in Eclipse: https~:~/~/artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml |
| 198 |
|
-{{/figure}} |
| 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 |
|
- |
| 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 |
|
- |
| 204 |
|
-{{code}} |
| 205 |
|
-mvn archetype:generate -DarchetypeArtifactId=plugin-archetype-workflow-element-simple -DarchetypeGroupId=de.xima.fc.archetype -DarchetypeVersion=7.0.4 |
| 206 |
|
-{{/code}} |
| 207 |
|
- |
| 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 |
|
- |
| 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. |
| 211 |
|
- |
| 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 |
|
- |
| 214 |
|
-== Deploy-Plugin |
| 215 |
|
- |
| 216 |
216 |
TODO |
| 217 |
217 |
|
| 218 |
|
-== FC-Server-Plugin |
| 219 |
|
- |
| 220 |
|
-TODO |
| 221 |
|
- |
| 222 |
|
- |
|
111 |
+Um einen besseren Einstieg in die Plugin-Entwicklung zu finden, [[bieten wir auf unserer Downloadseite>>url:https://customer.formcycle.eu/index.php/s/PgdMrNOvbYEzhmr]] |
