Changes for page Plugin-Entwicklung

From 1.2 to 1.3

From version 1.1

edited by gru
on 20.01.2021, 16:18

Change comment: Imported from XAR

To version 1.2

edited by awa
on 25.02.2022, 14:54

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (2 modified, 0 added, 0 removed)

Details

Page properties

Author

@@ -1,1 +1,1 @@
--XWiki.gru
++XWiki.awa

Content

@@ -1,8 +1,8 @@
  {{content/}}
--== Plugins for extending {{formcycle/}} ==
++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.
--Many services and functions of {{formcycle/}} can be customized and extended by using plugins. Each [[plugin type>>doc:Formcycle.PluginDevelopment.Types.WebHome]] extends a certain aspect of {{formcycle/}}, such as workflow processing or preprocessing forms. To create a custom plugin, you need to setup a Java project first of all.
++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.
  == API documentation ==
@@ -10,134 +10,266 @@
  == Project setup ==
--Setup a new Java project with the IDE of your choice. {{formcycle/}} uses the build management system [[Apache Maven>>url:https://maven.apache.org/]]) to resolve dependencies. Dependencies are provided by our public artifactory {{code language="none"}}http://artifactory.xima-services.de/artifactory/fc-plugin-dev{{/code}}. It contains all components needed for developing plugins. The main artifact you will need is the artifact [[fc-plugin-common>>url:http://artifactory.xima-services.de/artifactory/fc-plugin-dev/de/xima/fc/fc-plugin-common/]], containing all Java interfaces available for plugins.
++To get started with developing plugins, you need to create and configure new project.
--Maven uses configuration files named {{code language="none"}}pom.xml{{/code}} (project object model). A pom for plugin development might look as follows:
++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.
--{{panel title="Example for a pom.xml" initial="hidden" triggerable="true" fullwidth="true"}}
++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.
++
++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:
++
++{{panel title="~~~~/.m2/settings.xml" fullwidth="true" initial="hidden" triggerable="true"}}
  {{code language="xml"}}
--<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
++<?xml version="1.0" encoding="UTF-8"?>
++<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"
++    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
--...
++  <!-- Add XIMA artifactory -->
++  <profiles>
++    <profile>
++      <!-- FORMCYCLE dependencies -->
++      <repositories>
++        <repository>
++          <snapshots>
++            <enabled>false</enabled>
++          </snapshots>
++          <id>xima</id>
++          <name>fc-plugin-dev</name>
++          <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
++        </repository>
++      </repositories>
++      <!-- Maven plugins for FORMCYCLE -->
++      <pluginRepositories>
++        <pluginRepository>
++          <snapshots>
++            <enabled>false</enabled>
++          </snapshots>
++          <id>xima</id>
++          <name>fc-plugin-dev</name>
++          <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
++        </pluginRepository>
++      </pluginRepositories>
++      <id>xima-artifactory</id>
++    </profile>
++  </profiles>
-- <properties>
--  <!-- Configuration -->
--  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
++  <!-- Enable XIMA artifactory by default -->
++  <activeProfiles>
++    <activeProfile>xima-artifactory</activeProfile>
++  </activeProfiles>
--  <!-- Dependencies -->
--  <xfc-version>4.2.3</xfc-version>
++  <!-- FORMCYCLE specific Maven plugins provided by XIMA -->
++  <pluginGroups>
++    <pluginGroup>de.xima.fc.maven.plugin</pluginGroup>
++  </pluginGroups>
++</settings>
++{{/code}}
++{{/panel}}
--  <!-- Plugins -->
--  <maven-compiler-plugin-version>3.3</maven-compiler-plugin-version>
--  <maven-jar-plugin-version>2.4</maven-jar-plugin-version>
-- </properties>
++== Maven project setup
-- <repositories>
--  <repository>
--   <id>xima</id>
--   <name>fc-plugin-dev</name>
--   <url>http://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
--  </repository>
-- </repositories>
++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.
-- <dependencies>
--  <dependency>
--   <groupId>de.xima.fc</groupId>
--   <artifactId>fc-plugin-common</artifactId>
--   <version>${xfc-version}</version>
--   <scope>provided</scope>
--  </dependency>
-- </dependencies>
++To get started with a plugin, you can also use of of the available [[Maven archetypes>>||anchor="HMaven-Archetypes"]].
-- <build>
--  <plugins>
--   <plugin>
--    <groupId>org.apache.maven.plugins</groupId>
--    <artifactId>maven-compiler-plugin</artifactId>
--    <version>${maven-compiler-plugin-version}</version>
--    <configuration>
--     <source>1.7</source>
--     <target>1.7</target>
--     <encoding>UTF-8</encoding>
--    </configuration>
--   </plugin>
++=== Artekfakte und Abhängigkeiten
--   <plugin>
--    <groupId>org.apache.maven.plugins</groupId>
--    <artifactId>maven-jar-plugin</artifactId>
--    <version>${maven-jar-plugin-version}</version>
--    <configuration>
--     <archive>
--      <manifest>
--       <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
--      </manifest>
--      <manifestEntries>
--       <formcycle-version-requirement>${xfc-version}</formcycle-version-requirement>
--       <Build-Time>${maven.build.timestamp}</Build-Time>
--      </manifestEntries>
--     </archive>
--    </configuration>
--   </plugin>
++{{info}}
++All dependencies to {{formcycle/}} must be declared with the scope //provided//.
++{{/info}}
--  </plugins>
-- </build>
--</project>
++You can download a complete //pom.xml// for plugin development [[here>>attach:pom.xml||rel="__blank"]].
++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.
++
++Add the following to the //pom.xml// of the plugin project to include that artifact:
++
++{{code language="xml"}}
++  <properties>
++    <xfc.version>7.0.10</xfc.version>
++  </properties>
++
++  <dependencies>
++    <dependency>
++     <groupId>de.xima.fc</groupId>
++     <artifactId>fc-plugin-common</artifactId>
++     <version>${xfc.version}</version>
++     <scope>provided</scope>
++    </dependency>
++  </dependencies>
  {{/code}}
--{{/panel}}
--Certain plugins may require additional classes and functionality of the {{formcycle/}} system, which is provided by the artifact //fc-logic//. To add it as a dependency, modify the pom as follows:
++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:
  {{code language="xml"}}
--...
    <dependency>
     <groupId>de.xima.fc</groupId>
     <artifactId>fc-logic</artifactId>
--   <version>${xfc-version}</version>
++   <version>${xfc.version}</version>
     <scope>provided</scope>
    </dependency>
--...
  {{/code}}
--This artifact becomes necessary especially when working with databases or the [[workflow processing>>doc:Formcycle.PluginDevelopment.Types.IPluginProcessing.WebHome]]. You can also [[download a template for a pom file>>attach:pom.xml||rel="__blank"]] that includes the //fc-logic// artifact.
++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.
--{{info}}
--For version of {{formcycle/}} earlier than 4.1.1, you need to exclude the non-public dependency on the //aspose-processor// of the //fc-logic// artifact.
--{{/info}}
++=== Manifest und Fat JAR
--Furthermore, note that all dependencies must be declared with the //provide// scope. This prevent class path issues and keeps the plugin size small. When possible, use libraries already in use by {{formcycle/}}, eg. certain Apache Common libraries.
++The //META-INF/MANIFEST.MF// file in the plugin JAR should contain the following entries:
--{{info}}
--All dependencies must be declared with the scope //provided//.
--{{/info}}
++; formcycle-version-requirement
++: 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.
++; Implementation-Version
++: Required. The version of the plugin, which is for example shown in the UI.
++; Build-Time oder Build-Timestamp
++: Optional. This is displayed in the UI when the plugin version is a SNAPSHOT.
++; Implementation-Title
++: Optional. This is used e.g. by the deploy plugin to identify the plugin.
--Developing a plugin for {{formcycle/}} can be as simple as implementing one of the plugin interfaces. To install a plugin, upload them on the administrative interface either as a [[client>>doc:Formcycle.UserInterface.Client.Plugins]] or [[system plugin>>doc:Formcycle.SystemSettings.UserInterface.SystemPlugins]].
++You can use the //maven-assembly-plugin// to add these entries to the manifest.
--== Demo plugins ==
++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.
--As an introduction and to help you getting started with developing plugins, we provide several fully commented demo maven projects for each plugin type [[on our download pages>>url:https://customer.formcycle.eu/index.php/s/PgdMrNOvbYEzhmr]]. After downloading them, you can import them into the IDE of your choice, compile them and upload them to {{formcycle/}}.
++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.
--== Special terms ==
++For many plugins, the //maven-assembly-plugin// is sufficient. You can configure this plugin in the //pom.xml// as follows:
--Some Java methods and classes contain German technical terms as used by {{formcycle/}}. For reference, see the following list for their English counterparts.
++{{panel title="maven-assembly-plugin in pom.xml" fullwidth="true" initial="hidden" triggerable="true"}}
++{{code language="java"}}
++  <properties>
++    <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
++  </properties>
++  <build>
++    <finalName>${project.artifactId}</finalName>
++    <plugins>
++      <plugin>
++        <groupId>org.apache.maven.plugins</groupId>
++        <artifactId>maven-assembly-plugin</artifactId>
++        <version>${maven-assembly-plugin.version}</version>
++        <executions>
++          <execution>
++            <id>fat-jar</id>
++            <phase>package</phase>
++            <goals>
++              <goal>single</goal>
++            </goals>
++            <configuration>
++              <finalName>${project.artifactId}</finalName>
++              <appendAssemblyId>false</appendAssemblyId>
++              <descriptorRefs>
++                <descriptorRef>jar-with-dependencies</descriptorRef>
++              </descriptorRefs>
++              <archive>
++                <manifest>
++                  <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
++                </manifest>
++                <manifestEntries>
++                  <formcycle-version-requirement>${xfc-version}</formcycle-version-requirement>
++                  <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
++                  <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
++                  <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
++                  <Implementation-Version>${project.version}</Implementation-Version>
++                </manifestEntries>
++              </archive>
++            </configuration>
++          </execution>
++        </executions>
++      </plugin>
++    </plugins>
++  </build>
++{{/code}}
++{{/panel}}
--{{table dataTypeAlpha="0-1" preSort="0-asc"}}
++=== Build and install ===
--|=German|=English|=Example
--|Mandant|[[Client>>doc:Formcycle.SystemSettings.UserInterface.Clients]]|{{code language="Java"}}public Mandant getMandant(){{/code}} (get client)
--|Benutzer|[[User>>doc:Formcycle.UserInterface.UserSettings.WebHome]]|{{code language="Java"}}public Benutzer getCurrentBenutzer(){{/code}} (get user currently logged in)
--|Projekt|Project, a former term for a //form// containing files and multiple form versions|{{code language="Java"}}public Projekt getProjekt(){{/code}}
--|Aktion|[[Action>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.Actions.WebHome]] (workflow)|{{code language="Java"}}public Aktion getFolgeAktion(){{/code}} (get next action)
--|Weiterverarbeitung|Further processing|{{code language="Java"}}public EWeiterverarbeitung_Aktion getWeiterverarbeitungBeiFehler(){{/code}} (how to continue when an error has occurred)
--|Bedingung|[[Condition>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.ActionConditions]] (action)|{{code language="Java"}}public Bedingung getBedingung(){{/code}} (get the condition of an action)
--|Datei|[[File>>doc:Formcycle.UserInterface.FilesAndTemplates.Files]]|{{code language="Java"}}public FormEingangDatei getDatei(){{/code}} (get attached file)
--|Textbaustein|[[Template>>doc:Formcycle.UserInterface.FilesAndTemplates.WebHome]]|{{code language="Java"}}public ETextbausteinKategorie getKategorie(){{/code}} (get template type)
--|Vorgang|Form record|{{code language="Java"}}public Postfach getByVorgang(UserContext uc, Vorgang vorgang){{/code}} (get inbox for form record)
--|Postfach|[[Inbox>>doc:Formcycle.Inbox.WebHome]]|{{code language="Java"}}public Postfach getCurrentPostfach(){{/code}} (get current inbox)
--|Rolle|[[Role>>doc:Formcycle.UserInterface.UserSettings.Roles]]|{{code language="Java"}}public List<Rolle> getRollen(){{/code}} (get all roles for a user)
--|Datenquelle|[[Data source>>doc:.Types.IPluginDataSource]]|{{code language="Java"}}public IPluginDataSourceRetVal executeDatenquelle(...){{/code}} (get serializable JSON array from a data source)
--|Beschreibung|Description|{{code language="Java"}}public String getBeschreibung(){{/code}}
--|Kategory|Category|{{code language="Java"}}public ETextbausteinKategorie getKategorie(){{/code}}
++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:
--{{/table}}
++{{code}}
++mvn clean install
++{{/code}}
++
++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]].
++
++See the [[deploy plugin>>||anchor="HDeployPlugin"]] to upload the plugin to a running {{formcycle/}} server during the Maven build process.
++
++See the [[FC server plugin>>||anchor="HFCServerPlugin"]] for starting a simple {{formcycle/}} server.
++
++== Maven-Archetypes ==
++
++{{figure image="eclipse-archetype.png" width="500"}}
++  Hinzufügen des Archetypes-Katalogs in Eclipse
++{{/figure}}
++
++{{figure image="eclipse-archetype-select.png" width="500"}}
++  Auswahl eines Archetypes beim Erstellen eines Maven-Projekts in Eclipse
++{{/figure}}
++
++Für einige häufig verwendete Plugin-Typen stehen [[Maven-Archetypes>>url:https://maven.apache.org/guides/introduction/introduction-to-archetypes.html||target="_blank"]] bereits, um schnell ein Maven-Projekt aufsetzen zu können.
++
++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:
++
++{{code}}
++mvn archetype:generate -DarchetypeArtifactId=plugin-archetype-workflow-element-simple -DarchetypeGroupId=de.xima.fc.archetype -DarchetypeVersion=7.0.4
++{{/code}}
++
++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.
++
++Alle vorhandenen Archetypes und deren Versionen können im [[Archetype-Katalog>>url:https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml||target="_blank"]] eingesehen werden.
++
++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:
++
++{{code language="plaintext"}}https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml{{/code}}
++
++== Deploy-Plugin
++
++Um beim Entwickeln nicht jedes Mal eine neue Plugin-Version manuell über die Oberfläche hochladen zu müssen, kann das Deploy-Plugin verwendet werden. Dieses besteht aus 2 Teilen:
++
++* Ein Maven-Plugin, welches nach dem Bauen das Plugin via HTTP an einen laufenden {{formcycle/}}-Server sendet
++* Ein Plugin für {{formcycle/}}, welche die Gegenstelle in {{formcycle/}} bereitstellt und das Plugin aus dem HTTP-Request in {{formcycle/}} installiert.
++
++Weitere Details können im [[Hilfe-Artikel zum Deploy-Plugin>>doc:Formcycle.PluginDocumentation.FormcycleDeployPluginPlugin]] nachgelesen werden. Für die meisten Fälle reicht folgende Konfiguration in der //pom.xml// des Plugin-Projekts aus:
++
++{{code language="xml"}}
++  <properties>
++    <fc-deploy-plugin-maven-plugin.version>7.0.1<fc-deploy-plugin-maven-plugin.version/>
++  <build>
++    <plugins>
++	  <plugin>
++        <groupId>de.xima.fc.maven.plugin</groupId>
++        <artifactId>fc-deploy-plugin-maven-plugin</artifactId>
++        <version>${fc-deploy-plugin-maven-plugin.version}</version>
++        <executions>
++          <execution>
++            <id>upload</id>
++            <phase>install</phase>
++            <goals>
++              <goal>deploy</goal>
++            </goals>
++          </execution>
++        </executions>
++      </plugin>
++    </plugins>
++  </build>
++{{/code}}
++
++Sofern das Deploy-Plugin bereits in {{formcycle/}} installiert ist, kann das Plugin-Projekt dann beim Bauen wie folgt hochgeladen werden:
++
++{{code language="bash"}}
++mvn clean install -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin
++{{/code}}
++
++Wird Eclipse benutzt, kann auch eine Launch-Configuration mit den //fcDeployUrl// und dem //fcDeployToken// angelegt werden.
++
++== FC-Server-Plugin ==
++
++Zum Testen eines Plugins ist es erforderlich, einen laufenden {{formcycle/}}-Server zu haben. Zur Vereinfachung der Entwicklung gibt es das //fc-server-maven-plugin//, welches mittels eines einzigen Befehls ein fertig eingerichtetes {{formcycle/}} lokal startet, wo auch bereits das Deploy-Plugin vorinstalliert ist.
++
++Sofern wie oben beschrieben in //~~/.m2/settings.xml// die //pluginGroup// hinterlegt wurde, kann in einem beliebiegen Verzeichnis wie folgt ein {{formcycle/}}-Server per Maven gestartet werden:
++
++{{code language="bash"}}
++mvn fc-server:run-ms-war -DxfcVersion=7.0.10
++{{/code}}
++
++Nach kurzer Wartezeit (beim ersten Mal kann es länger dauern) ist dann ein {{formcycle/}}-Server gestartet. Die URL steht am Ende in der Kommandozeile, standardmäßig http://localhost:8080/xima-formcycle
++
++Dies funktioniert auch in einem Ordner ohne Maven-Projekt. Falls keine {{formcycle/}} angegeben ist, wird eine Standard-Version genommen. Wird der Befehl innerhalb eines Plugin-Maven-Projekts ausgeführt, wird versucht, die Version von {{formcycle/}} aus dem Plugin-Projekt auszulesen.
++