Changes for page Plugin-Entwicklung

From 1.1 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.27

edited by awa
on 15.03.2023, 18:15

Change comment: There is no comment for this version

Raw
Rendered

Summary

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

Details

Page properties

Content

@@ -70,7 +70,7 @@
  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.
--To get started with a plugin, you can also use of of the available [[Maven archetypes>>||anchor="HMaven-Archetypes"]].
++To get started with a plugin, you can also use of of the available [[Maven archetypes>>||anchor="HMavenarchetypes"]].
  === Artekfakte und Abhängigkeiten
@@ -86,7 +86,7 @@
  {{code language="xml"}}
    <properties>
--    <xfc.version>7.0.10</xfc.version>
++    <xfc.version>7.2.1</xfc.version>
    </properties>
    <dependencies>
@@ -110,8 +110,26 @@
    </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.
++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:
++{{code language="xml"}}
++	<dependencyManagement>
++		<dependencies>
++			<!--Import dependency versions from FORMCYCLE -->
++			<dependency>
++				<groupId>de.xima.fc</groupId>
++				<artifactId>fc</artifactId>
++				<version>${xfc.version}</version>
++				<type>pom</type>
++				<scope>import</scope>
++			</dependency>
++		</dependencies>
++	</dependencyManagement>
++{{/code}}
++
++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.
++
++
  === Manifest und Fat JAR
  The //META-INF/MANIFEST.MF// file in the plugin JAR should contain the following entries:
@@ -120,11 +120,15 @@
  : 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.
++; Plugin-Key
++: 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}}.
  ; 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}}
++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.
++{{/info}}
++
  You can use the //maven-assembly-plugin// to add these entries to the manifest.
  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.
@@ -189,48 +189,48 @@
  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 [[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.
++See the [[FC server plugin>>||anchor="HFCserverplugin"]] for starting a simple {{formcycle/}} server.
--== Maven-Archetypes ==
++== Maven archetypes ==
  {{figure image="eclipse-archetype.png" width="500"}}
--  Hinzufügen des Archetypes-Katalogs in Eclipse
++  Adding an archetype catalog in Eclipse
  {{/figure}}
  {{figure image="eclipse-archetype-select.png" width="500"}}
--  Auswahl eines Archetypes beim Erstellen eines Maven-Projekts in Eclipse
++  Selecting an archetype in Eclispe when creating a new Maven project
  {{/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.
++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.
--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:
++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:
  {{code}}
--mvn archetype:generate -DarchetypeArtifactId=plugin-archetype-workflow-element-simple -DarchetypeGroupId=de.xima.fc.archetype -DarchetypeVersion=7.0.4
++mvn archetype:generate -DarchetypeArtifactId=plugin-archetype-workflow-element-simple -DarchetypeGroupId=de.xima.fc.archetype
  {{/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.
++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.
--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.
++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.
--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:
++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.
  {{code language="plaintext"}}https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml{{/code}}
--== Deploy-Plugin
++== 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:
++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:
--* 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.
++* 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.
++* A {{formcycle/}} plugin, which provides the endpoint that takes the plugin from the HTTP requests and installs it to {{formcycle/}}.
--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:
++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:
  {{code language="xml"}}
    <properties>
--    <fc-deploy-plugin-maven-plugin.version>7.0.1<fc-deploy-plugin-maven-plugin.version/>
++    <fc-deploy-plugin-maven-plugin.version>7.0.1</fc-deploy-plugin-maven-plugin.version>
    <build>
      <plugins>
  	  <plugin>
@@ -237,39 +237,62 @@
          <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:
++Assuming the deploy plugin is installed as a system plugin of a {{formcycle/}} server, you can build and upload your plugin project as follows:
  {{code language="bash"}}
--mvn clean install -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin
++mvn fc-deploy:deploy
  {{/code}}
--Wird Eclipse benutzt, kann auch eine Launch-Configuration mit den //fcDeployUrl// und dem //fcDeployToken// angelegt werden.
++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:
--== FC-Server-Plugin ==
++{{code language="bash"}}
++mvn package fc-deploy:deploy -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin
++{{/code}}
--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.
++{{info}}
++  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.
++{{/info}}
--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:
++If you want to upload the plugin in a client scope, add the parameter //-DfcDeployClientId=3// with the ID of the client.
++== FC server plugin ==
++
++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.
++
++If you added the //pluginGroup// to the //~~/.m2/settings.xml// as described above, you can start a {{formcycle/}} server with the following CLI command:
++
  {{code language="bash"}}
--mvn fc-server:run-ms-war -DxfcVersion=7.0.10
++# Start the current version
++mvn fc-server:run-ms-war
++
++# Start a specific version
++mvn de.xima.fc.maven.plugin:fc-server-maven-plugin:7.0.4:run-ms-war -DxfcVersion=7.0.16
  {{/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
++{{info}}
++  We recommend you use Java 11. You may encounter issues when yout attempt to start {{formcycle/}} with Java 17.
++{{/info}}
--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.
++{{info}}
++  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.
++{{/info}}
++{{info}}
++  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.
++{{/info}}
++
++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}}).
++
++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.
++
++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.
++
++This command works even in a directory without a Maven project. When no {{formcycle/}} version is given, a default one is used.
++
++For advanced usage, see the [[README.md>>attach:README-FC-SERVER.md||rel="__blank"]].
++