Changes for page Plugin-Entwicklung

From 1.3 to 1.2

From version 1.2

edited by awa
on 25.02.2022, 14:54

Change comment: There is no comment for this version

To version 1.1

edited by gru
on 20.01.2021, 16:18

Change comment: Imported from XAR

Raw
Rendered

Summary

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

Details

Page properties

Author

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

Content

@@ -1,8 +1,8 @@
  {{content/}}
--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.
++== Plugins for extending {{formcycle/}} ==
--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.
++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.
  == API documentation ==
@@ -10,266 +10,134 @@
  == Project setup ==
--To get started with developing plugins, you need to create and configure new project.
++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.
--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.
++Maven uses configuration files named {{code language="none"}}pom.xml{{/code}} (project object model). A pom for plugin development might look as follows:
--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"}}
++{{panel title="Example for a pom.xml" initial="hidden" triggerable="true" fullwidth="true"}}
  {{code language="xml"}}
--<?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">
++<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">
--  <!-- 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>
++...
--  <!-- Enable XIMA artifactory by default -->
--  <activeProfiles>
--    <activeProfile>xima-artifactory</activeProfile>
--  </activeProfiles>
++ <properties>
++  <!-- Configuration -->
++  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
--  <!-- FORMCYCLE specific Maven plugins provided by XIMA -->
--  <pluginGroups>
--    <pluginGroup>de.xima.fc.maven.plugin</pluginGroup>
--  </pluginGroups>
--</settings>
--{{/code}}
--{{/panel}}
++  <!-- Dependencies -->
++  <xfc-version>4.2.3</xfc-version>
--== Maven project setup
++  <!-- Plugins -->
++  <maven-compiler-plugin-version>3.3</maven-compiler-plugin-version>
++  <maven-jar-plugin-version>2.4</maven-jar-plugin-version>
++ </properties>
--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.
++ <repositories>
++  <repository>
++   <id>xima</id>
++   <name>fc-plugin-dev</name>
++   <url>http://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
++  </repository>
++ </repositories>
--To get started with a plugin, you can also use of of the available [[Maven archetypes>>||anchor="HMaven-Archetypes"]].
++ <dependencies>
++  <dependency>
++   <groupId>de.xima.fc</groupId>
++   <artifactId>fc-plugin-common</artifactId>
++   <version>${xfc-version}</version>
++   <scope>provided</scope>
++  </dependency>
++ </dependencies>
--=== Artekfakte und Abhängigkeiten
++ <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>
--{{info}}
--All dependencies to {{formcycle/}} must be declared with the scope //provided//.
--{{/info}}
++   <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>
--You can download a complete //pom.xml// for plugin development [[here>>attach:pom.xml||rel="__blank"]].
++  </plugins>
++ </build>
++</project>
--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}}
--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:
++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:
  {{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}}
--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.
++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.
--=== Manifest und Fat JAR
++{{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}}
--The //META-INF/MANIFEST.MF// file in the plugin JAR should contain the following entries:
++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.
--; 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.
++{{info}}
++All dependencies must be declared with the scope //provided//.
++{{/info}}
--You can use the //maven-assembly-plugin// to add these entries to the manifest.
++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]].
--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.
++== Demo plugins ==
--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.
++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/}}.
--For many plugins, the //maven-assembly-plugin// is sufficient. You can configure this plugin in the //pom.xml// as follows:
++== Special terms ==
--{{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}}
++Some Java methods and classes contain German technical terms as used by {{formcycle/}}. For reference, see the following list for their English counterparts.
--=== Build and install ===
++{{table dataTypeAlpha="0-1" preSort="0-asc"}}
--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:
++|=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}}
--{{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.
--
++{{/table}}