Differences

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

--- dev-guide:plugins [2024/06/05 18:03] – gaetan
+++ dev-guide:plugins [2025/06/18 12:05] (current) – barley1965
@@ Line 1: / Line 1: @@
-GroIMP is designed around plugins, which can easily be updated, installed, or removed from the GUI with the  [[user-guide:pluginmanager|Plugin Manager]].
+GroIMP is designed around plugins, which can be added, modified or removed without modifying the GroIMP installation.
-====== Plugin repositories ======
+====== GroIMP Plugin ======
-The plugin manger uses Plugin repositories to gather knowledge on the available plugins.
+Any repository with a ''plugin.xml'' and ''plugin.properties'' files is considered as a plugin by GroIMP.
-The repositories can be provided in three formats:
+To be properly loadable though, the ''plugin.xml'' needs to include:
-  - Ordered List ItemAs a JSON file. Which contains the metadata of one or several plugins.The file need to follow the JSON format for plugin data (see bellow).
+<code xml>
-  - Ordered List ItemAs a local directory. The directory is automatically scanned to find any Groimp plugin. They are found from their plugin.xml file. The plugin data is then extracted from that file.
+<?xml version="1.0" encoding="UTF-8"?>
-  - Ordered List ItemAs a list of repositories (.list). The .list file is a simple list of any of the three repository formats.
+<plugin id="your.plugin.id"
+version="x.x"
+xmlns="http://grogra.de/registry" >
+</code>
+where ''plugin id'' and ''version'' need to be filled with the plugin information.
-====== JSON format for plugin data ======
+See more:
-The metadata used by the plugin is:
+  * [[:dev-guide:creating-own-plugin#plugin_structure|Plugin structure]]
+  * [[:dev-guide:creating-own-plugin#Plugin_configuration_(For_Groimp_integration)|Create a GroIMP plugin]]
+  * [[:dev-guide:creating-own-plugin#embedded_documentation|Add documentation to help panels]]
+     * [[:dev-guide:linking-help-button | Configure help buttons]]
+  * [[https://gitlab.com/grogra/groimp-plugins|Git repo of GroIMP plugins]]
+  * [[https://gitlab.com/grogra/groimp-template/|Plugin templates]]
-id : The unique id of the plugin.
+====== Managing plugins ======
-name : The name of the plugin. Defined in plugin.properties
-versions : A list of version.
-description (optional)
-helpUrl (optional)
-vendor (optional)
-mainClass (optional)
-A version is composed of:
+GroIMP plugins are located in directories by default:
+  - ''/path/where/groimpisinstalled/plugins/''
+  - ''~/.grogra.de-platform/plugins/''
-its version : The version number
+Additionally, it is possible to add a directory with the argument ''-p /path/to/directory/''. (e.g. ''java -jar core.jar -p /dir/'').
-a downloadUrl : The url to download the plugin .jar. It can be a local path.
-depends : A list of other GroIMP plugin required to run the plugin. The plugins are designed by their id and a version number
-libs : A list of external libraries required by the plugin. The list must contains the name of the jar used by groimp and an url (or local path) to fetch that jar.
+When GroIMP starts it will automatically load every plugin in the given paths.
-Here is an example of a plugin.json file:
+**Note:** It is possible to //ignore// a plugin path by adding it to the //blacklisted// file in ''~/.grogra.de-platform/blacklisted''.
-<code>
-[
-    {
-        "id" : "de.grogra.test",
-        "name" : "Test",
-        "description" : "This is a testing plugin",
-        "helpUrl": "https://gitlab.com/grogra/groimp-plugins/",
-        "vendor": "de.grogra",
-        "mainClass": "",
-        "versions" : {
-            "1.2.3" : {
-                "downloadUrl" : "https://gitlab.com/grogra/groimp-plugins/Test/download",
-                "libs" : {
-                "xmlbeans.jar" :"https://repo1.maven.org/maven2/org/apache/xmlbeans/xmlbeans/2.3.0/xmlbeans-2.3.0.jar"
-                },
-                "depends" : {
-                   "de.grogra.ext.x3d":"=2.1.1"
-                }
-            }
-        }
-    }
-]
-</code>
-===== Plugin version conditions =====
-==== Equal condition ====
+===== Manually ====
-The plugin usually depends on other groimp plugins. It can however depends on a specific version of a plugin.
+It is possible to manually add or remove a plugin by simply copying/deleting them from the loaded paths.
-That dependency is defined by the = before the version number:
-<code>
+The added plugin needs to be compiled and follow the plugin structure. See [[:dev-guide:creating-own-plugin|this guide]] on the plugin structure.
-"depends" : {
-    "de.grogra.ext.x3d":"=2.1.1"
+**Note:** If you do not have the permission to delete a repository from the GroIMP installation folder, you can prevent the plugin from being loaded by adding it to the //blacklisted// file.
-}
-</code>
+===== Plugin Manager =====
-==== Higher than condition ====
+The plugins can easily be updated, installed, or removed from the GUI with the
+[[user-guide:pluginmanager|Plugin Manager]].
+The plugin manager uses the [[:dev-guide:plugins-repository|plugin repositories]] to find plugin data. These repositories can be local or remote but need to follow the given structure.
-By default the plugin manager uses the "Higher than condition". It means that if a plugin depends on another, as long a a version newer of that plugin is available, the condition is met.