GroIMP wiki

a part of grogra.de

User Tools

Site Tools

Trace:
dev-guide:creating-own-plugin

Differences

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

Link to this comparison view

Next revision		Previous revision
dev-guide:creating-own-plugin [2024/04/12 12:45] – created gaetandev-guide:creating-own-plugin [2025/04/02 15:30] (current) – gaetan
Line 1: Line 1:
-===== Creating a new Plugin =====+===== GroIMP Plugin =====
  
 ==== Plugin structure ==== ==== 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: 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 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: 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.properties
     * plugin.xml     * plugin.xml
 +    * doc/
     * dependencies.jar ...     * dependencies.jar ...
  
Line 22: Line 23:
     * target     * target
       * classes       * classes
-        * plugin.properties +        * plugin.properties 
-       * plugin.xml+        * plugin.xml
         * <compiled class files>         * <compiled class files>
         * <additional files copied from the src-directory>         * <additional files copied from the src-directory>
Line 31: Line 32:
 **Important:** Note that the files //plugin.xml//, and //plugin.properties// are required. **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 ==== ==== Using Maven ====
Line 46: Line 47:
           * plugin.properties           * plugin.properties
           * plugin.xml           * plugin.xml
 +          * doc/
           * <additional non-Java files>           * <additional non-Java files>
       * assembly       * assembly
Line 156: Line 158:
  
 The second part - remote properties: The second part - remote properties:
 +
 <code xml> <code xml>
   <repositories>   <repositories>
Line 173: Line 176:
      <maven.assembly.plugin.move-lib>generate-resources</maven.assembly.plugin.move-lib>      <maven.assembly.plugin.move-lib>generate-resources</maven.assembly.plugin.move-lib>
  </properties>  </properties>
-</code+</code>
  
 defines:  defines: 
Line 208: Line 211:
   
   </dependencies>   </dependencies>
-<code>+</code>
  
 defines the dependencies to: defines the dependencies to:
Line 284: 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. 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]]
 +
 +
dev-guide/creating-own-plugin.1712918739.txt.gz · Last modified: 2024/04/12 12:45 by gaetan