Wiki source code of Plugin-Entwicklung


Hide last authors
gru 1.1 1 {{content/}}
2
MKO 16.1 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.
gru 1.1 4
MKO 16.1 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.
gru 1.1 6
MKO 16.1 7 == API documentation ==
gru 1.1 8
MKO 16.1 9 The API documentations for {{formcycle/}} can be found here: [[Javadocs>>https://docs.formcycle.eu/]]
gru 1.1 10
MKO 16.1 11 == Project setup ==
gru 1.1 12
MKO 16.1 13 To get started with developing plugins, you need to create and configure new project.
gru 1.1 14
MKO 16.1 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.
gru 1.1 16
MKO 16.1 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.
gru 1.1 18
MKO 16.1 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:
gru 1.1 20
awa 3.3 21 {{panel title="~~~~/.m2/settings.xml" fullwidth="true" initial="hidden" triggerable="true"}}
awa 3.1 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">
gru 1.1 26
awa 3.1 27 <!-- Add XIMA artifactory -->
28 <profiles>
29 <profile>
awa 3.4 30 <!-- FORMCYCLE dependencies -->
awa 3.1 31 <repositories>
32 <repository>
33 <snapshots>
34 <enabled>false</enabled>
35 </snapshots>
36 <id>xima</id>
awa 5.9 37 <name>fc-plugin-dev</name>
awa 3.1 38 <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
39 </repository>
40 </repositories>
awa 3.4 41 <!-- Maven plugins for FORMCYCLE -->
awa 3.1 42 <pluginRepositories>
43 <pluginRepository>
44 <snapshots>
45 <enabled>false</enabled>
46 </snapshots>
47 <id>xima</id>
awa 5.9 48 <name>fc-plugin-dev</name>
awa 3.1 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>
gru 1.1 55
awa 3.1 56 <!-- Enable XIMA artifactory by default -->
57 <activeProfiles>
58 <activeProfile>xima-artifactory</activeProfile>
59 </activeProfiles>
gru 1.1 60
awa 3.1 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}}
gru 1.1 68
MKO 16.1 69 == Maven project setup
gru 1.1 70
MKO 16.1 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.
awa 3.8 72
MKO 16.1 73 To get started with a plugin, you can also use of of the available [[Maven archetypes>>||anchor="HMavenarchetypes"]].
awa 3.5 74
MKO 16.1 75 === Artekfakte und Abhängigkeiten
76
awa 3.5 77 {{info}}
MKO 16.1 78 All dependencies to {{formcycle/}} must be declared with the scope //provided//.
awa 3.5 79 {{/info}}
80
MKO 16.1 81 You can download a complete //pom.xml// for plugin development [[here>>attach:pom.xml||rel="__blank"]].
awa 6.2 82
MKO 16.1 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.
awa 3.5 84
MKO 16.1 85 Add the following to the //pom.xml// of the plugin project to include that artifact:
awa 3.5 86
awa 3.1 87 {{code language="xml"}}
88 <properties>
awa 10.15 89 <xfc.version>7.2.1</xfc.version>
awa 3.1 90 </properties>
gru 1.1 91
awa 3.1 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>
gru 1.1 100 {{/code}}
101
MKO 16.1 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:
gru 1.1 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
MKO 16.1 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:
gru 1.1 114
awa 10.6 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
MKO 16.1 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.
awa 10.6 131
gru 1.1 132
MKO 16.1 133 === Manifest und Fat JAR
gru 1.1 134
MKO 16.1 135 The //META-INF/MANIFEST.MF// file in the plugin JAR should contain the following entries:
136
awa 3.5 137 ; formcycle-version-requirement
MKO 16.1 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.
awa 3.5 139 ; Implementation-Version
MKO 16.1 140 : Required. The version of the plugin, which is for example shown in the UI.
awa 10.13 141 ; Plugin-Key
MKO 16.1 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}}.
awa 3.5 143 ; Build-Time oder Build-Timestamp
MKO 16.1 144 : Optional. This is displayed in the UI when the plugin version is a SNAPSHOT.
gru 1.1 145
awa 10.13 146 {{info}}
MKO 16.1 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.
awa 10.13 148 {{/info}}
149
MKO 16.1 150 You can use the //maven-assembly-plugin// to add these entries to the manifest.
awa 3.5 151
MKO 16.1 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.
awa 3.5 153
MKO 16.1 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.
awa 3.5 155
MKO 16.1 156 For many plugins, the //maven-assembly-plugin// is sufficient. You can configure this plugin in the //pom.xml// as follows:
awa 3.5 157
awa 3.6 158 {{panel title="maven-assembly-plugin in pom.xml" fullwidth="true" initial="hidden" triggerable="true"}}
awa 3.5 159 {{code language="java"}}
160 <properties>
161 <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
162 </properties>
163 <build>
awa 5.10 164 <finalName>${project.artifactId}</finalName>
awa 3.5 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>
awa 5.10 178 <finalName>${project.artifactId}</finalName>
awa 3.5 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}}
awa 3.6 202 {{/panel}}
awa 3.5 203
MKO 16.1 204 === Build and install ===
awa 3.5 205
MKO 16.1 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:
awa 3.5 207
208 {{code}}
MKO 16.1 209 mvn clean install
awa 3.5 210 {{/code}}
211
MKO 16.1 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]].
awa 3.5 213
MKO 16.1 214 See the [[deploy plugin>>||anchor="HDeployplugin"]] to upload the plugin to a running {{formcycle/}} server during the Maven build process.
awa 3.5 215
MKO 16.1 216 See the [[FC server plugin>>||anchor="HFCserverplugin"]] for starting a simple {{formcycle/}} server.
awa 3.5 217
MKO 16.1 218 == Maven archetypes ==
awa 3.5 219
awa 4.3 220 {{figure image="eclipse-archetype.png" width="500"}}
MKO 16.1 221 Adding an archetype catalog in Eclipse
awa 4.2 222 {{/figure}}
awa 3.1 223
awa 5.2 224 {{figure image="eclipse-archetype-select.png" width="500"}}
MKO 16.1 225 Selecting an archetype in Eclispe when creating a new Maven project
awa 5.2 226 {{/figure}}
227
MKO 16.1 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.
awa 4.2 229
MKO 16.1 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:
awa 4.2 231
232 {{code}}
MKO 16.1 233 mvn archetype:generate -DarchetypeArtifactId=plugin-archetype-workflow-element-simple -DarchetypeGroupId=de.xima.fc.archetype
awa 4.2 234 {{/code}}
235
MKO 16.1 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.
awa 4.2 237
MKO 16.1 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.
awa 4.2 239
MKO 16.1 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.
awa 4.2 241
MKO 16.1 242 {{code language="plaintext"}}https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml{{/code}}
awa 4.14 243
MKO 16.1 244 == Deploy plugin
awa 3.5 245
MKO 16.1 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:
awa 3.5 247
MKO 16.1 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/}}.
awa 5.5 250
MKO 16.1 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:
awa 5.5 252
253 {{code language="xml"}}
254 <properties>
awa 15.2 255 <fc-deploy-plugin-maven-plugin.version>7.0.1</fc-deploy-plugin-maven-plugin.version>
awa 5.5 256 <build>
257 <plugins>
MKO 16.1 258 <plugin>
awa 5.5 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
MKO 16.1 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:
awa 5.5 268
269 {{code language="bash"}}
awa 10.10 270 mvn fc-deploy:deploy
271 {{/code}}
272
MKO 16.1 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:
awa 10.10 274
275 {{code language="bash"}}
awa 10.2 276 mvn package fc-deploy:deploy -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin
awa 5.5 277 {{/code}}
278
awa 10.10 279 {{info}}
MKO 16.1 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.
awa 10.10 281 {{/info}}
282
MKO 16.1 283 If you want to upload the plugin in a client scope, add the parameter //-DfcDeployClientId=3// with the ID of the client.
awa 3.5 284
MKO 16.1 285 == FC server plugin ==
awa 3.5 286
MKO 16.1 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.
awa 3.5 288
MKO 16.1 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:
awa 5.6 290
291 {{code language="bash"}}
MKO 16.1 292 # Start the current version
awa 10.8 293 mvn fc-server:run-ms-war
awa 10.5 294
MKO 16.1 295 # Start a specific version
awa 10.5 296 mvn de.xima.fc.maven.plugin:fc-server-maven-plugin:7.0.4:run-ms-war -DxfcVersion=7.0.16
awa 5.6 297 {{/code}}
298
awa 10.5 299 {{info}}
MKO 16.1 300 We recommend you use Java 11. You may encounter issues when yout attempt to start {{formcycle/}} with Java 17.
awa 10.5 301 {{/info}}
302
303 {{info}}
MKO 16.1 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.
awa 10.8 305 {{/info}}
306
307 {{info}}
MKO 16.1 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.
awa 10.5 309 {{/info}}
310
MKO 16.1 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}}).
awa 5.6 312
MKO 16.1 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.
awa 10.8 314
MKO 16.1 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.
awa 10.8 316
MKO 16.1 317 This command works even in a directory without a Maven project. When no {{formcycle/}} version is given, a default one is used.
awa 12.2 318
MKO 16.1 319 For advanced usage, see the [[README.md>>attach:README-FC-SERVER.md||rel="__blank"]].
320