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 #### Notifier
 210
 211 To notify the user with the PeerTube ToastModule:
 212
 213 ```js
 214 const { notifier } = peertubeHelpers
 215 notifier.success('Success message content.')
 216 notifier.error('Error message content.')
 217 ```
 218
 219 #### Translate
 220
 221 You can translate some strings of your plugin (PeerTube will use your `translations` object of your `package.json` file):
 222
 223 ```js
 224 peertubeHelpers.translate('User name')
 225    .then(translation => console.log('Translated User name by ' + translation))
 226 ```
 227
 228 #### Get public settings
 229
 230 To get your public plugin settings:
 231
 232 ```js
 233 peertubeHelpers.getSettings()
 234   .then(s => {
 235     if (!s || !s['site-id'] || !s['url']) {
 236       console.error('Matomo settings are not set.')
 237       return
 238     }
 239
 240     // ...
 241   })
 242 ```
 243
 244
 245 ### Publishing
 246
 247 PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes
 248 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).
 249
 250 ## Write a plugin/theme
 251
 252 Steps:
 253  * Find a name for your plugin or your theme (must not have spaces, it can only contain lowercase letters and `-`)
 254  * Add the appropriate prefix:
 255    * If you develop a plugin, add `peertube-plugin-` prefix to your plugin name (for example: `peertube-plugin-mysupername`)
 256    * If you develop a theme, add `peertube-theme-` prefix to your theme name (for example: `peertube-theme-mysupertheme`)
 257  * Clone the quickstart repository
 258  * Configure your repository
 259  * Update `README.md`
 260  * Update `package.json`
 261  * Register hooks, add CSS and static files
 262  * Test your plugin/theme with a local PeerTube installation
 263  * Publish your plugin/theme on NPM
 264
 265 ### Clone the quickstart repository
 266
 267 If you develop a plugin, clone the `peertube-plugin-quickstart` repository:
 268
 269 ```
 270 $ git clone https://framagit.org/framasoft/peertube/peertube-plugin-quickstart.git peertube-plugin-mysupername
 271 ```
 272
 273 If you develop a theme, clone the `peertube-theme-quickstart` repository:
 274
 275 ```
 276 $ git clone https://framagit.org/framasoft/peertube/peertube-theme-quickstart.git peertube-theme-mysupername
 277 ```
 278
 279 ### Configure your repository
 280
 281 Set your repository URL:
 282
 283 ```
 284 $ cd peertube-plugin-mysupername # or cd peertube-theme-mysupername
 285 $ git remote set-url origin https://your-git-repo
 286 ```
 287
 288 ### Update README
 289
 290 Update `README.md` file:
 291
 292 ```
 293 $ $EDITOR README.md
 294 ```
 295
 296 ### Update package.json
 297
 298 Update the `package.json` fields:
 299    * `name` (should start with `peertube-plugin-` or `peertube-theme-`)
 300    * `description`
 301    * `homepage`
 302    * `author`
 303    * `bugs`
 304    * `engine.peertube` (the PeerTube version compatibility, must be `>=x.y.z` and nothing else)
 305
 306 **Caution:** Don't update or remove other keys, or PeerTube will not be able to index/install your plugin.
 307 If you don't need static directories, use an empty `object`:
 308
 309 ```json
 310 {
 311   ...,
 312   "staticDirs": {},
 313   ...
 314 }
 315 ```
 316
 317 And if you don't need CSS or client script files, use an empty `array`:
 318
 319 ```json
 320 {
 321   ...,
 322   "css": [],
 323   "clientScripts": [],
 324   ...
 325 }
 326 ```
 327
 328 ### Write code
 329
 330 Now you can register hooks or settings, write CSS and add static directories to your plugin or your theme :)
 331
 332 **Caution:** It's up to you to check the code you write will be compatible with the PeerTube NodeJS version,
 333 and will be supported by web browsers.
 334 If you want to write modern JavaScript, please use a transpiler like [Babel](https://babeljs.io/).
 335
 336 ### Add translations
 337
 338 If you want to translate strings of your plugin (like labels of your registered settings), create a file and add it to `package.json`:
 339
 340 ```json
 341 {
 342   ...,
 343   "translations": {
 344     "fr-FR": "./languages/fr.json",
 345     "pt-BR": "./languages/pt-BR.json"
 346   },
 347   ...
 348 }
 349 ```
 350
 351 The key should be one of the locales defined in [i18n.ts](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/i18n/i18n.ts).
 352 You **must** use the complete locales (`fr-FR` instead of `fr`).
 353
 354 Translation files are just objects, with the english sentence as the key and the translation as the value.
 355 `fr.json` could contain for example:
 356
 357 ```json
 358 {
 359   "Hello world": "Hello le monde"
 360 }
 361 ```
 362
 363 ### Test your plugin/theme
 364
 365 You'll need to have a local PeerTube instance:
 366  * Follow the [dev prerequisites](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#prerequisites)
 367  (to clone the repository, install dependencies and prepare the database)
 368  * Build PeerTube (`--light` to only build the english language):
 369
 370 ```
 371 $ npm run build -- --light
 372 ```
 373
 374  * Build the CLI:
 375
 376 ```
 377 $ npm run setup:cli
 378 ```
 379
 380  * Run PeerTube (you can access to your instance on http://localhost:9000):
 381
 382 ```
 383 $ NODE_ENV=test npm start
 384 ```
 385
 386  * Register the instance via the CLI:
 387
 388 ```
 389 $ node ./dist/server/tools/peertube.js auth add -u 'http://localhost:9000' -U 'root' --password 'test'
 390 ```
 391
 392 Then, you can install or reinstall your local plugin/theme by running:
 393
 394 ```
 395 $ node ./dist/server/tools/peertube.js plugins install --path /your/absolute/plugin-or-theme/path
 396 ```
 397
 398 ### Publish
 399
 400 Go in your plugin/theme directory, and run:
 401
 402 ```
 403 $ npm publish
 404 ```
 405
 406 Every time you want to publish another version of your plugin/theme, just update the `version` key from the `package.json`
 407 and republish it on NPM. Remember that the PeerTube index will take into account your new plugin/theme version after ~24 hours.
 408
 409
 410 ## Plugin & Theme hooks/helpers API
 411
 412 See the dedicated documentation: https://docs.joinpeertube.org/#/api-plugins
 413
 414
 415 ## Tips
 416
 417 ### Compatibility with PeerTube
 418
 419 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`).
 420 So please:
 421   * Don't make assumptions and check every parameter you want to use. For example:
 422
 423 ```js
 424 registerHook({
 425   target: 'filter:api.video.get.result',
 426   handler: video => {
 427     // We check the parameter exists and the name field exists too, to avoid exceptions
 428     if (video && video.name) video.name += ' <3'
 429
 430     return video
 431   }
 432 })
 433 ```
 434   * 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)
 435   * Don't use PeerTube dependencies. Use your own :)
 436
 437 If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` field of your `package.json` field.
 438 This way, older PeerTube versions will still use your old plugin, and new PeerTube versions will use your updated plugin.
 439
 440 ### Spam/moderation plugin
 441
 442 If you want to create an antispam/moderation plugin, you could use the following hooks:
 443  * `filter:api.video.upload.accept.result`: to accept or not local uploads
 444  * `filter:api.video-thread.create.accept.result`: to accept or not local thread
 445  * `filter:api.video-comment-reply.create.accept.result`: to accept or not local replies
 446  * `filter:api.video-threads.list.result`: to change/hide the text of threads
 447  * `filter:api.video-thread-comments.list.result`: to change/hide the text of replies
 448  * `filter:video.auto-blacklist.result`: to automatically blacklist local or remote videos
 449
 450 ### Other plugin examples
 451
 452 You can take a look to "official" PeerTube plugins if you want to take inspiration from them: https://framagit.org/framasoft/peertube/official-plugins