Wiki source code of Plugin-Entwicklung

Hide last authors

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