support/doc/plugins/guide.md

   1 # Plugins & Themes
   2
   3 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
   4 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
   5
   6
   7 - [Concepts](#concepts)
   8   - [Hooks](#hooks)
   9   - [Static files](#static-files)
  10   - [CSS](#css)
  11   - [Server helpers (only for plugins)](#server-helpers-only-for-plugins)
  12     - [Settings](#settings)
  13     - [Storage](#storage)
  14   - [Publishing](#publishing)
  15 - [Write a plugin/theme](#write-a-plugintheme)
  16   - [Clone the quickstart repository](#clone-the-quickstart-repository)
  17   - [Configure your repository](#configure-your-repository)
  18   - [Update README](#update-readme)
  19   - [Update package.json](#update-packagejson)
  20   - [Write code](#write-code)
  21   - [Test your plugin/theme](#test-your-plugintheme)
  22   - [Publish](#publish)
  23 - [Tips](#tips)
  24   - [Compatibility with PeerTube](#compatibility-with-peertube)
  25   - [Spam/moderation plugin](#spammoderation-plugin)
  26
  27 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
  28
  29 ## Concepts
  30
  31 Themes are exactly the same than plugins, except that:
  32  * Their name starts with `peertube-theme-` instead of `peertube-plugin-`
  33  * They cannot declare server code (so they cannot register server hooks or settings)
  34  * CSS files are loaded by client only if the theme is chosen by the administrator or the user
  35
  36 ### Hooks
  37
  38 A plugin registers functions in JavaScript to execute when PeerTube (server and client) fires events. There are 3 types of hooks:
  39  * `filter`: used to filter functions parameters or return values.
  40  For example to replace words in video comments, or change the videos list behaviour
  41  * `action`: used to do something after a certain trigger. For example to send a hook every time a video is published
  42  * `static`: same than `action` but PeerTube waits their execution
  43
  44 Example:
  45
  46 ```js
  47 // This register function is called by PeerTube, and **must** return a promise
  48 async function register ({ registerHook, registerSetting, settingsManager, storageManager, peertubeHelpers }) {
  49   registerHook({
  50     target: 'action:application.listening',
  51     handler: () => displayHelloWorld()
  52   })
  53 }
  54 ```
  55
  56 On server side, these hooks are registered by the `library` file defined in `package.json`.
  57
  58 ```json
  59 {
  60   ...,
  61   "library": "./main.js",
  62   ...,
  63 }
  64 ```
  65
  66
  67 On client side, these hooks are registered by the `clientScripts` files defined in `package.json`.
  68 All client scripts have scopes so PeerTube client only loads scripts it needs:
  69
  70 ```json
  71 {
  72   ...,
  73   "clientScripts": [
  74     {
  75       "script": "client/common-client-plugin.js",
  76       "scopes": [ "common" ]
  77     },
  78     {
  79       "script": "client/video-watch-client-plugin.js",
  80       "scopes": [ "video-watch" ]
  81     }
  82   ],
  83   ...
  84 }
  85 ```
  86
  87 ### Static files
  88
  89 Plugins can declare static directories that PeerTube will serve (images for example)
  90 from `/plugins/{plugin-name}/{plugin-version}/static/`
  91 or `/themes/{theme-name}/{theme-version}/static/` routes.
  92
  93 ### CSS
  94
  95 Plugins can declare CSS files that PeerTube will automatically inject in the client.
  96
  97 ### Server helpers (only for plugins)
  98
  99 #### Settings
 100
 101 Plugins can register settings, that PeerTube will inject in the administration interface.
 102
 103 Example:
 104
 105 ```js
 106 registerSetting({
 107   name: 'admin-name',
 108   label: 'Admin name',
 109   type: 'input',
 110   default: 'my super name'
 111 })
 112
 113 const adminName = await settingsManager.getSetting('admin-name')
 114 ```
 115
 116 #### Storage
 117
 118 Plugins can store/load JSON data, that PeerTube will store in its database (so don't put files in there).
 119
 120 Example:
 121
 122 ```js
 123 const value = await storageManager.getData('mykey')
 124 await storageManager.storeData('mykey', { subkey: 'value' })
 125 ```
 126
 127 ### Publishing
 128
 129 PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes
 130 take into account your plugin (after ~ 1 day). An official PeerTube index is available on https://packages.joinpeertube.org/ (it's just a REST API, so don't expect a beautiful website).
 131
 132 ## Write a plugin/theme
 133
 134 Steps:
 135  * Find a name for your plugin or your theme (must not have spaces, it can only contain lowercase letters and `-`)
 136  * Add the appropriate prefix:
 137    * If you develop a plugin, add `peertube-plugin-` prefix to your plugin name (for example: `peertube-plugin-mysupername`)
 138    * If you develop a theme, add `peertube-theme-` prefix to your theme name (for example: `peertube-theme-mysupertheme`)
 139  * Clone the quickstart repository
 140  * Configure your repository
 141  * Update `README.md`
 142  * Update `package.json`
 143  * Register hooks, add CSS and static files
 144  * Test your plugin/theme with a local PeerTube installation
 145  * Publish your plugin/theme on NPM
 146
 147 ### Clone the quickstart repository
 148
 149 If you develop a plugin, clone the `peertube-plugin-quickstart` repository:
 150
 151 ```
 152 $ git clone https://framagit.org/framasoft/peertube/peertube-plugin-quickstart.git peertube-plugin-mysupername
 153 ```
 154
 155 If you develop a theme, clone the `peertube-theme-quickstart` repository:
 156
 157 ```
 158 $ git clone https://framagit.org/framasoft/peertube/peertube-theme-quickstart.git peertube-theme-mysupername
 159 ```
 160
 161 ### Configure your repository
 162
 163 Set your repository URL:
 164
 165 ```
 166 $ cd peertube-plugin-mysupername # or cd peertube-theme-mysupername
 167 $ git remote set-url origin https://your-git-repo
 168 ```
 169
 170 ### Update README
 171
 172 Update `README.md` file:
 173
 174 ```
 175 $ $EDITOR README.md
 176 ```
 177
 178 ### Update package.json
 179
 180 Update the `package.json` fields:
 181    * `name` (should start with `peertube-plugin-` or `peertube-theme-`)
 182    * `description`
 183    * `homepage`
 184    * `author`
 185    * `bugs`
 186    * `engine.peertube` (the PeerTube version compatibility, must be `>=x.y.z` and nothing else)
 187
 188 **Caution:** Don't update or remove other keys, or PeerTube will not be able to index/install your plugin.
 189 If you don't need static directories, use an empty `object`:
 190
 191 ```json
 192 {
 193   ...,
 194   "staticDirs": {},
 195   ...
 196 }
 197 ```
 198
 199 And if you don't need CSS or client script files, use an empty `array`:
 200
 201 ```json
 202 {
 203   ...,
 204   "css": [],
 205   "clientScripts": [],
 206   ...
 207 }
 208 ```
 209
 210 ### Write code
 211
 212 Now you can register hooks or settings, write CSS and add static directories to your plugin or your theme :)
 213
 214 **Caution:** It's up to you to check the code you write will be compatible with the PeerTube NodeJS version,
 215 and will be supported by web browsers.
 216 If you want to write modern JavaScript, please use a transpiler like [Babel](https://babeljs.io/).
 217
 218 ### Test your plugin/theme
 219
 220 You'll need to have a local PeerTube instance:
 221  * Follow the [dev prerequisites](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#prerequisites)
 222  (to clone the repository, install dependencies and prepare the database)
 223  * Build PeerTube (`--light` to only build the english language):
 224
 225 ```
 226 $ npm run build -- --light
 227 ```
 228
 229  * Build the CLI:
 230
 231 ```
 232 $ npm run setup:cli
 233 ```
 234
 235  * Run PeerTube (you can access to your instance on http://localhost:9000):
 236
 237 ```
 238 $ NODE_ENV=test npm start
 239 ```
 240
 241  * Register the instance via the CLI:
 242
 243 ```
 244 $ node ./dist/server/tools/peertube.js auth add -u 'http://localhost:9000' -U 'root' --password 'test'
 245 ```
 246
 247 Then, you can install or reinstall your local plugin/theme by running:
 248
 249 ```
 250 $ node ./dist/server/tools/peertube.js plugins install --path /your/absolute/plugin-or-theme/path
 251 ```
 252
 253 ### Publish
 254
 255 Go in your plugin/theme directory, and run:
 256
 257 ```
 258 $ npm publish
 259 ```
 260
 261 Every time you want to publish another version of your plugin/theme, just update the `version` key from the `package.json`
 262 and republish it on NPM. Remember that the PeerTube index will take into account your new plugin/theme version after ~24 hours.
 263
 264
 265 ## Plugin & Theme hooks/helpers API
 266
 267 See the dedicated documentation: https://docs.joinpeertube.org/#/api-plugins
 268
 269
 270 ## Tips
 271
 272 ### Compatibility with PeerTube
 273
 274 Unfortunately, we don't have enough resources to provide hook compatibility between minor releases of PeerTube (for example between `1.2.x` and `1.3.x`).
 275 So please:
 276   * Don't make assumptions and check every parameter you want to use. For example:
 277
 278 ```js
 279 registerHook({
 280   target: 'filter:api.video.get.result',
 281   handler: video => {
 282     // We check the parameter exists and the name field exists too, to avoid exceptions
 283     if (video && video.name) video.name += ' <3'
 284
 285     return video
 286   }
 287 })
 288 ```
 289   * Don't try to require parent PeerTube modules, only use `peertubeHelpers`. If you need another helper or a specific hook, please [create an issue](https://github.com/Chocobozzz/PeerTube/issues/new)
 290   * Don't use PeerTube dependencies. Use your own :)
 291
 292 If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` field of your `package.json` field.
 293 This way, older PeerTube versions will still use your old plugin, and new PeerTube versions will use your updated plugin.
 294
 295 ### Spam/moderation plugin
 296
 297 If you want to create an antispam/moderation plugin, you could use the following hooks:
 298  * `filter:api.video.upload.accept.result`: to accept or not local uploads
 299  * `filter:api.video-thread.create.accept.result`: to accept or not local thread
 300  * `filter:api.video-comment-reply.create.accept.result`: to accept or not local replies
 301  * `filter:api.video-threads.list.result`: to change/hide the text of threads
 302  * `filter:api.video-thread-comments.list.result`: to change/hide the text of replies
 303  * `filter:video.auto-blacklist.result`: to automatically blacklist local or remote videos
 304