]>
Commit | Line | Data |
---|---|---|
662e5d4f C |
1 | # Plugins & Themes |
2 | ||
d8e9a42c C |
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) | |
7545a094 C |
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) | |
d8e9a42c C |
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) | |
7545a094 | 26 | - [Add translations](#add-translations) |
d8e9a42c C |
27 | - [Test your plugin/theme](#test-your-plugintheme) |
28 | - [Publish](#publish) | |
7545a094 | 29 | - [Plugin & Theme hooks/helpers API](#plugin--theme-hookshelpers-api) |
d8e9a42c C |
30 | - [Tips](#tips) |
31 | - [Compatibility with PeerTube](#compatibility-with-peertube) | |
32 | - [Spam/moderation plugin](#spammoderation-plugin) | |
112be80e | 33 | - [Other plugin examples](#other-plugin-examples) |
d8e9a42c C |
34 | |
35 | <!-- END doctoc generated TOC please keep comment here to allow auto update --> | |
36 | ||
662e5d4f C |
37 | ## Concepts |
38 | ||
32d7f2b7 | 39 | Themes are exactly the same as plugins, except that: |
662e5d4f C |
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 | |
662e5d4f C |
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 | ||
7545a094 C |
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 | ||
662e5d4f C |
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 | ||
7545a094 C |
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 | ||
662e5d4f C |
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. | |
7545a094 C |
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 | ``` | |
662e5d4f | 135 | |
9fa6ca16 | 136 | ### Server helpers (only for plugins) |
662e5d4f C |
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 | ||
d8e9a42c | 155 | #### Storage |
662e5d4f C |
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') | |
9fa6ca16 | 163 | await storageManager.storeData('mykey', { subkey: 'value' }) |
662e5d4f C |
164 | ``` |
165 | ||
7545a094 C |
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 | ||
662e5d4f C |
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 | ||
9fa6ca16 | 290 | And if you don't need CSS or client script files, use an empty `array`: |
662e5d4f C |
291 | |
292 | ```json | |
293 | { | |
294 | ..., | |
295 | "css": [], | |
9fa6ca16 | 296 | "clientScripts": [], |
662e5d4f C |
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 | ||
7545a094 C |
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 | ||
112be80e C |
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 | ||
662e5d4f C |
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 | |
9fa6ca16 C |
345 | ``` |
346 | ||
347 | * Build the CLI: | |
348 | ||
349 | ``` | |
350 | $ npm run setup:cli | |
662e5d4f C |
351 | ``` |
352 | ||
9fa6ca16 | 353 | * Run PeerTube (you can access to your instance on http://localhost:9000): |
662e5d4f C |
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 | ||
d8e9a42c | 382 | |
bfa1a32b C |
383 | ## Plugin & Theme hooks/helpers API |
384 | ||
195474f9 | 385 | See the dedicated documentation: https://docs.joinpeertube.org/#/api-plugins |
bfa1a32b C |
386 | |
387 | ||
d8e9a42c C |
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 | ``` | |
51326912 | 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) |
d8e9a42c C |
408 | * Don't use PeerTube dependencies. Use your own :) |
409 | ||
51326912 | 410 | If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` field of your `package.json` field. |
d8e9a42c C |
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 | ||
112be80e C |
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 |