documenting plugins dev

docs/dev/plugin.md

@@ -16,16 +16,110 @@ Since **v.1.2.2** you can write your own plugin that react to event related acti
 >  
 > [**<u>Please share your plugins or your needs</u>**](/contacts)
 
-Plugins should be inside `./plugins` directory, this is an example:
+
+## Example
+Here is a complete example of plugins feature: [https://framagit.org/les/gancio/-/blob/master/plugins/gancioPluginExample.js](https://framagit.org/les/gancio/-/blob/master/plugins/gancioPluginExample.js) .
+
+## Basic plugin syntax
+
+A plugin is essentially an `index.js` file inside its own path in `./plugins`, e.g. `./plugins/my-example-plugin/index.js`
+```javascript
+module.exports = {
+  
+}
+```
+
+Plugins should be inside `./plugins` directory but you can specify another location using [`plugins_path`](https://gancio.org/install/config#plugins-path) configuration.
+
+## Plugin details
+A plugins **MUST** expose a `configuration` key where to specify its details:
 
 ```js
-const plugin = {
+module.exports = {
-  gancio: null,
+  configuration: {
-  load (gancio) {
+    name: 'Example',
-    console.error('Plugin GancioPluginExample loaded!')
+    author: 'lesion',
-    plugin.gancio = gancio
+    url: 'https://framagit.org/les/gancio/plugins/gancioPluginExample.js',
-  },
+    description: 'Example plugin',
+    settings: {
+      my_plugin_string_setting: {
+        type: 'TEXT',
+        description: 'My plugin string setting',
+        required: true,
+        hint: 'My plugin setting support <strong>html too</strong>'
+      },
+      enable_this_feature_in_my_plugin: {
+        type: 'CHECK',
+        description: 'My plugin best feature',
+        required: true,
+        hint: 'This feature is super dupe, enable it!'
+      },
+      min_post: {
+        type: 'NUMBER',
+        description: 'it supports number too'
+      },
+      my_default_language: {
+        description: 'My default language',
+        type: 'LIST',
+        items: ['it', 'en', 'fr']
+      }
+    }
+  }
+}
+```
 
+[![/assets/plugins/settings.png](/assets/plugins/settings.png)](/assets/plugins/settings.png){: data-fancybox="group" data-caption="Home"}
+
+
+## Load a plugin
+When a plugin is enabled by an administrator, Gancio will call the `load` method if specified:
+
+```js
+load ({ settings: gancio_settings, db, helpers, log}, settings) {
+
+  // access to your plugin local settings
+  console.info('Your local settings are in ', settings)
+  console.info(`For example, you can access to your default language setting by using ${settings.my_default_language}`)
+
+  // access to gancio settings
+  console.info(`Gancio settings are in ${gancio_settings}, e.g. ${gancio.settings.baseurl}`)
+
+  // log something
+  log.warn('This is a log entry from my example plugin')
+
+  // use the DB (since 1.6.14)
+  console.info(db.models.findAll())
+  console.info(db.query('CREATE TABLE IF NOT EXISTS myPluginTable'))
+}
+```
+
+## Expose an API <span class='label label-yellow'>since 1.6.4</span>
+
+Plugins could have public HTTP endpoints by exposing an express Router in routeAPI object.
+
+```js
+const express = require('express')
+const routeAPI = express.Router()
+
+routeAPI.get('/test', (req, res) => {
+  res.json('WOW!')
+})
+```
+
+This endpoint will be exposed at <your_instance>/api/plugin/<your_plugin_name>/test
+  
+
+## Access to DB <span class='label label-yellow'>since 1.6.4</span>
+TODO
+
+## Helpers <span class='label label-red'>DOCUMENTATION NEEDED</span>
+- randomString
+- sanitizeHTML
+- queryParamToBool
+
+## React to events
+
+```js
   onEventCreate (event) {
     const eventLink = `${plugin.gancio.settings.baseurl}/event/${event.slug}`
     if (!event.is_visible) {
@@ -42,10 +136,6 @@ const plugin = {
   onEventDelete (event) {
     console.error(`Event "${event.title}" deleted`)
   }
-}
-
-
-module.exports = plugin
 ```
 
 

docs/usage/cli.md

@@ -17,7 +17,7 @@ has_toc: true
 Gancio is distributed with an embedded CLI.
 To use the CLI you need to specify the `config.json` configuration file via `--config <your_config.json>` flag; by default the CLI will look for one in the current directory, so if your current directory is /opt/gancio (having followed the [installation instructions](/install/debian)) there is no need to specify it.
 
-#### Using CLI with Docker installation
+### Using CLI with Docker installation
 To use the CLI in a docker installation you can execute a shell inside the container with:
 `docker exec --workdir /home/node/data -it gancio  sh` and following the normal CLI usage or running commands with:
 
@@ -26,7 +26,7 @@ To use the CLI in a docker installation you can execute a shell inside the conta
 (the first "gancio" is the container name)
 
 
-## Users
+## Users <span class='label label-yellow'>since 1.6.14</span>
 All users related sub-commands starts with `gancio users`.
 Note that most of this actions could be done from administration panel (Admin > Users).
 
@@ -50,8 +50,6 @@ To create an user with administrator privileges use the `--admin` flag, e.g. `ga
 ### Reset password
 `gancio users reset-password <username|email>`
 
-> info "Changelog"
-> from: 1.6.14
 
 ### Change administrator privileges
 
@@ -60,6 +58,3 @@ To add administrator privileges to an user:
 
 To remove administrator privileges from an user:
 `gancio users unset-admin <username|email>`
-
-> info "Changelog"
-> from: 1.6.14

docs/usage/plugins.md

@@ -10,13 +10,12 @@ has_toc: true
 # Plugins
 {: .no_toc }
 
-This page is a guide to install plugins, if you want to develop one instead look [here](/dev/plugins)
+This page is a guide to install plugins, if you want to develop one instead look [here](/dev/plugins).  
+__Please note that some plugins are officially supported and distributed along with the release__
 
 1. TOC
 {:toc}
 
-
-
 ## Install
 
 To install a plugin you have to:
@@ -49,7 +48,7 @@ __with docker__
 docker-compose restart
 ```
 
-# List of plugins
+# List of embedded plugins
 
 ## __Telegram__
 
@@ -57,6 +56,5 @@ This plugin republishes events to Telegram channels or groups.
 The goal is to spread the info of our networks to the capitalist cyberspace, and pull otherwise isolated people to our radical and free part of the internet.
 
 - **Website**: [https://framagit.org/bcn.convocala/gancio-plugin-telegram-bridge](https://framagit.org/bcn.convocala/gancio-plugin-telegram-bridge)
-- **Download**: [gancio-plugin-telegram-bridge-v0.2.0.zip](https://framagit.org/les/gancio-plugin-telegram-bridge/-/archive/v0.2.0/gancio-plugin-telegram-bridge-v0.2.0.zip)
+- **Release**: https://framagit.org/bcn.convocala/gancio-plugin-telegram-bridge/-/commit/af0eed7b42242ba484d9828157f1be0355bba69b
-- **Release**: v0.2.0 / 10 Dec '22