Wiki source code of Plugin-Entwicklung

Show last authors
1 {{content/}}
2
3 Plugins let you extend {{formcycle/}} and add new features. Various different [[plugin type>>doc:Formcycle.PluginDevelopment.Types.WebHome]] exist, such as plugins for adding custom workflow actions ands triggers, or plugins for new form elements.
4
5 A plugin must be a JAR file with the appropriate class files. To create a custom plugin, you need to setup a Java project, such as via Maven.
6
7 == API documentation ==
8
9 The API documentations for {{formcycle/}} can be found here: [[Javadocs>>https://docs.formcycle.eu/]]
10
11 == Project setup ==
12
13 To get started with developing plugins, you need to create and configure new project.
14
15 We recommend the build tool [[Apache Maven>>url:https://maven.apache.org/||rel="__blank"]]. Other build tools such as Gradle are possible, but you will not find any help for those tools here.
16
17 To access the {{formcycle case="dat"/}} dependencies, you need to use the Maven repository [[https:~~/~~/artifactory.xima-services.de/artifactory/fc-plugin-dev>>url:https://artifactory.xima-services.de/artifactory/fc-plugin-dev]]. This contains all Maven artifacts required for developing plugins.
18
19 To get Maven to recognize that repository, add it tot the Maven configuration file //settings.xml//. Usually, you can find this settings file in the //.m2// folder in your home directory, i.e. //~~/.m2/settings.xml// for Linux and //%homepath%\.m2\settings.xml// for Windows:
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>fc-plugin-dev</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>fc-plugin-dev</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 == Maven project setup
70
71 The following lists a few important steps required for setting up a Maven project for a {{formcycle/}} plugin, but we assume you have basic knowledge of how to work with Maven.
72
73 To get started with a plugin, you can also use of of the available [[Maven archetypes>>||anchor="HMavenarchetypes"]].
74
75 === Artekfakte und Abhängigkeiten
76
77 {{info}}
78 All dependencies to {{formcycle/}} must be declared with the scope //provided//.
79 {{/info}}
80
81 You can download a complete //pom.xml// for plugin development [[here>>attach:pom.xml||rel="__blank"]].
82
83 The main artifact you need to include is the artifact [[fc-plugin-common>>url:http://artifactory.xima-services.de/artifactory/fc-plugin-dev/de/xima/fc/fc-plugin-common/]]. It contains all Java interfaces available for plugins.
84
85 Add the following to the //pom.xml// of the plugin project to include that artifact:
86
87 {{code language="xml"}}
88 <properties>
89 <xfc.version>7.2.1</xfc.version>
90 </properties>
91
92 <dependencies>
93 <dependency>
94 <groupId>de.xima.fc</groupId>
95 <artifactId>fc-plugin-common</artifactId>
96 <version>${xfc.version}</version>
97 <scope>provided</scope>
98 </dependency>
99 </dependencies>
100 {{/code}}
101
102 For more complicated plugins, you can also include //fc-logic//, which provides more {{formcycle/}} related classes, such as the database access objects when you need to access the database. If you want to use it, replace dependency to //fc-plugin-common// with:
103
104 {{code language="xml"}}
105 <dependency>
106 <groupId>de.xima.fc</groupId>
107 <artifactId>fc-logic</artifactId>
108 <version>${xfc.version}</version>
109 <scope>provided</scope>
110 </dependency>
111 {{/code}}
112
113 Note that all dependencies must be declared with the //provide// scope. This prevents class path issues and keeps the plugin size small. When possible, use libraries already used by {{formcycle/}}, e.g. certain Apache Common libraries or guava. Also use the provided scope for such dependencies. A simple way to manage versions and avoid mistakes is by including the FORMCYCLE Bom:
114
115 {{code language="xml"}}
116 <dependencyManagement>
117 <dependencies>
118 <!--Import dependency versions from FORMCYCLE -->
119 <dependency>
120 <groupId>de.xima.fc</groupId>
121 <artifactId>fc</artifactId>
122 <version>${xfc.version}</version>
123 <type>pom</type>
124 <scope>import</scope>
125 </dependency>
126 </dependencies>
127 </dependencyManagement>
128 {{/code}}
129
130 Then just declare the dependency you wish to use without a {{code}}<version>...</version>{{/code}}. If FORMCYCLE already provides that dependency, you won't get a build error. Otherwise you need to include the dependency in the plugin: Remove the provided scope and add the version.
131
132
133 === Manifest und Fat JAR
134
135 The //META-INF/MANIFEST.MF// file in the plugin JAR should contain the following entries:
136
137 ; formcycle-version-requirement
138 : Required. The version of {{formcycle/}} against which the plugin was compiled. This is required for {{formcycle/}} to check the compatibility when the plugin is installed.
139 ; Implementation-Version
140 : Required. The version of the plugin, which is for example shown in the UI.
141 ; Plugin-Key
142 : Required. This is used by {{formcycle/}} to identify the plugin, and also used by e.g. the deploy or server plugin. Recommended value is {{code}}${project.groupId}:${project.artifactId}{{/code}}.
143 ; Build-Time oder Build-Timestamp
144 : Optional. This is displayed in the UI when the plugin version is a SNAPSHOT.
145
146 {{info}}
147 Up until and including version 7.x of {{formcycle/}}, {{code}}Implementation-Title{{/code}} with the same value as {{code}}Plugin-Key{{/code}} is also required.
148 {{/info}}
149
150 You can use the //maven-assembly-plugin// to add these entries to the manifest.
151
152 Furthermore, it is required that you create a fat JAR. Dependencies provided by {{formcycle/}} should be declared with the scope //provided//, as mentioned above. However, any additional dependencies that your plugin needs must be included in the JAR file.
153
154 This can be done via the [[maven-assembly-plugin>>url:https://maven.apache.org/plugins/maven-assembly-plugin/]] or via the [[maven-shade-plugin>>url:https://maven.apache.org/plugins/maven-shade-plugin/]]. The latter one is meant for advanced use cases, such as when multiple dependencies have conflicting files and you need to merge those.
155
156 For many plugins, the //maven-assembly-plugin// is sufficient. You can configure this plugin in the //pom.xml// as follows:
157
158 {{panel title="maven-assembly-plugin in pom.xml" fullwidth="true" initial="hidden" triggerable="true"}}
159 {{code language="java"}}
160 <properties>
161 <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
162 </properties>
163 <build>
164 <finalName>${project.artifactId}</finalName>
165 <plugins>
166 <plugin>
167 <groupId>org.apache.maven.plugins</groupId>
168 <artifactId>maven-assembly-plugin</artifactId>
169 <version>${maven-assembly-plugin.version}</version>
170 <executions>
171 <execution>
172 <id>fat-jar</id>
173 <phase>package</phase>
174 <goals>
175 <goal>single</goal>
176 </goals>
177 <configuration>
178 <finalName>${project.artifactId}</finalName>
179 <appendAssemblyId>false</appendAssemblyId>
180 <descriptorRefs>
181 <descriptorRef>jar-with-dependencies</descriptorRef>
182 </descriptorRefs>
183 <archive>
184 <manifest>
185 <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
186 </manifest>
187 <manifestEntries>
188 <formcycle-version-requirement>${xfc-version}</formcycle-version-requirement>
189 <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
190 <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
191 <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
192 <Implementation-Version>${project.version}</Implementation-Version>
193 </manifestEntries>
194 </archive>
195 </configuration>
196 </execution>
197 </executions>
198 </plugin>
199 </plugins>
200 </build>
201 {{/code}}
202 {{/panel}}
203
204 === Build and install ===
205
206 In general, the command to build the plugin depends on the settings in the //pom.xml//. In most cases, however, the following standard command should be enough:
207
208 {{code}}
209 mvn clean install
210 {{/code}}
211
212 This creates a JAR file in the //target// folder. You can then upload this plugin to a running {{formcycle/}} server, either as a [[client plugin>>doc:Formcycle.UserInterface.Client.Plugins]] or as a [[system plugin>>doc:Formcycle.SystemSettings.UserInterface.SystemPlugins]].
213
214 See the [[deploy plugin>>||anchor="HDeployplugin"]] to upload the plugin to a running {{formcycle/}} server during the Maven build process.
215
216 See the [[FC server plugin>>||anchor="HFCserverplugin"]] for starting a simple {{formcycle/}} server.
217
218 == Maven archetypes ==
219
220 {{figure image="eclipse-archetype.png" width="500"}}
221 Adding an archetype catalog in Eclipse
222 {{/figure}}
223
224 {{figure image="eclipse-archetype-select.png" width="500"}}
225 Selecting an archetype in Eclispe when creating a new Maven project
226 {{/figure}}
227
228 For some common plugin types, we provide [[Maven archetypes>>url:https://maven.apache.org/guides/introduction/introduction-to-archetypes.html||target="_blank"]] to help you get started.
229
230 If you added the XIMA artifactory to the //~~/.m2/settings.xml// as described above, you can create a new plugin project from an archetype via the following CLI command:
231
232 {{code}}
233 mvn archetype:generate -DarchetypeArtifactId=plugin-archetype-workflow-element-simple -DarchetypeGroupId=de.xima.fc.archetype
234 {{/code}}
235
236 This prompts for a few required details such as the desired Maven coordinates of the new project, then creates a new folder in the current working directory with a preconfigured Maven project.
237
238 See the [[archetype catalog>>url:https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml||target="_blank"]] for a list of available archetypes.
239
240 If you are using Eclipse, you can also add the archetype catalog in the Eclipse settings. Eclipse will then show you the available archetypes when you create a new Maven project with the builtin wizard.
241
242 {{code language="plaintext"}}https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml{{/code}}
243
244 == Deploy plugin
245
246 When developing a plugin, you often need to build a new snapshot version and upload it to a running {{formcycle/}} server. To ease that process, the deploy plugin can be used to upload the plugin automatically as part of the Maven build process. It consists of two parts:
247
248 * A Maven plugin, which is run at the end of the build process and sends the plugin JAR file to a running {{formcycle/}} server via HTTP.
249 * A {{formcycle/}} plugin, which provides the endpoint that takes the plugin from the HTTP requests and installs it to {{formcycle/}}.
250
251 For more details, see [[help page of the deploy plugin>>doc:Formcycle.PluginDocumentation.FormcycleDeployPluginPlugin]]. For most cases, you do not need any configuration in your pom, but we recommend you at least pin the version to a specific release:
252
253 {{code language="xml"}}
254 <properties>
255 <fc-deploy-plugin-maven-plugin.version>7.0.1</fc-deploy-plugin-maven-plugin.version>
256 <build>
257 <plugins>
258 <plugin>
259 <groupId>de.xima.fc.maven.plugin</groupId>
260 <artifactId>fc-deploy-plugin-maven-plugin</artifactId>
261 <version>${fc-deploy-plugin-maven-plugin.version}</version>
262 </plugin>
263 </plugins>
264 </build>
265 {{/code}}
266
267 Assuming the deploy plugin is installed as a system plugin of a {{formcycle/}} server, you can build and upload your plugin project as follows:
268
269 {{code language="bash"}}
270 mvn fc-deploy:deploy
271 {{/code}}
272
273 This assumes that {{formcycle/}} is running on the standard URL {{code}}http://localhost:8080/xima-formcycle{{/code}} and that the deploy plugin uses the default password "admin". If that is not the case, you can also change these values:
274
275 {{code language="bash"}}
276 mvn package fc-deploy:deploy -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin
277 {{/code}}
278
279 {{info}}
280 Up to and including version 7.x of {{formcycle/}} and the Maven plugin, you need to run the package phase explicitly and always specify the URL and the password. Starting with version 8.x, the package phase is executed automatically and the URL and password have default values.
281 {{/info}}
282
283 If you want to upload the plugin in a client scope, add the parameter //-DfcDeployClientId=3// with the ID of the client.
284
285 == FC server plugin ==
286
287 To test a plugin, you will need a running {{formcycle/}} server. The //fc-server-maven-plugin// can be used to start a fully configured {{formcycle/}} server with just a single command. It also comes with the deploy plugin preinstalled.
288
289 If you added the //pluginGroup// to the //~~/.m2/settings.xml// as described above, you can start a {{formcycle/}} server with the following CLI command:
290
291 {{code language="bash"}}
292 # Start the current version
293 mvn fc-server:run-ms-war
294
295 # Start a specific version
296 mvn de.xima.fc.maven.plugin:fc-server-maven-plugin:7.0.4:run-ms-war -DxfcVersion=7.0.16
297 {{/code}}
298
299 {{info}}
300 We recommend you use Java 11. You may encounter issues when yout attempt to start {{formcycle/}} with Java 17.
301 {{/info}}
302
303 {{info}}
304 Up to and including version 7.x of {{formcycle/}} and the Maven plugin, you need to run the package phase explicitly: {{code}}mvn package fc-server:run-ms-war{{/code}}. Starting with version 8.x, this is not required anymore.
305 {{/info}}
306
307 {{info}}
308 The major and minor version of the Maven plugin should always be equal to the major and minor version of the {{formcycle/}} application you are running. For example, to start {{formcycle/}} 7.0.x, you should the Maven plugin version 7.0.x. To start {{formcycle/}} 7.1.x, you should use the Maven plugin version 7.1.x etc.
309 {{/info}}
310
311 After a short amount of time (may take longer when you start it for the first time), you have a local {{formcycle/}} server running. The URL is printed in the command line, and should be http://localhost:8080/xima-formcycle by default. The super user login is {{code language="plaintext"}}sadmin{{/code}} (password: {{code language="plaintext"}}admin{{/code}}), the client admin access is {{code language="plaintext"}}admin{{/code}} (password {{code language="plaintext"}}/admin_{{/code}}).
312
313 When you run the command in the root folder of a Maven project, the project is packaged, uploaded to server and installed. Also, the FC server Maven plugin tries to read the {{formcycle/}} version from the plugin.
314
315 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.
316
317 This command works even in a directory without a Maven project. When no {{formcycle/}} version is given, a default one is used.
318
319 For advanced usage, see the [[README.md>>attach:README-FC-SERVER.md||rel="__blank"]].