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     - [Update video constants](#update-video-constants)
  15     - [Add custom routes](#add-custom-routes)
  16   - [Client helpers (themes & plugins)](#client-helpers-themes--plugins)
  17   - [Plugin static route](#plugin-static-route)
  18     - [Translate](#translate)
  19     - [Get public settings](#get-public-settings)
  20   - [Publishing](#publishing)
  21 - [Write a plugin/theme](#write-a-plugintheme)
  22   - [Clone the quickstart repository](#clone-the-quickstart-repository)
  23   - [Configure your repository](#configure-your-repository)
  24   - [Update README](#update-readme)
  25   - [Update package.json](#update-packagejson)
  26   - [Write code](#write-code)
  27   - [Add translations](#add-translations)
  28   - [Test your plugin/theme](#test-your-plugintheme)
  29   - [Publish](#publish)
  30 - [Plugin & Theme hooks/helpers API](#plugin--theme-hookshelpers-api)
  31 - [Tips](#tips)
  32   - [Compatibility with PeerTube](#compatibility-with-peertube)
  33   - [Spam/moderation plugin](#spammoderation-plugin)
  34   - [Other plugin examples](#other-plugin-examples)
  35
  36 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
  37
  38 ## Concepts
  39
  40 Themes are exactly the same as plugins, except that:
  41  * Their name starts with `peertube-theme-` instead of `peertube-plugin-`
  42  * They cannot declare server code (so they cannot register server hooks or settings)
  43  * CSS files are loaded by client only if the theme is chosen by the administrator or the user
  44
  45 ### Hooks
  46
  47 A plugin registers functions in JavaScript to execute when PeerTube (server and client) fires events. There are 3 types of hooks:
  48  * `filter`: used to filter functions parameters or return values.
  49  For example to replace words in video comments, or change the videos list behaviour
  50  * `action`: used to do something after a certain trigger. For example to send a hook every time a video is published
  51  * `static`: same than `action` but PeerTube waits their execution
  52
  53 On server side, these hooks are registered by the `library` file defined in `package.json`.
  54
  55 ```json
  56 {
  57   ...,
  58   "library": "./main.js",
  59   ...,
  60 }
  61 ```
  62
  63 And `main.js` defines a `register` function:
  64
  65 Example:
  66
  67 ```js
  68 async function register ({
  69   registerHook,
  70   registerSetting,
  71   settingsManager,
  72   storageManager,
  73   videoCategoryManager,
  74   videoLicenceManager,
  75   videoLanguageManager,
  76   peertubeHelpers,
  77   getRouter
  78 }) {
  79   registerHook({
  80     target: 'action:application.listening',
  81     handler: () => displayHelloWorld()
  82   })
  83 }
  84 ```
  85
  86
  87 On client side, these hooks are registered by the `clientScripts` files defined in `package.json`.
  88 All client scripts have scopes so PeerTube client only loads scripts it needs:
  89
  90 ```json
  91 {
  92   ...,
  93   "clientScripts": [
  94     {
  95       "script": "client/common-client-plugin.js",
  96       "scopes": [ "common" ]
  97     },
  98     {
  99       "script": "client/video-watch-client-plugin.js",
 100       "scopes": [ "video-watch" ]
 101     }
 102   ],
 103   ...
 104 }
 105 ```
 106
 107 And these scripts also define a `register` function:
 108
 109 ```js
 110 function register ({ registerHook, peertubeHelpers }) {
 111   registerHook({
 112     target: 'action:application.init',
 113     handler: () => onApplicationInit(peertubeHelpers)
 114   })
 115 }
 116 ```
 117
 118 ### Static files
 119
 120 Plugins can declare static directories that PeerTube will serve (images for example)
 121 from `/plugins/{plugin-name}/{plugin-version}/static/`
 122 or `/themes/{theme-name}/{theme-version}/static/` routes.
 123
 124 ### CSS
 125
 126 Plugins can declare CSS files that PeerTube will automatically inject in the client.
 127 If you need to override existing style, you can use the `#custom-css` selector:
 128
 129 ```
 130 body#custom-css {
 131   color: red;
 132 }
 133
 134 #custom-css .header {
 135   background-color: red;
 136 }
 137 ```
 138
 139 ### Server helpers (only for plugins)
 140
 141 #### Settings
 142
 143 Plugins can register settings, that PeerTube will inject in the administration interface.
 144
 145 Example:
 146
 147 ```js
 148 registerSetting({
 149   name: 'admin-name',
 150   label: 'Admin name',
 151   type: 'input',
 152   default: 'my super name'
 153 })
 154
 155 const adminName = await settingsManager.getSetting('admin-name')
 156 ```
 157
 158 #### Storage
 159
 160 Plugins can store/load JSON data, that PeerTube will store in its database (so don't put files in there).
 161
 162 Example:
 163
 164 ```js
 165 const value = await storageManager.getData('mykey')
 166 await storageManager.storeData('mykey', { subkey: 'value' })
 167 ```
 168
 169 #### Update video constants
 170
 171 You can add/delete video categories, licences or languages using the appropriate managers:
 172
 173 ```js
 174 videoLanguageManager.addLanguage('al_bhed', 'Al Bhed')
 175 videoLanguageManager.deleteLanguage('fr')
 176
 177 videoCategoryManager.addCategory(42, 'Best category')
 178 videoCategoryManager.deleteCategory(1) // Music
 179
 180 videoLicenceManager.addLicence(42, 'Best licence')
 181 videoLicenceManager.deleteLicence(7) // Public domain
 182 ```
 183
 184 #### Add custom routes
 185
 186 You can create custom routes using an [express Router](https://expressjs.com/en/4x/api.html#router) for your plugin:
 187
 188 ```js
 189 const router = getRouter()
 190 router.get('/ping', (req, res) => res.json({ message: 'pong' }))
 191 ```
 192
 193 The `ping` route can be accessed using:
 194  * `/plugins/:pluginName/:pluginVersion/router/ping`
 195  * Or `/plugins/:pluginName/router/ping`
 196
 197
 198 ### Client helpers (themes & plugins)
 199
 200 ### Plugin static route
 201
 202 To get your plugin static route:
 203
 204 ```js
 205 const baseStaticUrl = peertubeHelpers.getBaseStaticRoute()
 206 const imageUrl = baseStaticUrl + '/images/chocobo.png'
 207 ```
 208
 209 #### Translate
 210
 211 You can translate some strings of your plugin (PeerTube will use your `translations` object of your `package.json` file):
 212
 213 ```js
 214 peertubeHelpers.translate('User name')
 215    .then(translation => console.log('Translated User name by ' + translation))
 216 ```
 217
 218 #### Get public settings
 219
 220 To get your public plugin settings:
 221
 222 ```js
 223 peertubeHelpers.getSettings()
 224   .then(s => {
 225     if (!s || !s['site-id'] || !s['url']) {
 226       console.error('Matomo settings are not set.')
 227       return
 228     }
 229
 230     // ...
 231   })
 232 ```
 233
 234
 235 ### Publishing
 236
 237 PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes
 238 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).
 239
 240 ## Write a plugin/theme
 241
 242 Steps:
 243  * Find a name for your plugin or your theme (must not have spaces, it can only contain lowercase letters and `-`)
 244  * Add the appropriate prefix:
 245    * If you develop a plugin, add `peertube-plugin-` prefix to your plugin name (for example: `peertube-plugin-mysupername`)
 246    * If you develop a theme, add `peertube-theme-` prefix to your theme name (for example: `peertube-theme-mysupertheme`)
 247  * Clone the quickstart repository
 248  * Configure your repository
 249  * Update `README.md`
 250  * Update `package.json`
 251  * Register hooks, add CSS and static files
 252  * Test your plugin/theme with a local PeerTube installation
 253  * Publish your plugin/theme on NPM
 254
 255 ### Clone the quickstart repository
 256
 257 If you develop a plugin, clone the `peertube-plugin-quickstart` repository:
 258
 259 ```
 260 $ git clone https://framagit.org/framasoft/peertube/peertube-plugin-quickstart.git peertube-plugin-mysupername
 261 ```
 262
 263 If you develop a theme, clone the `peertube-theme-quickstart` repository:
 264
 265 ```
 266 $ git clone https://framagit.org/framasoft/peertube/peertube-theme-quickstart.git peertube-theme-mysupername
 267 ```
 268
 269 ### Configure your repository
 270
 271 Set your repository URL:
 272
 273 ```
 274 $ cd peertube-plugin-mysupername # or cd peertube-theme-mysupername
 275 $ git remote set-url origin https://your-git-repo
 276 ```
 277
 278 ### Update README
 279
 280 Update `README.md` file:
 281
 282 ```
 283 $ $EDITOR README.md
 284 ```
 285
 286 ### Update package.json
 287
 288 Update the `package.json` fields:
 289    * `name` (should start with `peertube-plugin-` or `peertube-theme-`)
 290    * `description`
 291    * `homepage`
 292    * `author`
 293    * `bugs`
 294    * `engine.peertube` (the PeerTube version compatibility, must be `>=x.y.z` and nothing else)
 295
 296 **Caution:** Don't update or remove other keys, or PeerTube will not be able to index/install your plugin.
 297 If you don't need static directories, use an empty `object`:
 298
 299 ```json
 300 {
 301   ...,
 302   "staticDirs": {},
 303   ...
 304 }
 305 ```
 306
 307 And if you don't need CSS or client script files, use an empty `array`:
 308
 309 ```json
 310 {
 311   ...,
 312   "css": [],
 313   "clientScripts": [],
 314   ...
 315 }
 316 ```
 317
 318 ### Write code
 319
 320 Now you can register hooks or settings, write CSS and add static directories to your plugin or your theme :)
 321
 322 **Caution:** It's up to you to check the code you write will be compatible with the PeerTube NodeJS version,
 323 and will be supported by web browsers.
 324 If you want to write modern JavaScript, please use a transpiler like [Babel](https://babeljs.io/).
 325
 326 ### Add translations
 327
 328 If you want to translate strings of your plugin (like labels of your registered settings), create a file and add it to `package.json`:
 329
 330 ```json
 331 {
 332   ...,
 333   "translations": {
 334     "fr-FR": "./languages/fr.json",
 335     "pt-BR": "./languages/pt-BR.json"
 336   },
 337   ...
 338 }
 339 ```
 340
 341 The key should be one of the locales defined in [i18n.ts](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/i18n/i18n.ts).
 342 You **must** use the complete locales (`fr-FR` instead of `fr`).
 343
 344 Translation files are just objects, with the english sentence as the key and the translation as the value.
 345 `fr.json` could contain for example:
 346
 347 ```json
 348 {
 349   "Hello world": "Hello le monde"
 350 }
 351 ```
 352
 353 ### Test your plugin/theme
 354
 355 You'll need to have a local PeerTube instance:
 356  * Follow the [dev prerequisites](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#prerequisites)
 357  (to clone the repository, install dependencies and prepare the database)
 358  * Build PeerTube (`--light` to only build the english language):
 359
 360 ```
 361 $ npm run build -- --light
 362 ```
 363
 364  * Build the CLI:
 365
 366 ```
 367 $ npm run setup:cli
 368 ```
 369
 370  * Run PeerTube (you can access to your instance on http://localhost:9000):
 371
 372 ```
 373 $ NODE_ENV=test npm start
 374 ```
 375
 376  * Register the instance via the CLI:
 377
 378 ```
 379 $ node ./dist/server/tools/peertube.js auth add -u 'http://localhost:9000' -U 'root' --password 'test'
 380 ```
 381
 382 Then, you can install or reinstall your local plugin/theme by running:
 383
 384 ```
 385 $ node ./dist/server/tools/peertube.js plugins install --path /your/absolute/plugin-or-theme/path
 386 ```
 387
 388 ### Publish
 389
 390 Go in your plugin/theme directory, and run:
 391
 392 ```
 393 $ npm publish
 394 ```
 395
 396 Every time you want to publish another version of your plugin/theme, just update the `version` key from the `package.json`
 397 and republish it on NPM. Remember that the PeerTube index will take into account your new plugin/theme version after ~24 hours.
 398
 399
 400 ## Plugin & Theme hooks/helpers API
 401
 402 See the dedicated documentation: https://docs.joinpeertube.org/#/api-plugins
 403
 404
 405 ## Tips
 406
 407 ### Compatibility with PeerTube
 408
 409 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`).
 410 So please:
 411   * Don't make assumptions and check every parameter you want to use. For example:
 412
 413 ```js
 414 registerHook({
 415   target: 'filter:api.video.get.result',
 416   handler: video => {
 417     // We check the parameter exists and the name field exists too, to avoid exceptions
 418     if (video && video.name) video.name += ' <3'
 419
 420     return video
 421   }
 422 })
 423 ```
 424   * 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)
 425   * Don't use PeerTube dependencies. Use your own :)
 426
 427 If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` field of your `package.json` field.
 428 This way, older PeerTube versions will still use your old plugin, and new PeerTube versions will use your updated plugin.
 429
 430 ### Spam/moderation plugin
 431
 432 If you want to create an antispam/moderation plugin, you could use the following hooks:
 433  * `filter:api.video.upload.accept.result`: to accept or not local uploads
 434  * `filter:api.video-thread.create.accept.result`: to accept or not local thread
 435  * `filter:api.video-comment-reply.create.accept.result`: to accept or not local replies
 436  * `filter:api.video-threads.list.result`: to change/hide the text of threads
 437  * `filter:api.video-thread-comments.list.result`: to change/hide the text of replies
 438  * `filter:video.auto-blacklist.result`: to automatically blacklist local or remote videos
 439
 440 ### Other plugin examples
 441
 442 You can take a look to "official" PeerTube plugins if you want to take inspiration from them: https://framagit.org/framasoft/peertube/official-plugins