]>
Commit | Line | Data |
---|---|---|
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 | - [Add external auth methods](#add-external-auth-methods) | |
17 | - [Client helpers (themes & plugins)](#client-helpers-themes--plugins) | |
18 | - [Plugin static route](#plugin-static-route) | |
19 | - [Notifier](#notifier) | |
20 | - [Markdown Renderer](#markdown-renderer) | |
21 | - [Custom Modal](#custom-modal) | |
22 | - [Translate](#translate) | |
23 | - [Get public settings](#get-public-settings) | |
24 | - [Add custom fields to video form](#add-custom-fields-to-video-form) | |
25 | - [Add new transcoding profiles](#add-new-transcoding-profiles) | |
26 | - [Publishing](#publishing) | |
27 | - [Write a plugin/theme](#write-a-plugintheme) | |
28 | - [Clone the quickstart repository](#clone-the-quickstart-repository) | |
29 | - [Configure your repository](#configure-your-repository) | |
30 | - [Update README](#update-readme) | |
31 | - [Update package.json](#update-packagejson) | |
32 | - [Write code](#write-code) | |
33 | - [Add translations](#add-translations) | |
34 | - [Build your plugin](#build-your-plugin) | |
35 | - [Test your plugin/theme](#test-your-plugintheme) | |
36 | - [Publish](#publish) | |
37 | - [Plugin & Theme hooks/helpers API](#plugin--theme-hookshelpers-api) | |
38 | - [Tips](#tips) | |
39 | - [Compatibility with PeerTube](#compatibility-with-peertube) | |
40 | - [Spam/moderation plugin](#spammoderation-plugin) | |
41 | - [Other plugin examples](#other-plugin-examples) | |
42 | ||
43 | <!-- END doctoc generated TOC please keep comment here to allow auto update --> | |
44 | ||
45 | ## Concepts | |
46 | ||
47 | Themes are exactly the same as plugins, except that: | |
48 | * Their name starts with `peertube-theme-` instead of `peertube-plugin-` | |
49 | * They cannot declare server code (so they cannot register server hooks or settings) | |
50 | * CSS files are loaded by client only if the theme is chosen by the administrator or the user | |
51 | ||
52 | ### Hooks | |
53 | ||
54 | A plugin registers functions in JavaScript to execute when PeerTube (server and client) fires events. There are 3 types of hooks: | |
55 | * `filter`: used to filter functions parameters or return values. | |
56 | For example to replace words in video comments, or change the videos list behaviour | |
57 | * `action`: used to do something after a certain trigger. For example to send a hook every time a video is published | |
58 | * `static`: same than `action` but PeerTube waits their execution | |
59 | ||
60 | On server side, these hooks are registered by the `library` file defined in `package.json`. | |
61 | ||
62 | ```json | |
63 | { | |
64 | ..., | |
65 | "library": "./main.js", | |
66 | ..., | |
67 | } | |
68 | ``` | |
69 | ||
70 | And `main.js` defines a `register` function: | |
71 | ||
72 | Example: | |
73 | ||
74 | ```js | |
75 | async function register ({ | |
76 | registerHook, | |
77 | ||
78 | registerSetting, | |
79 | settingsManager, | |
80 | ||
81 | storageManager, | |
82 | ||
83 | videoCategoryManager, | |
84 | videoLicenceManager, | |
85 | videoLanguageManager, | |
86 | ||
87 | peertubeHelpers, | |
88 | ||
89 | getRouter, | |
90 | ||
91 | registerExternalAuth, | |
92 | unregisterExternalAuth, | |
93 | registerIdAndPassAuth, | |
94 | unregisterIdAndPassAuth | |
95 | }) { | |
96 | registerHook({ | |
97 | target: 'action:application.listening', | |
98 | handler: () => displayHelloWorld() | |
99 | }) | |
100 | } | |
101 | ``` | |
102 | ||
103 | ||
104 | On client side, these hooks are registered by the `clientScripts` files defined in `package.json`. | |
105 | All client scripts have scopes so PeerTube client only loads scripts it needs: | |
106 | ||
107 | ```json | |
108 | { | |
109 | ..., | |
110 | "clientScripts": [ | |
111 | { | |
112 | "script": "client/common-client-plugin.js", | |
113 | "scopes": [ "common" ] | |
114 | }, | |
115 | { | |
116 | "script": "client/video-watch-client-plugin.js", | |
117 | "scopes": [ "video-watch" ] | |
118 | } | |
119 | ], | |
120 | ... | |
121 | } | |
122 | ``` | |
123 | ||
124 | And these scripts also define a `register` function: | |
125 | ||
126 | ```js | |
127 | function register ({ registerHook, peertubeHelpers }) { | |
128 | registerHook({ | |
129 | target: 'action:application.init', | |
130 | handler: () => onApplicationInit(peertubeHelpers) | |
131 | }) | |
132 | } | |
133 | ``` | |
134 | ||
135 | ### Static files | |
136 | ||
137 | Plugins can declare static directories that PeerTube will serve (images for example) | |
138 | from `/plugins/{plugin-name}/{plugin-version}/static/` | |
139 | or `/themes/{theme-name}/{theme-version}/static/` routes. | |
140 | ||
141 | ### CSS | |
142 | ||
143 | Plugins can declare CSS files that PeerTube will automatically inject in the client. | |
144 | If you need to override existing style, you can use the `#custom-css` selector: | |
145 | ||
146 | ``` | |
147 | body#custom-css { | |
148 | color: red; | |
149 | } | |
150 | ||
151 | #custom-css .header { | |
152 | background-color: red; | |
153 | } | |
154 | ``` | |
155 | ||
156 | ### Server helpers (only for plugins) | |
157 | ||
158 | #### Settings | |
159 | ||
160 | Plugins can register settings, that PeerTube will inject in the administration interface. | |
161 | ||
162 | Example: | |
163 | ||
164 | ```js | |
165 | registerSetting({ | |
166 | name: 'admin-name', | |
167 | label: 'Admin name', | |
168 | type: 'input', | |
169 | // type: input | input-checkbox | input-password | input-textarea | markdown-text | markdown-enhanced | |
170 | default: 'my super name' | |
171 | }) | |
172 | ||
173 | const adminName = await settingsManager.getSetting('admin-name') | |
174 | ||
175 | const result = await settingsManager.getSettings([ 'admin-name', 'admin-password' ]) | |
176 | result['admin-name] | |
177 | ||
178 | settingsManager.onSettingsChange(settings => { | |
179 | settings['admin-name]) | |
180 | }) | |
181 | ``` | |
182 | ||
183 | #### Storage | |
184 | ||
185 | Plugins can store/load JSON data, that PeerTube will store in its database (so don't put files in there). | |
186 | ||
187 | Example: | |
188 | ||
189 | ```js | |
190 | const value = await storageManager.getData('mykey') | |
191 | await storageManager.storeData('mykey', { subkey: 'value' }) | |
192 | ``` | |
193 | ||
194 | #### Update video constants | |
195 | ||
196 | You can add/delete video categories, licences or languages using the appropriate managers: | |
197 | ||
198 | ```js | |
199 | videoLanguageManager.addLanguage('al_bhed', 'Al Bhed') | |
200 | videoLanguageManager.deleteLanguage('fr') | |
201 | ||
202 | videoCategoryManager.addCategory(42, 'Best category') | |
203 | videoCategoryManager.deleteCategory(1) // Music | |
204 | ||
205 | videoLicenceManager.addLicence(42, 'Best licence') | |
206 | videoLicenceManager.deleteLicence(7) // Public domain | |
207 | ||
208 | videoPrivacyManager.deletePrivacy(2) // Remove Unlisted video privacy | |
209 | playlistPrivacyManager.deletePlaylistPrivacy(3) // Remove Private video playlist privacy | |
210 | ``` | |
211 | ||
212 | #### Add custom routes | |
213 | ||
214 | You can create custom routes using an [express Router](https://expressjs.com/en/4x/api.html#router) for your plugin: | |
215 | ||
216 | ```js | |
217 | const router = getRouter() | |
218 | router.get('/ping', (req, res) => res.json({ message: 'pong' })) | |
219 | ``` | |
220 | ||
221 | The `ping` route can be accessed using: | |
222 | * `/plugins/:pluginName/:pluginVersion/router/ping` | |
223 | * Or `/plugins/:pluginName/router/ping` | |
224 | ||
225 | ||
226 | #### Add external auth methods | |
227 | ||
228 | If you want to add a classic username/email and password auth method (like [LDAP](https://framagit.org/framasoft/peertube/official-plugins/-/tree/master/peertube-plugin-auth-ldap) for example): | |
229 | ||
230 | ```js | |
231 | registerIdAndPassAuth({ | |
232 | authName: 'my-auth-method', | |
233 | ||
234 | // PeerTube will try all id and pass plugins in the weight DESC order | |
235 | // Exposing this value in the plugin settings could be interesting | |
236 | getWeight: () => 60, | |
237 | ||
238 | // Optional function called by PeerTube when the user clicked on the logout button | |
239 | onLogout: user => { | |
240 | console.log('User %s logged out.', user.username') | |
241 | }, | |
242 | ||
243 | // Optional function called by PeerTube when the access token or refresh token are generated/refreshed | |
244 | hookTokenValidity: ({ token, type }) => { | |
245 | if (type === 'access') return { valid: true } | |
246 | if (type === 'refresh') return { valid: false } | |
247 | }, | |
248 | ||
249 | // Used by PeerTube when the user tries to authenticate | |
250 | login: ({ id, password }) => { | |
251 | if (id === 'user' && password === 'super password') { | |
252 | return { | |
253 | username: 'user' | |
254 | email: 'user@example.com' | |
255 | role: 2 | |
256 | displayName: 'User display name' | |
257 | } | |
258 | } | |
259 | ||
260 | // Auth failed | |
261 | return null | |
262 | } | |
263 | }) | |
264 | ||
265 | // Unregister this auth method | |
266 | unregisterIdAndPassAuth('my-auth-method') | |
267 | ``` | |
268 | ||
269 | You can also add an external auth method (like [OpenID](https://framagit.org/framasoft/peertube/official-plugins/-/tree/master/peertube-plugin-auth-openid-connect), [SAML2](https://framagit.org/framasoft/peertube/official-plugins/-/tree/master/peertube-plugin-auth-saml2) etc): | |
270 | ||
271 | ```js | |
272 | // result contains the userAuthenticated auth method you can call to authenticate a user | |
273 | const result = registerExternalAuth({ | |
274 | authName: 'my-auth-method', | |
275 | ||
276 | // Will be displayed in a button next to the login form | |
277 | authDisplayName: () => 'Auth method' | |
278 | ||
279 | // If the user click on the auth button, PeerTube will forward the request in this function | |
280 | onAuthRequest: (req, res) => { | |
281 | res.redirect('https://external-auth.example.com/auth') | |
282 | }, | |
283 | ||
284 | // Same than registerIdAndPassAuth option | |
285 | // onLogout: ... | |
286 | ||
287 | // Same than registerIdAndPassAuth option | |
288 | // hookTokenValidity: ... | |
289 | }) | |
290 | ||
291 | router.use('/external-auth-callback', (req, res) => { | |
292 | // Forward the request to PeerTube | |
293 | result.userAuthenticated({ | |
294 | req, | |
295 | res, | |
296 | username: 'user' | |
297 | email: 'user@example.com' | |
298 | role: 2 | |
299 | displayName: 'User display name' | |
300 | }) | |
301 | }) | |
302 | ||
303 | // Unregister this external auth method | |
304 | unregisterExternalAuth('my-auth-method) | |
305 | ``` | |
306 | ||
307 | ### Client helpers (themes & plugins) | |
308 | ||
309 | #### Plugin static route | |
310 | ||
311 | To get your plugin static route: | |
312 | ||
313 | ```js | |
314 | const baseStaticUrl = peertubeHelpers.getBaseStaticRoute() | |
315 | const imageUrl = baseStaticUrl + '/images/chocobo.png' | |
316 | ``` | |
317 | ||
318 | #### Notifier | |
319 | ||
320 | To notify the user with the PeerTube ToastModule: | |
321 | ||
322 | ```js | |
323 | const { notifier } = peertubeHelpers | |
324 | notifier.success('Success message content.') | |
325 | notifier.error('Error message content.') | |
326 | ``` | |
327 | ||
328 | #### Markdown Renderer | |
329 | ||
330 | To render a formatted markdown text to HTML: | |
331 | ||
332 | ```js | |
333 | const { markdownRenderer } = peertubeHelpers | |
334 | ||
335 | await markdownRenderer.textMarkdownToHTML('**My Bold Text**') | |
336 | // return <strong>My Bold Text</strong> | |
337 | ||
338 | await markdownRenderer.enhancedMarkdownToHTML('![alt-img](http://.../my-image.jpg)') | |
339 | // return <img alt=alt-img src=http://.../my-image.jpg /> | |
340 | ``` | |
341 | ||
342 | #### Custom Modal | |
343 | ||
344 | To show a custom modal: | |
345 | ||
346 | ```js | |
347 | peertubeHelpers.showModal({ | |
348 | title: 'My custom modal title', | |
349 | content: '<p>My custom modal content</p>', | |
350 | // Optionals parameters : | |
351 | // show close icon | |
352 | close: true, | |
353 | // show cancel button and call action() after hiding modal | |
354 | cancel: { value: 'cancel', action: () => {} }, | |
355 | // show confirm button and call action() after hiding modal | |
356 | confirm: { value: 'confirm', action: () => {} }, | |
357 | }) | |
358 | ``` | |
359 | ||
360 | #### Translate | |
361 | ||
362 | You can translate some strings of your plugin (PeerTube will use your `translations` object of your `package.json` file): | |
363 | ||
364 | ```js | |
365 | peertubeHelpers.translate('User name') | |
366 | .then(translation => console.log('Translated User name by ' + translation)) | |
367 | ``` | |
368 | ||
369 | #### Get public settings | |
370 | ||
371 | To get your public plugin settings: | |
372 | ||
373 | ```js | |
374 | peertubeHelpers.getSettings() | |
375 | .then(s => { | |
376 | if (!s || !s['site-id'] || !s['url']) { | |
377 | console.error('Matomo settings are not set.') | |
378 | return | |
379 | } | |
380 | ||
381 | // ... | |
382 | }) | |
383 | ``` | |
384 | ||
385 | #### Add custom fields to video form | |
386 | ||
387 | To add custom fields in the video form (in *Plugin settings* tab): | |
388 | ||
389 | ```js | |
390 | async function register ({ registerVideoField, peertubeHelpers }) { | |
391 | const descriptionHTML = await peertubeHelpers.translate(descriptionSource) | |
392 | const commonOptions = { | |
393 | name: 'my-field-name, | |
394 | label: 'My added field', | |
395 | descriptionHTML: 'Optional description', | |
396 | type: 'input-textarea', | |
397 | default: '' | |
398 | } | |
399 | ||
400 | for (const type of [ 'upload', 'import-url', 'import-torrent', 'update' ]) { | |
401 | registerVideoField(commonOptions, { type }) | |
402 | } | |
403 | } | |
404 | ``` | |
405 | ||
406 | PeerTube will send this field value in `body.pluginData['my-field-name']` and fetch it from `video.pluginData['my-field-name']`. | |
407 | ||
408 | So for example, if you want to store an additional metadata for videos, register the following hooks in **server**: | |
409 | ||
410 | ```js | |
411 | async function register ({ | |
412 | registerHook, | |
413 | storageManager | |
414 | }) { | |
415 | const fieldName = 'my-field-name' | |
416 | ||
417 | // Store data associated to this video | |
418 | registerHook({ | |
419 | target: 'action:api.video.updated', | |
420 | handler: ({ video, body }) => { | |
421 | if (!body.pluginData) return | |
422 | ||
423 | const value = body.pluginData[fieldName] | |
424 | if (!value) return | |
425 | ||
426 | storageManager.storeData(fieldName + '-' + video.id, value) | |
427 | } | |
428 | }) | |
429 | ||
430 | // Add your custom value to the video, so the client autofill your field using the previously stored value | |
431 | registerHook({ | |
432 | target: 'filter:api.video.get.result', | |
433 | handler: async (video) => { | |
434 | if (!video) return video | |
435 | if (!video.pluginData) video.pluginData = {} | |
436 | ||
437 | const result = await storageManager.getData(fieldName + '-' + video.id) | |
438 | video.pluginData[fieldName] = result | |
439 | ||
440 | return video | |
441 | } | |
442 | }) | |
443 | } | |
444 | ``` | |
445 | ||
446 | #### Add new transcoding profiles | |
447 | ||
448 | Adding transcoding profiles allow admins to change ffmpeg encoding parameters and/or encoders. | |
449 | A transcoding profile has to be chosen by the admin of the instance using the admin configuration. | |
450 | ||
451 | ```js | |
452 | async function register ({ | |
453 | transcodingManager | |
454 | }) { | |
455 | ||
456 | // Adapt bitrate when using libx264 encoder | |
457 | { | |
458 | const builder = (options) => { | |
459 | const { input, resolution, fps, streamNum } = options | |
460 | ||
461 | const streamString = streamNum ? ':' + streamNum : '' | |
462 | ||
463 | // You can also return a promise | |
464 | return { | |
465 | outputOptions: [ | |
466 | // Use a custom bitrate | |
467 | '-b' + streamString + ' 10K' | |
468 | ] | |
469 | } | |
470 | } | |
471 | ||
472 | const encoder = 'libx264' | |
473 | const profileName = 'low-quality' | |
474 | ||
475 | // Support this profile for VOD transcoding | |
476 | transcodingManager.addVODProfile(encoder, profileName, builder) | |
477 | ||
478 | // And/Or support this profile for live transcoding | |
479 | transcodingManager.addLiveProfile(encoder, profileName, builder) | |
480 | } | |
481 | ||
482 | { | |
483 | const builder = (options) => { | |
484 | const { streamNum } = options | |
485 | ||
486 | const streamString = streamNum ? ':' + streamNum : '' | |
487 | ||
488 | // Always copy stream when PeerTube use libfdk_aac or aac encoders | |
489 | return { | |
490 | copy: true | |
491 | } | |
492 | } | |
493 | ||
494 | const profileName = 'copy-audio' | |
495 | ||
496 | for (const encoder of [ 'libfdk_aac', 'aac' ]) { | |
497 | transcodingManager.addVODProfile(encoder, profileName, builder) | |
498 | } | |
499 | } | |
500 | ``` | |
501 | ||
502 | PeerTube will try different encoders depending on their priority. | |
503 | If the encoder is not available in the current transcoding profile or in ffmpeg, it tries the next one. | |
504 | Plugins can change the order of these encoders and add their custom encoders: | |
505 | ||
506 | ```js | |
507 | async function register ({ | |
508 | transcodingManager | |
509 | }) { | |
510 | ||
511 | // Adapt bitrate when using libx264 encoder | |
512 | { | |
513 | const builder = () => { | |
514 | return { | |
515 | outputOptions: [] | |
516 | } | |
517 | } | |
518 | ||
519 | // Support libopus and libvpx-vp9 encoders (these codecs could be incompatible with the player) | |
520 | transcodingManager.addVODProfile('libopus', 'test-vod-profile', builder) | |
521 | ||
522 | // Default priorities are ~100 | |
523 | // Lowest priority = 1 | |
524 | transcodingManager.addVODEncoderPriority('audio', 'libopus', 1000) | |
525 | ||
526 | transcodingManager.addVODProfile('libvpx-vp9', 'test-vod-profile', builder) | |
527 | transcodingManager.addVODEncoderPriority('video', 'libvpx-vp9', 1000) | |
528 | ||
529 | transcodingManager.addLiveProfile('libopus', 'test-live-profile', builder) | |
530 | transcodingManager.addLiveEncoderPriority('audio', 'libopus', 1000) | |
531 | } | |
532 | ``` | |
533 | ||
534 | ||
535 | ### Publishing | |
536 | ||
537 | PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes | |
538 | 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). | |
539 | ||
540 | ## Write a plugin/theme | |
541 | ||
542 | Steps: | |
543 | * Find a name for your plugin or your theme (must not have spaces, it can only contain lowercase letters and `-`) | |
544 | * Add the appropriate prefix: | |
545 | * If you develop a plugin, add `peertube-plugin-` prefix to your plugin name (for example: `peertube-plugin-mysupername`) | |
546 | * If you develop a theme, add `peertube-theme-` prefix to your theme name (for example: `peertube-theme-mysupertheme`) | |
547 | * Clone the quickstart repository | |
548 | * Configure your repository | |
549 | * Update `README.md` | |
550 | * Update `package.json` | |
551 | * Register hooks, add CSS and static files | |
552 | * Test your plugin/theme with a local PeerTube installation | |
553 | * Publish your plugin/theme on NPM | |
554 | ||
555 | ### Clone the quickstart repository | |
556 | ||
557 | If you develop a plugin, clone the `peertube-plugin-quickstart` repository: | |
558 | ||
559 | ``` | |
560 | $ git clone https://framagit.org/framasoft/peertube/peertube-plugin-quickstart.git peertube-plugin-mysupername | |
561 | ``` | |
562 | ||
563 | If you develop a theme, clone the `peertube-theme-quickstart` repository: | |
564 | ||
565 | ``` | |
566 | $ git clone https://framagit.org/framasoft/peertube/peertube-theme-quickstart.git peertube-theme-mysupername | |
567 | ``` | |
568 | ||
569 | ### Configure your repository | |
570 | ||
571 | Set your repository URL: | |
572 | ||
573 | ``` | |
574 | $ cd peertube-plugin-mysupername # or cd peertube-theme-mysupername | |
575 | $ git remote set-url origin https://your-git-repo | |
576 | ``` | |
577 | ||
578 | ### Update README | |
579 | ||
580 | Update `README.md` file: | |
581 | ||
582 | ``` | |
583 | $ $EDITOR README.md | |
584 | ``` | |
585 | ||
586 | ### Update package.json | |
587 | ||
588 | Update the `package.json` fields: | |
589 | * `name` (should start with `peertube-plugin-` or `peertube-theme-`) | |
590 | * `description` | |
591 | * `homepage` | |
592 | * `author` | |
593 | * `bugs` | |
594 | * `engine.peertube` (the PeerTube version compatibility, must be `>=x.y.z` and nothing else) | |
595 | ||
596 | **Caution:** Don't update or remove other keys, or PeerTube will not be able to index/install your plugin. | |
597 | If you don't need static directories, use an empty `object`: | |
598 | ||
599 | ```json | |
600 | { | |
601 | ..., | |
602 | "staticDirs": {}, | |
603 | ... | |
604 | } | |
605 | ``` | |
606 | ||
607 | And if you don't need CSS or client script files, use an empty `array`: | |
608 | ||
609 | ```json | |
610 | { | |
611 | ..., | |
612 | "css": [], | |
613 | "clientScripts": [], | |
614 | ... | |
615 | } | |
616 | ``` | |
617 | ||
618 | ### Write code | |
619 | ||
620 | Now you can register hooks or settings, write CSS and add static directories to your plugin or your theme :) | |
621 | ||
622 | **Caution:** It's up to you to check the code you write will be compatible with the PeerTube NodeJS version, | |
623 | and will be supported by web browsers. | |
624 | If you want to write modern JavaScript, please use a transpiler like [Babel](https://babeljs.io/). | |
625 | ||
626 | ### Add translations | |
627 | ||
628 | If you want to translate strings of your plugin (like labels of your registered settings), create a file and add it to `package.json`: | |
629 | ||
630 | ```json | |
631 | { | |
632 | ..., | |
633 | "translations": { | |
634 | "fr-FR": "./languages/fr.json", | |
635 | "pt-BR": "./languages/pt-BR.json" | |
636 | }, | |
637 | ... | |
638 | } | |
639 | ``` | |
640 | ||
641 | The key should be one of the locales defined in [i18n.ts](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/i18n/i18n.ts). | |
642 | You **must** use the complete locales (`fr-FR` instead of `fr`). | |
643 | ||
644 | Translation files are just objects, with the english sentence as the key and the translation as the value. | |
645 | `fr.json` could contain for example: | |
646 | ||
647 | ```json | |
648 | { | |
649 | "Hello world": "Hello le monde" | |
650 | } | |
651 | ``` | |
652 | ||
653 | ### Build your plugin | |
654 | ||
655 | If you added client scripts, you'll need to build them using webpack. | |
656 | ||
657 | Install webpack: | |
658 | ||
659 | ``` | |
660 | $ npm install | |
661 | ``` | |
662 | ||
663 | Add/update your files in the `clientFiles` array of `webpack.config.js`: | |
664 | ||
665 | ``` | |
666 | $ $EDITOR ./webpack.config.js | |
667 | ``` | |
668 | ||
669 | Build your client files: | |
670 | ||
671 | ``` | |
672 | $ npm run build | |
673 | ``` | |
674 | ||
675 | You built files are in the `dist/` directory. Check `package.json` to correctly point to them. | |
676 | ||
677 | ||
678 | ### Test your plugin/theme | |
679 | ||
680 | You'll need to have a local PeerTube instance: | |
681 | * Follow the [dev prerequisites](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#prerequisites) | |
682 | (to clone the repository, install dependencies and prepare the database) | |
683 | * Build PeerTube (`--light` to only build the english language): | |
684 | ||
685 | ``` | |
686 | $ npm run build -- --light | |
687 | ``` | |
688 | ||
689 | * Build the CLI: | |
690 | ||
691 | ``` | |
692 | $ npm run setup:cli | |
693 | ``` | |
694 | ||
695 | * Run PeerTube (you can access to your instance on http://localhost:9000): | |
696 | ||
697 | ``` | |
698 | $ NODE_ENV=test npm start | |
699 | ``` | |
700 | ||
701 | * Register the instance via the CLI: | |
702 | ||
703 | ``` | |
704 | $ node ./dist/server/tools/peertube.js auth add -u 'http://localhost:9000' -U 'root' --password 'test' | |
705 | ``` | |
706 | ||
707 | Then, you can install or reinstall your local plugin/theme by running: | |
708 | ||
709 | ``` | |
710 | $ node ./dist/server/tools/peertube.js plugins install --path /your/absolute/plugin-or-theme/path | |
711 | ``` | |
712 | ||
713 | ### Publish | |
714 | ||
715 | Go in your plugin/theme directory, and run: | |
716 | ||
717 | ``` | |
718 | $ npm publish | |
719 | ``` | |
720 | ||
721 | Every time you want to publish another version of your plugin/theme, just update the `version` key from the `package.json` | |
722 | and republish it on NPM. Remember that the PeerTube index will take into account your new plugin/theme version after ~24 hours. | |
723 | ||
724 | ||
725 | ## Plugin & Theme hooks/helpers API | |
726 | ||
727 | See the dedicated documentation: https://docs.joinpeertube.org/api-plugins | |
728 | ||
729 | ||
730 | ## Tips | |
731 | ||
732 | ### Compatibility with PeerTube | |
733 | ||
734 | 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`). | |
735 | So please: | |
736 | * Don't make assumptions and check every parameter you want to use. For example: | |
737 | ||
738 | ```js | |
739 | registerHook({ | |
740 | target: 'filter:api.video.get.result', | |
741 | handler: video => { | |
742 | // We check the parameter exists and the name field exists too, to avoid exceptions | |
743 | if (video && video.name) video.name += ' <3' | |
744 | ||
745 | return video | |
746 | } | |
747 | }) | |
748 | ``` | |
749 | * 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/choose) | |
750 | * Don't use PeerTube dependencies. Use your own :) | |
751 | ||
752 | If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` field of your `package.json` field. | |
753 | This way, older PeerTube versions will still use your old plugin, and new PeerTube versions will use your updated plugin. | |
754 | ||
755 | ### Spam/moderation plugin | |
756 | ||
757 | If you want to create an antispam/moderation plugin, you could use the following hooks: | |
758 | * `filter:api.video.upload.accept.result`: to accept or not local uploads | |
759 | * `filter:api.video-thread.create.accept.result`: to accept or not local thread | |
760 | * `filter:api.video-comment-reply.create.accept.result`: to accept or not local replies | |
761 | * `filter:api.video-threads.list.result`: to change/hide the text of threads | |
762 | * `filter:api.video-thread-comments.list.result`: to change/hide the text of replies | |
763 | * `filter:video.auto-blacklist.result`: to automatically blacklist local or remote videos | |
764 | ||
765 | ### Other plugin examples | |
766 | ||
767 | You can take a look to "official" PeerTube plugins if you want to take inspiration from them: https://framagit.org/framasoft/peertube/official-plugins |