Wiki-Quellcode von Plugin-Entwicklung

Zeige letzte Bearbeiter
1 {{content/}}
2
3 == Plugins für zusätzliche Funktionalitäten ==
4
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
7 == API-Dokumentation ==
8
9 Die API-Dokumentation für {{formcycle/}} findet sich hier auf unserer Seite: [[Javadocs>>https://docs.formcycle.eu/]]
10
11 == Maven-Setup ==
12
13 Zu Beginn der Entwicklung eines Plugins ist es nötig das entsprechende Entwicklungsprojekt aufzusetzten und zu konfigurieren.
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.
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.
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//:
20
21 {{panel title="~~~~/.m2/settings.xml" fullwidth="true" initial="hidden" triggerable="true"}}
22 {{code language="xml"}}
23 <?xml version="1.0" encoding="UTF-8"?>
24 <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"
25 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
26
27 <!-- Add XIMA artifactory -->
28 <profiles>
29 <profile>
30 <!-- FORMCYCLE dependencies -->
31 <repositories>
32 <repository>
33 <snapshots>
34 <enabled>false</enabled>
35 </snapshots>
36 <id>xima</id>
37 <name>libs-release</name>
38 <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
39 </repository>
40 </repositories>
41 <!-- Maven plugins for FORMCYCLE -->
42 <pluginRepositories>
43 <pluginRepository>
44 <snapshots>
45 <enabled>false</enabled>
46 </snapshots>
47 <id>xima</id>
48 <name>plugins-release</name>
49 <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
50 </pluginRepository>
51 </pluginRepositories>
52 <id>xima-artifactory</id>
53 </profile>
54 </profiles>
55
56 <!-- Enable XIMA artifactory by default -->
57 <activeProfiles>
58 <activeProfile>xima-artifactory</activeProfile>
59 </activeProfiles>
60
61 <!-- FORMCYCLE specific Maven plugins provided by XIMA -->
62 <pluginGroups>
63 <pluginGroup>de.xima.fc.maven.plugin</pluginGroup>
64 </pluginGroups>
65 </settings>
66 {{/code}}
67 {{/panel}}
68
69 == Projekt-Setup
70
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
81 {{code language="xml"}}
82 <properties>
83 <xfc.version>7.0.10</xfc.version>
84 </properties>
85
86 <dependencies>
87 <dependency>
88 <groupId>de.xima.fc</groupId>
89 <artifactId>fc-plugin-common</artifactId>
90 <version>${xfc.version}</version>
91 <scope>provided</scope>
92 </dependency>
93 </dependencies>
94 {{/code}}
95
96 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:
97
98 {{code language="xml"}}
99 <dependency>
100 <groupId>de.xima.fc</groupId>
101 <artifactId>fc-logic</artifactId>
102 <version>${xfc.version}</version>
103 <scope>provided</scope>
104 </dependency>
105 {{/code}}
106
107 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"]].
108
109 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).
110
111 === Manifest und Fat JAR
112
113 In der //META-INF/MANIFEST.MF// in der Plugin-JAR-Datei sollten folgende Informationen stehen:
114
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.
123
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 {{panel title="maven-assembly-plugin in pom.xml" fullwidth="true" initial="hidden" triggerable="true"}}
133 {{code language="java"}}
134 <properties>
135 <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
136 </properties>
137 <build>
138 <finalName>${project.parent.artifactId}</finalName>
139 <plugins>
140 <plugin>
141 <groupId>org.apache.maven.plugins</groupId>
142 <artifactId>maven-assembly-plugin</artifactId>
143 <version>${maven-assembly-plugin.version}</version>
144 <executions>
145 <execution>
146 <id>fat-jar</id>
147 <phase>package</phase>
148 <goals>
149 <goal>single</goal>
150 </goals>
151 <configuration>
152 <finalName>${project.parent.artifactId}</finalName>
153 <appendAssemblyId>false</appendAssemblyId>
154 <descriptorRefs>
155 <descriptorRef>jar-with-dependencies</descriptorRef>
156 </descriptorRefs>
157 <archive>
158 <manifest>
159 <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
160 </manifest>
161 <manifestEntries>
162 <formcycle-version-requirement>${xfc-version}</formcycle-version-requirement>
163 <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
164 <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
165 <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
166 <Implementation-Version>${project.version}</Implementation-Version>
167 </manifestEntries>
168 </archive>
169 </configuration>
170 </execution>
171 </executions>
172 </plugin>
173 </plugins>
174 </build>
175 {{/code}}
176 {{/panel}}
177
178 === Bauen und Installieren ===
179
180 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:
181
182 {{code}}
183 mvn clean install
184 {{/code}}
185
186 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.
187
188 Zum automatischen Hochladen gibt es zudem das Deploy-Plugin, siehe unten.
189
190 Zum Starten eines einfachen {{formcycle}}-Servers gibt es das FC-Server-Plugin, siehe ebenfalls unten.
191
192 == Maven-Archetypes ==
193
194 TODO
195
196 Um einen besseren Einstieg in die Plugin-Entwicklung zu finden, [[bieten wir auf unserer Downloadseite>>url:https://customer.formcycle.eu/index.php/s/PgdMrNOvbYEzhmr]]
197
198 == Deploy-Plugin
199
200 TODO
201
202 == FC-Server-Plugin
203
204 TODO
205