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