documenting plugins dev
This commit is contained in:
lesion
@@ -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 = {
|
||||
gancio: null,
|
||||
load (gancio) {
|
||||
console.error('Plugin GancioPluginExample loaded!')
|
||||
plugin.gancio = gancio
|
||||
},
|
||||
module.exports = {
|
||||
configuration: {
|
||||
name: 'Example',
|
||||
author: 'lesion',
|
||||
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){: 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
|
||||
```
|
||||
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -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**: v0.2.0 / 10 Dec '22
|
||||
- **Release**: https://framagit.org/bcn.convocala/gancio-plugin-telegram-bridge/-/commit/af0eed7b42242ba484d9828157f1be0355bba69b
|
||||
|
||||
|
||||
Reference in New Issue
Block a user