Differences

This shows you the differences between two versions of the page.

--- dev-guide:creating-own-plugin [2024/04/12 12:49] – gaetan
+++ dev-guide:creating-own-plugin [2025/04/02 15:30] (current) – gaetan
@@ Line 1: / Line 1: @@
-===== Creating a new Plugin =====
+===== GroIMP Plugin =====
 ==== Plugin structure ====
@@ Line 7: / Line 7: @@
 Firstly, a plugin has to have a special directory layout. The layout depends on how you run GroIMP. There are currently two layout:
   - As compiled plugin.
-  - As source code.
+  - As compiled classes.
 In the compiled version of GroIMP (the one deployed and installed with the executable files) the plugins are loaded as:
@@ Line 15: / Line 15: @@
     * plugin.properties
     * plugin.xml
+    * doc/
     * dependencies.jar ...
@@ Line 31: / Line 32: @@
 **Important:** Note that the files //plugin.xml//, and //plugin.properties// are required.
-By default GroIMP load plugins from its root/plugins directory. During development, usually the --project-tree argument is used, making GroIMP load plugin from the same directory as the needed GroIMP plugins and projects (e.g., Graph, XL-Core, IMP-3D, ...). It is also possible to set an additional directory where GroIMP look for plugins in the GroIMP preferences.
+By default GroIMP load plugins from its root/plugins directory. During development, usually the --project-tree argument is used, making GroIMP load plugin from the same directory as the needed GroIMP plugins and projects (e.g., Graph, XL-Core, IMP-3D, ...). It is also possible to set an additional directory where GroIMP look for plugins in the GroIMP preferences. Or by passing the command line argument -p when starting groimp.
 ==== Using Maven ====
@@ Line 46: / Line 47: @@
           * plugin.properties
           * plugin.xml
+          * doc/
           * <additional non-Java files>
       * assembly
@@ Line 285: / Line 287: @@
 Within the registry-element, the actual content of the plugin is registered. You can look at [[:GroIMP-Platform:Platform-registry-structure| this page]] for more information on GroIMP's registry structure.
+===== Embedded documentation =====
+The embedded documentation of GroIMP is based on the docbook format with the htmlhelp template.
+The docbook file must be created in src/main/resources/manual.xml.
+There are several docbook editors available online.
+With GroIMP 2.1.4 it is also possible to use a markdown file as a source of documentation, this file is then turned in to a docbook file and forwarded to the normal pipeline.
+A documentation on the Markdown based approach can be found [[dev-guide:markdownDoku|here]].
+The compilation including the embedded help is described [[maintainer-guide:making-a-groimp-maven#compile_with_help_panel|here]]
+The linking of the embedded documentation  to the help buttons of the panels is explained [[dev-guide:linking-help-button|here]]
+===== Linking an example =====
+In order to make your plugin easier to get started with, it is recommended to add an example project with it. The example projects are available in GroIMP from the [[user-guide:common_panels#project_explorer|project panel]].
+To include an example project,the gsz file needs to be placed in 'src/main/resources' and in the plugin the project needs to be referenced in the ''plugin.xml'' file with:
+<code xml>
+<ref name="examples">
+   <directory name="CATEGORYNAME" optionCategory="true">
+      <projectDir name="PROJECTNAME">
+	<directory name="PROJECTVERSION">
+	  <FilterSourceFactory name="FACTORYNAME">
+	    <resource name="PROJECTFILE.gsz" />
+	  </FilterSourceFactory>
+	</directory>
+     <!-- in the case where several versions of the projects are available -->
+        <directory name="OTHERVERSION">
+	  <FilterSourceFactory name="FACTORYNAME">
+	    <resource name="OTHERFILE.gsz" />
+	  </FilterSourceFactory>
+	</directory>
+      </projectDir>
+  <directory/>
+</code>
+Where:
+  * ref name="examples" is the example registry folder.
+  * CATEGORYNAME is the category where the example will be grouped.
+  * PROJECTNAME is a name, that is used by default when displayed. But it can be overwritten in the properties.
+  * PROJECTVERSION is the version. One project can have several versions. They will all be available in the project explorer, by selecting them in the drop-down menu. Versions of one project need to be added within the same tag ''projectDir''. The other versions will be defined with an OTHERVERSION.
+  * FACTORYNAME is the default name displayed. Can be overwritten in the properties.
+  * PROJECTFILE.gsz (and any OTHERFILE.gsz) the relative path to access the project file. Usually, both the ''plugin.xml'' file and the ''PROJECTFILE'' are in ''src/main/resources/''.
+The displayed name can be changed in the ''plugin.properties'' file:
+<code>
+/examples/CATEGORYNAME.Name = any name you want
+/examples/CATEGORYNAME/PROJECTNAME.ProjectName = ...
+/examples/CATEGORYNAME/PROJECTNAME.ShortDescription = ...
+/examples/CATEGORYNAME/PROJECTNAME.Image = `image IMAGEPATH.png`
+/examples/CATEGORYNAME/PROJECTNAME.Category = ...
+/examples/CATEGORYNAME/PROJECTNAME.Authors = ...
+/examples/CATEGORYNAME/PROJECTNAME.Tags = ...
+</code>
+===== Linking a Template =====
+Similar to the examples a FilterSourceFactory can be used to add new templates. Templates are the files that can be selected by creating a new project 'File/new/...'.
+To add a gsz file stored in 'src/main/resources' as a template it must be  added in the template directory:
+<code xml>
+  <ref name="ui">
+	<ref name="templates">
+		<FilterSourceFactory name="myTemplate">
+		 	<resource name="my_template.gsz"/>
+		</FilterSourceFactory>
+	</ref>
+  </ref>
+</code>
+Additionally the name shown in the menu can be set in the properties file.
+See more:
+[[:groimp-platform:bundle-resources|Add resources in properties file]]