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