]>
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 | - [Concepts](#concepts) | |
7 | - [Hooks](#hooks) | |
8 | - [Static files](#static-files) | |
9 | - [CSS](#css) | |
10 | - [Server API (only for plugins)](#server-api-only-for-plugins) | |
11 | - [Settings](#settings) | |
12 | - [Storage](#storage) | |
13 | - [Update video constants](#update-video-constants) | |
14 | - [Add custom routes](#add-custom-routes) | |
15 | - [Add external auth methods](#add-external-auth-methods) | |
16 | - [Add new transcoding profiles](#add-new-transcoding-profiles) | |
17 | - [Server helpers](#server-helpers) | |
18 | - [Client API (themes & plugins)](#client-api-themes--plugins) | |
19 | - [Get plugin static and router routes](#get-plugin-static-and-router-routes) | |
20 | - [Notifier](#notifier) | |
21 | - [Markdown Renderer](#markdown-renderer) | |
22 | - [Auth header](#auth-header) | |
23 | - [Custom Modal](#custom-modal) | |
24 | - [Translate](#translate) | |
25 | - [Get public settings](#get-public-settings) | |
26 | - [Get server config](#get-server-config) | |
27 | - [Add custom fields to video form](#add-custom-fields-to-video-form) | |
28 | - [Register settings script](#register-settings-script) | |
29 | - [Plugin selector on HTML elements](#plugin-selector-on-html-elements) | |
30 | - [HTML placeholder elements](#html-placeholder-elements) | |
31 | - [Add/remove left menu links](#addremove-left-menu-links) | |
32 | - [Create client page](#create-client-page) | |
33 | - [Publishing](#publishing) | |
34 | - [Write a plugin/theme](#write-a-plugintheme) | |
35 | - [Clone the quickstart repository](#clone-the-quickstart-repository) | |
36 | - [Configure your repository](#configure-your-repository) | |
37 | - [Update README](#update-readme) | |
38 | - [Update package.json](#update-packagejson) | |
39 | - [Write code](#write-code) | |
40 | - [Add translations](#add-translations) | |
41 | - [Build your plugin](#build-your-plugin) | |
42 | - [Test your plugin/theme](#test-your-plugintheme) | |
43 | - [Publish](#publish) | |
44 | - [Unpublish](#unpublish) | |
45 | - [Plugin & Theme hooks/helpers API](#plugin--theme-hookshelpers-api) | |
46 | - [Tips](#tips) | |
47 | - [Compatibility with PeerTube](#compatibility-with-peertube) | |
48 | - [Spam/moderation plugin](#spammoderation-plugin) | |
49 | - [Other plugin examples](#other-plugin-examples) | |
50 | ||
51 | <!-- END doctoc generated TOC please keep comment here to allow auto update --> | |
52 | ||
53 | ## Concepts | |
54 | ||
55 | Themes are exactly the same as plugins, except that: | |
56 | * Their name starts with `peertube-theme-` instead of `peertube-plugin-` | |
57 | * They cannot declare server code (so they cannot register server hooks or settings) | |
58 | * CSS files are loaded by client only if the theme is chosen by the administrator or the user | |
59 | ||
60 | ### Hooks | |
61 | ||
62 | A plugin registers functions in JavaScript to execute when PeerTube (server and client) fires events. There are 3 types of hooks: | |
63 | * `filter`: used to filter functions parameters or return values. | |
64 | For example to replace words in video comments, or change the videos list behaviour | |
65 | * `action`: used to do something after a certain trigger. For example to send a hook every time a video is published | |
66 | * `static`: same than `action` but PeerTube waits their execution | |
67 | ||
68 | On server side, these hooks are registered by the `library` file defined in `package.json`. | |
69 | ||
70 | ```json | |
71 | { | |
72 | ..., | |
73 | "library": "./main.js", | |
74 | ..., | |
75 | } | |
76 | ``` | |
77 | ||
78 | And `main.js` defines a `register` function: | |
79 | ||
80 | Example: | |
81 | ||
82 | ```js | |
83 | async function register ({ | |
84 | registerHook, | |
85 | ||
86 | registerSetting, | |
87 | settingsManager, | |
88 | ||
89 | storageManager, | |
90 | ||
91 | videoCategoryManager, | |
92 | videoLicenceManager, | |
93 | videoLanguageManager, | |
94 | ||
95 | peertubeHelpers, | |
96 | ||
97 | getRouter, | |
98 | ||
99 | registerExternalAuth, | |
100 | unregisterExternalAuth, | |
101 | registerIdAndPassAuth, | |
102 | unregisterIdAndPassAuth | |
103 | }) { | |
104 | registerHook({ | |
105 | target: 'action:application.listening', | |
106 | handler: () => displayHelloWorld() | |
107 | }) | |
108 | } | |
109 | ``` | |
110 | ||
111 | Hooks prefixed by `action:api` also give access the original **express** [Request](http://expressjs.com/en/api.html#req) and [Response](http://expressjs.com/en/api.html#res): | |
112 | ||
113 | ```js | |
114 | async function register ({ | |
115 | registerHook, | |
116 | peertubeHelpers: { logger } | |
117 | }) { | |
118 | registerHook({ | |
119 | target: 'action:api.video.updated', | |
120 | handler: ({ req, res }) => logger.debug('original request parameters', { params: req.params }) | |
121 | }) | |
122 | } | |
123 | ``` | |
124 | ||
125 | ||
126 | On client side, these hooks are registered by the `clientScripts` files defined in `package.json`. | |
127 | All client scripts have scopes so PeerTube client only loads scripts it needs: | |
128 | ||
129 | ```json | |
130 | { | |
131 | ..., | |
132 | "clientScripts": [ | |
133 | { | |
134 | "script": "client/common-client-plugin.js", | |
135 | "scopes": [ "common" ] | |
136 | }, | |
137 | { | |
138 | "script": "client/video-watch-client-plugin.js", | |
139 | "scopes": [ "video-watch" ] | |
140 | } | |
141 | ], | |
142 | ... | |
143 | } | |
144 | ``` | |
145 | ||
146 | And these scripts also define a `register` function: | |
147 | ||
148 | ```js | |
149 | function register ({ registerHook, peertubeHelpers }) { | |
150 | registerHook({ | |
151 | target: 'action:application.init', | |
152 | handler: () => onApplicationInit(peertubeHelpers) | |
153 | }) | |
154 | } | |
155 | ``` | |
156 | ||
157 | ### Static files | |
158 | ||
159 | Plugins can declare static directories that PeerTube will serve (images for example) | |
160 | from `/plugins/{plugin-name}/{plugin-version}/static/` | |
161 | or `/themes/{theme-name}/{theme-version}/static/` routes. | |
162 | ||
163 | ### CSS | |
164 | ||
165 | Plugins can declare CSS files that PeerTube will automatically inject in the client. | |
166 | If you need to override existing style, you can use the `#custom-css` selector: | |
167 | ||
168 | ``` | |
169 | body#custom-css { | |
170 | color: red; | |
171 | } | |
172 | ||
173 | #custom-css .header { | |
174 | background-color: red; | |
175 | } | |
176 | ``` | |
177 | ||
178 | ### Server API (only for plugins) | |
179 | ||
180 | #### Settings | |
181 | ||
182 | Plugins can register settings, that PeerTube will inject in the administration interface. | |
183 | The following fields will be automatically translated using the plugin translation files: `label`, `html`, `descriptionHTML`, `options.label`. | |
184 | **These fields are injected in the plugin settings page as HTML, so pay attention to your translation files.** | |
185 | ||
186 | Example: | |
187 | ||
188 | ```js | |
189 | function register (...) { | |
190 | registerSetting({ | |
191 | name: 'admin-name', | |
192 | label: 'Admin name', | |
193 | ||
194 | type: 'input', | |
195 | // type: 'input' | 'input-checkbox' | 'input-password' | 'input-textarea' | 'markdown-text' | 'markdown-enhanced' | 'select' | 'html' | |
196 | ||
197 | // If type: 'select', give the select available options | |
198 | options: [ | |
199 | { label: 'Label 1', value: 'value1' }, | |
200 | { label: 'Label 2', value: 'value2' } | |
201 | ], | |
202 | ||
203 | // If type: 'html', set the HTML that will be injected in the page | |
204 | html: '<strong class="...">Hello</strong><br /><br />' | |
205 | ||
206 | // Optional | |
207 | descriptionHTML: 'The purpose of this field is...', | |
208 | ||
209 | default: 'my super name', | |
210 | ||
211 | // If the setting is not private, anyone can view its value (client code included) | |
212 | // If the setting is private, only server-side hooks can access it | |
213 | private: false | |
214 | }) | |
215 | ||
216 | const adminName = await settingsManager.getSetting('admin-name') | |
217 | ||
218 | const result = await settingsManager.getSettings([ 'admin-name', 'admin-password' ]) | |
219 | result['admin-name] | |
220 | ||
221 | settingsManager.onSettingsChange(settings => { | |
222 | settings['admin-name'] | |
223 | }) | |
224 | } | |
225 | ``` | |
226 | ||
227 | #### Storage | |
228 | ||
229 | Plugins can store/load JSON data, that PeerTube will store in its database (so don't put files in there). | |
230 | ||
231 | Example: | |
232 | ||
233 | ```js | |
234 | function register ({ | |
235 | storageManager | |
236 | }) { | |
237 | const value = await storageManager.getData('mykey') | |
238 | await storageManager.storeData('mykey', { subkey: 'value' }) | |
239 | } | |
240 | ``` | |
241 | ||
242 | You can also store files in the plugin data directory (`/{plugins-directory}/data/{npm-plugin-name}`) **in PeerTube >= 3.2**. | |
243 | This directory and its content won't be deleted when your plugin is uninstalled/upgraded. | |
244 | ||
245 | ```js | |
246 | function register ({ | |
247 | storageManager, | |
248 | peertubeHelpers | |
249 | }) { | |
250 | const basePath = peertubeHelpers.plugin.getDataDirectoryPath() | |
251 | ||
252 | fs.writeFile(path.join(basePath, 'filename.txt'), 'content of my file', function (err) { | |
253 | ... | |
254 | }) | |
255 | } | |
256 | ``` | |
257 | ||
258 | #### Update video constants | |
259 | ||
260 | You can add/delete video categories, licences or languages using the appropriate constant managers: | |
261 | ||
262 | ```js | |
263 | function register ({ | |
264 | videoLanguageManager, | |
265 | videoCategoryManager, | |
266 | videoLicenceManager, | |
267 | videoPrivacyManager, | |
268 | playlistPrivacyManager | |
269 | }) { | |
270 | videoLanguageManager.addConstant('al_bhed', 'Al Bhed') | |
271 | videoLanguageManager.deleteConstant('fr') | |
272 | ||
273 | videoCategoryManager.addConstant(42, 'Best category') | |
274 | videoCategoryManager.deleteConstant(1) // Music | |
275 | videoCategoryManager.resetConstants() // Reset to initial categories | |
276 | videoCategoryManager.getConstants() // Retrieve all category constants | |
277 | ||
278 | videoLicenceManager.addConstant(42, 'Best licence') | |
279 | videoLicenceManager.deleteConstant(7) // Public domain | |
280 | ||
281 | videoPrivacyManager.deleteConstant(2) // Remove Unlisted video privacy | |
282 | playlistPrivacyManager.deleteConstant(3) // Remove Private video playlist privacy | |
283 | } | |
284 | ``` | |
285 | ||
286 | #### Add custom routes | |
287 | ||
288 | You can create custom routes using an [express Router](https://expressjs.com/en/4x/api.html#router) for your plugin: | |
289 | ||
290 | ```js | |
291 | function register ({ | |
292 | router | |
293 | }) { | |
294 | const router = getRouter() | |
295 | router.get('/ping', (req, res) => res.json({ message: 'pong' })) | |
296 | ||
297 | // Users are automatically authenticated | |
298 | router.get('/auth', async (res, res) => { | |
299 | const user = await peertubeHelpers.user.getAuthUser(res) | |
300 | ||
301 | const isAdmin = user.role === 0 | |
302 | const isModerator = user.role === 1 | |
303 | const isUser = user.role === 2 | |
304 | ||
305 | res.json({ | |
306 | username: user.username, | |
307 | isAdmin, | |
308 | isModerator, | |
309 | isUser | |
310 | }) | |
311 | }) | |
312 | } | |
313 | ``` | |
314 | ||
315 | The `ping` route can be accessed using: | |
316 | * `/plugins/:pluginName/:pluginVersion/router/ping` | |
317 | * Or `/plugins/:pluginName/router/ping` | |
318 | ||
319 | ||
320 | #### Add external auth methods | |
321 | ||
322 | 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): | |
323 | ||
324 | ```js | |
325 | function register (...) { | |
326 | ||
327 | registerIdAndPassAuth({ | |
328 | authName: 'my-auth-method', | |
329 | ||
330 | // PeerTube will try all id and pass plugins in the weight DESC order | |
331 | // Exposing this value in the plugin settings could be interesting | |
332 | getWeight: () => 60, | |
333 | ||
334 | // Optional function called by PeerTube when the user clicked on the logout button | |
335 | onLogout: user => { | |
336 | console.log('User %s logged out.', user.username') | |
337 | }, | |
338 | ||
339 | // Optional function called by PeerTube when the access token or refresh token are generated/refreshed | |
340 | hookTokenValidity: ({ token, type }) => { | |
341 | if (type === 'access') return { valid: true } | |
342 | if (type === 'refresh') return { valid: false } | |
343 | }, | |
344 | ||
345 | // Used by PeerTube when the user tries to authenticate | |
346 | login: ({ id, password }) => { | |
347 | if (id === 'user' && password === 'super password') { | |
348 | return { | |
349 | username: 'user' | |
350 | email: 'user@example.com' | |
351 | role: 2 | |
352 | displayName: 'User display name' | |
353 | } | |
354 | } | |
355 | ||
356 | // Auth failed | |
357 | return null | |
358 | } | |
359 | }) | |
360 | ||
361 | // Unregister this auth method | |
362 | unregisterIdAndPassAuth('my-auth-method') | |
363 | } | |
364 | ``` | |
365 | ||
366 | 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): | |
367 | ||
368 | ```js | |
369 | function register (...) { | |
370 | ||
371 | // result contains the userAuthenticated auth method you can call to authenticate a user | |
372 | const result = registerExternalAuth({ | |
373 | authName: 'my-auth-method', | |
374 | ||
375 | // Will be displayed in a button next to the login form | |
376 | authDisplayName: () => 'Auth method' | |
377 | ||
378 | // If the user click on the auth button, PeerTube will forward the request in this function | |
379 | onAuthRequest: (req, res) => { | |
380 | res.redirect('https://external-auth.example.com/auth') | |
381 | }, | |
382 | ||
383 | // Same than registerIdAndPassAuth option | |
384 | // onLogout: ... | |
385 | ||
386 | // Same than registerIdAndPassAuth option | |
387 | // hookTokenValidity: ... | |
388 | }) | |
389 | ||
390 | router.use('/external-auth-callback', (req, res) => { | |
391 | // Forward the request to PeerTube | |
392 | result.userAuthenticated({ | |
393 | req, | |
394 | res, | |
395 | username: 'user' | |
396 | email: 'user@example.com' | |
397 | role: 2 | |
398 | displayName: 'User display name' | |
399 | }) | |
400 | }) | |
401 | ||
402 | // Unregister this external auth method | |
403 | unregisterExternalAuth('my-auth-method) | |
404 | } | |
405 | ``` | |
406 | ||
407 | #### Add new transcoding profiles | |
408 | ||
409 | Adding transcoding profiles allow admins to change ffmpeg encoding parameters and/or encoders. | |
410 | A transcoding profile has to be chosen by the admin of the instance using the admin configuration. | |
411 | ||
412 | ```js | |
413 | async function register ({ | |
414 | transcodingManager | |
415 | }) { | |
416 | ||
417 | // Adapt bitrate when using libx264 encoder | |
418 | { | |
419 | const builder = (options) => { | |
420 | const { input, resolution, fps, streamNum } = options | |
421 | ||
422 | const streamString = streamNum ? ':' + streamNum : '' | |
423 | ||
424 | // You can also return a promise | |
425 | // All these options are optional | |
426 | return { | |
427 | scaleFilter: { | |
428 | // Used to define an alternative scale filter, needed by some encoders | |
429 | // Default to 'scale' | |
430 | name: 'scale_vaapi' | |
431 | }, | |
432 | // Default to [] | |
433 | inputOptions: [], | |
434 | // Default to [] | |
435 | outputOptions: [ | |
436 | // Use a custom bitrate | |
437 | '-b' + streamString + ' 10K' | |
438 | ] | |
439 | } | |
440 | } | |
441 | ||
442 | const encoder = 'libx264' | |
443 | const profileName = 'low-quality' | |
444 | ||
445 | // Support this profile for VOD transcoding | |
446 | transcodingManager.addVODProfile(encoder, profileName, builder) | |
447 | ||
448 | // And/Or support this profile for live transcoding | |
449 | transcodingManager.addLiveProfile(encoder, profileName, builder) | |
450 | } | |
451 | ||
452 | { | |
453 | const builder = (options) => { | |
454 | const { streamNum } = options | |
455 | ||
456 | const streamString = streamNum ? ':' + streamNum : '' | |
457 | ||
458 | // Always copy stream when PeerTube use libfdk_aac or aac encoders | |
459 | return { | |
460 | copy: true | |
461 | } | |
462 | } | |
463 | ||
464 | const profileName = 'copy-audio' | |
465 | ||
466 | for (const encoder of [ 'libfdk_aac', 'aac' ]) { | |
467 | transcodingManager.addVODProfile(encoder, profileName, builder) | |
468 | } | |
469 | } | |
470 | ``` | |
471 | ||
472 | PeerTube will try different encoders depending on their priority. | |
473 | If the encoder is not available in the current transcoding profile or in ffmpeg, it tries the next one. | |
474 | Plugins can change the order of these encoders and add their custom encoders: | |
475 | ||
476 | ```js | |
477 | async function register ({ | |
478 | transcodingManager | |
479 | }) { | |
480 | ||
481 | // Adapt bitrate when using libx264 encoder | |
482 | { | |
483 | const builder = () => { | |
484 | return { | |
485 | inputOptions: [], | |
486 | outputOptions: [] | |
487 | } | |
488 | } | |
489 | ||
490 | // Support libopus and libvpx-vp9 encoders (these codecs could be incompatible with the player) | |
491 | transcodingManager.addVODProfile('libopus', 'test-vod-profile', builder) | |
492 | ||
493 | // Default priorities are ~100 | |
494 | // Lowest priority = 1 | |
495 | transcodingManager.addVODEncoderPriority('audio', 'libopus', 1000) | |
496 | ||
497 | transcodingManager.addVODProfile('libvpx-vp9', 'test-vod-profile', builder) | |
498 | transcodingManager.addVODEncoderPriority('video', 'libvpx-vp9', 1000) | |
499 | ||
500 | transcodingManager.addLiveProfile('libopus', 'test-live-profile', builder) | |
501 | transcodingManager.addLiveEncoderPriority('audio', 'libopus', 1000) | |
502 | } | |
503 | ``` | |
504 | ||
505 | During live transcode input options are applied once for each target resolution. | |
506 | Plugins are responsible for detecting such situation and applying input options only once if necessary. | |
507 | ||
508 | #### Server helpers | |
509 | ||
510 | PeerTube provides your plugin some helpers. For example: | |
511 | ||
512 | ```js | |
513 | async function register ({ | |
514 | peertubeHelpers | |
515 | }) { | |
516 | // Block a server | |
517 | { | |
518 | const serverActor = await peertubeHelpers.server.getServerActor() | |
519 | ||
520 | await peertubeHelpers.moderation.blockServer({ byAccountId: serverActor.Account.id, hostToBlock: '...' }) | |
521 | } | |
522 | ||
523 | // Load a video | |
524 | { | |
525 | const video = await peertubeHelpers.videos.loadByUrl('...') | |
526 | } | |
527 | } | |
528 | ``` | |
529 | ||
530 | See the [plugin API reference](https://docs.joinpeertube.org/api-plugins) to see the complete helpers list. | |
531 | ||
532 | ### Client API (themes & plugins) | |
533 | ||
534 | #### Get plugin static and router routes | |
535 | ||
536 | To get your plugin static route: | |
537 | ||
538 | ```js | |
539 | function register (...) { | |
540 | const baseStaticUrl = peertubeHelpers.getBaseStaticRoute() | |
541 | const imageUrl = baseStaticUrl + '/images/chocobo.png' | |
542 | } | |
543 | ``` | |
544 | ||
545 | And to get your plugin router route, use `peertubeHelpers.getBaseRouterRoute()`: | |
546 | ||
547 | ```js | |
548 | function register (...) { | |
549 | registerHook({ | |
550 | target: 'action:video-watch.video.loaded', | |
551 | handler: ({ video }) => { | |
552 | fetch(peertubeHelpers.getBaseRouterRoute() + '/my/plugin/api', { | |
553 | method: 'GET', | |
554 | headers: peertubeHelpers.getAuthHeader() | |
555 | }).then(res => res.json()) | |
556 | .then(data => console.log('Hi %s.', data)) | |
557 | } | |
558 | }) | |
559 | } | |
560 | ``` | |
561 | ||
562 | ||
563 | #### Notifier | |
564 | ||
565 | To notify the user with the PeerTube ToastModule: | |
566 | ||
567 | ```js | |
568 | function register (...) { | |
569 | const { notifier } = peertubeHelpers | |
570 | notifier.success('Success message content.') | |
571 | notifier.error('Error message content.') | |
572 | } | |
573 | ``` | |
574 | ||
575 | #### Markdown Renderer | |
576 | ||
577 | To render a formatted markdown text to HTML: | |
578 | ||
579 | ```js | |
580 | function register (...) { | |
581 | const { markdownRenderer } = peertubeHelpers | |
582 | ||
583 | await markdownRenderer.textMarkdownToHTML('**My Bold Text**') | |
584 | // return <strong>My Bold Text</strong> | |
585 | ||
586 | await markdownRenderer.enhancedMarkdownToHTML('![alt-img](http://.../my-image.jpg)') | |
587 | // return <img alt=alt-img src=http://.../my-image.jpg /> | |
588 | } | |
589 | ``` | |
590 | ||
591 | #### Auth header | |
592 | ||
593 | **PeerTube >= 3.2** | |
594 | ||
595 | To make your own HTTP requests using the current authenticated user, use an helper to automatically set appropriate headers: | |
596 | ||
597 | ```js | |
598 | function register (...) { | |
599 | registerHook({ | |
600 | target: 'action:auth-user.information-loaded', | |
601 | handler: ({ user }) => { | |
602 | ||
603 | // Useless because we have the same info in the ({ user }) parameter | |
604 | // It's just an example | |
605 | fetch('/api/v1/users/me', { | |
606 | method: 'GET', | |
607 | headers: peertubeHelpers.getAuthHeader() | |
608 | }).then(res => res.json()) | |
609 | .then(data => console.log('Hi %s.', data.username)) | |
610 | } | |
611 | }) | |
612 | } | |
613 | ``` | |
614 | ||
615 | #### Custom Modal | |
616 | ||
617 | To show a custom modal: | |
618 | ||
619 | ```js | |
620 | function register (...) { | |
621 | peertubeHelpers.showModal({ | |
622 | title: 'My custom modal title', | |
623 | content: '<p>My custom modal content</p>', | |
624 | // Optionals parameters : | |
625 | // show close icon | |
626 | close: true, | |
627 | // show cancel button and call action() after hiding modal | |
628 | cancel: { value: 'cancel', action: () => {} }, | |
629 | // show confirm button and call action() after hiding modal | |
630 | confirm: { value: 'confirm', action: () => {} }, | |
631 | }) | |
632 | } | |
633 | ``` | |
634 | ||
635 | #### Translate | |
636 | ||
637 | You can translate some strings of your plugin (PeerTube will use your `translations` object of your `package.json` file): | |
638 | ||
639 | ```js | |
640 | function register (...) { | |
641 | peertubeHelpers.translate('User name') | |
642 | .then(translation => console.log('Translated User name by ' + translation)) | |
643 | } | |
644 | ``` | |
645 | ||
646 | #### Get public settings | |
647 | ||
648 | To get your public plugin settings: | |
649 | ||
650 | ```js | |
651 | function register (...) { | |
652 | peertubeHelpers.getSettings() | |
653 | .then(s => { | |
654 | if (!s || !s['site-id'] || !s['url']) { | |
655 | console.error('Matomo settings are not set.') | |
656 | return | |
657 | } | |
658 | ||
659 | // ... | |
660 | }) | |
661 | } | |
662 | ``` | |
663 | ||
664 | #### Get server config | |
665 | ||
666 | ```js | |
667 | function register (...) { | |
668 | peertubeHelpers.getServerConfig() | |
669 | .then(config => { | |
670 | console.log('Fetched server config.', config) | |
671 | }) | |
672 | } | |
673 | ``` | |
674 | ||
675 | #### Add custom fields to video form | |
676 | ||
677 | To add custom fields in the video form (in *Plugin settings* tab): | |
678 | ||
679 | ```js | |
680 | async function register ({ registerVideoField, peertubeHelpers }) { | |
681 | const descriptionHTML = await peertubeHelpers.translate(descriptionSource) | |
682 | const commonOptions = { | |
683 | name: 'my-field-name, | |
684 | label: 'My added field', | |
685 | descriptionHTML: 'Optional description', | |
686 | ||
687 | // type: 'input' | 'input-checkbox' | 'input-password' | 'input-textarea' | 'markdown-text' | 'markdown-enhanced' | 'select' | 'html' | |
688 | // /!\ 'input-checkbox' could send "false" and "true" strings instead of boolean | |
689 | type: 'input-textarea', | |
690 | ||
691 | default: '', | |
692 | ||
693 | // Optional, to hide a field depending on the current form state | |
694 | // liveVideo is in the options object when the user is creating/updating a live | |
695 | // videoToUpdate is in the options object when the user is updating a video | |
696 | hidden: ({ formValues, videoToUpdate, liveVideo }) => { | |
697 | return formValues.pluginData['other-field'] === 'toto' | |
698 | }, | |
699 | ||
700 | // Optional, to display an error depending on the form state | |
701 | error: ({ formValues, value }) => { | |
702 | if (formValues['privacy'] !== 1 && formValues['privacy'] !== 2) return { error: false } | |
703 | if (value === true) return { error: false } | |
704 | ||
705 | return { error: true, text: 'Should be enabled' } | |
706 | } | |
707 | } | |
708 | ||
709 | const videoFormOptions = { | |
710 | // Optional, to choose to put your setting in a specific tab in video form | |
711 | // type: 'main' | 'plugin-settings' | |
712 | tab: 'main' | |
713 | } | |
714 | ||
715 | for (const type of [ 'upload', 'import-url', 'import-torrent', 'update', 'go-live' ]) { | |
716 | registerVideoField(commonOptions, { type, ...videoFormOptions }) | |
717 | } | |
718 | } | |
719 | ``` | |
720 | ||
721 | PeerTube will send this field value in `body.pluginData['my-field-name']` and fetch it from `video.pluginData['my-field-name']`. | |
722 | ||
723 | So for example, if you want to store an additional metadata for videos, register the following hooks in **server**: | |
724 | ||
725 | ```js | |
726 | async function register ({ | |
727 | registerHook, | |
728 | storageManager | |
729 | }) { | |
730 | const fieldName = 'my-field-name' | |
731 | ||
732 | // Store data associated to this video | |
733 | registerHook({ | |
734 | target: 'action:api.video.updated', | |
735 | handler: ({ video, body }) => { | |
736 | if (!body.pluginData) return | |
737 | ||
738 | const value = body.pluginData[fieldName] | |
739 | if (!value) return | |
740 | ||
741 | storageManager.storeData(fieldName + '-' + video.id, value) | |
742 | } | |
743 | }) | |
744 | ||
745 | // Add your custom value to the video, so the client autofill your field using the previously stored value | |
746 | registerHook({ | |
747 | target: 'filter:api.video.get.result', | |
748 | handler: async (video) => { | |
749 | if (!video) return video | |
750 | if (!video.pluginData) video.pluginData = {} | |
751 | ||
752 | const result = await storageManager.getData(fieldName + '-' + video.id) | |
753 | video.pluginData[fieldName] = result | |
754 | ||
755 | return video | |
756 | } | |
757 | }) | |
758 | } | |
759 | ``` | |
760 | ||
761 | #### Register settings script | |
762 | ||
763 | To hide some fields in your settings plugin page depending on the form state: | |
764 | ||
765 | ```js | |
766 | async function register ({ registerSettingsScript }) { | |
767 | registerSettingsScript({ | |
768 | isSettingHidden: options => { | |
769 | if (options.setting.name === 'my-setting' && options.formValues['field45'] === '2') { | |
770 | return true | |
771 | } | |
772 | ||
773 | return false | |
774 | } | |
775 | }) | |
776 | } | |
777 | ``` | |
778 | #### Plugin selector on HTML elements | |
779 | ||
780 | PeerTube provides some selectors (using `id` HTML attribute) on important blocks so plugins can easily change their style. | |
781 | ||
782 | For example `#plugin-selector-login-form` could be used to hide the login form. | |
783 | ||
784 | See the complete list on https://docs.joinpeertube.org/api-plugins | |
785 | ||
786 | #### HTML placeholder elements | |
787 | ||
788 | PeerTube provides some HTML id so plugins can easily insert their own element: | |
789 | ||
790 | ```js | |
791 | async function register (...) { | |
792 | const elem = document.createElement('div') | |
793 | elem.className = 'hello-world-h4' | |
794 | elem.innerHTML = '<h4>Hello everybody! This is an element next to the player</h4>' | |
795 | ||
796 | document.getElementById('plugin-placeholder-player-next').appendChild(elem) | |
797 | } | |
798 | ``` | |
799 | ||
800 | See the complete list on https://docs.joinpeertube.org/api-plugins | |
801 | ||
802 | #### Add/remove left menu links | |
803 | ||
804 | Left menu links can be filtered (add/remove a section or add/remove links) using the `filter:left-menu.links.create.result` client hook. | |
805 | ||
806 | #### Create client page | |
807 | ||
808 | To create a client page, register a new client route: | |
809 | ||
810 | ```js | |
811 | function register ({ registerClientRoute }) { | |
812 | registerClientRoute({ | |
813 | route: 'my-super/route', | |
814 | onMount: ({ rootEl }) => { | |
815 | rootEl.innerHTML = 'hello' | |
816 | } | |
817 | }) | |
818 | } | |
819 | ``` | |
820 | ||
821 | ||
822 | ### Publishing | |
823 | ||
824 | PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes take into account your plugin (after ~ 1 day). An official plugin index is available on [packages.joinpeertube.org](https://packages.joinpeertube.org/api/v1/plugins), with no interface to present packages. | |
825 | ||
826 | > The official plugin index source code is available at https://framagit.org/framasoft/peertube/plugin-index | |
827 | ||
828 | ## Write a plugin/theme | |
829 | ||
830 | Steps: | |
831 | * Find a name for your plugin or your theme (must not have spaces, it can only contain lowercase letters and `-`) | |
832 | * Add the appropriate prefix: | |
833 | * If you develop a plugin, add `peertube-plugin-` prefix to your plugin name (for example: `peertube-plugin-mysupername`) | |
834 | * If you develop a theme, add `peertube-theme-` prefix to your theme name (for example: `peertube-theme-mysupertheme`) | |
835 | * Clone the quickstart repository | |
836 | * Configure your repository | |
837 | * Update `README.md` | |
838 | * Update `package.json` | |
839 | * Register hooks, add CSS and static files | |
840 | * Test your plugin/theme with a local PeerTube installation | |
841 | * Publish your plugin/theme on NPM | |
842 | ||
843 | ### Clone the quickstart repository | |
844 | ||
845 | If you develop a plugin, clone the `peertube-plugin-quickstart` repository: | |
846 | ||
847 | ``` | |
848 | $ git clone https://framagit.org/framasoft/peertube/peertube-plugin-quickstart.git peertube-plugin-mysupername | |
849 | ``` | |
850 | ||
851 | If you develop a theme, clone the `peertube-theme-quickstart` repository: | |
852 | ||
853 | ``` | |
854 | $ git clone https://framagit.org/framasoft/peertube/peertube-theme-quickstart.git peertube-theme-mysupername | |
855 | ``` | |
856 | ||
857 | ### Configure your repository | |
858 | ||
859 | Set your repository URL: | |
860 | ||
861 | ``` | |
862 | $ cd peertube-plugin-mysupername # or cd peertube-theme-mysupername | |
863 | $ git remote set-url origin https://your-git-repo | |
864 | ``` | |
865 | ||
866 | ### Update README | |
867 | ||
868 | Update `README.md` file: | |
869 | ||
870 | ``` | |
871 | $ $EDITOR README.md | |
872 | ``` | |
873 | ||
874 | ### Update package.json | |
875 | ||
876 | Update the `package.json` fields: | |
877 | * `name` (should start with `peertube-plugin-` or `peertube-theme-`) | |
878 | * `description` | |
879 | * `homepage` | |
880 | * `author` | |
881 | * `bugs` | |
882 | * `engine.peertube` (the PeerTube version compatibility, must be `>=x.y.z` and nothing else) | |
883 | ||
884 | **Caution:** Don't update or remove other keys, or PeerTube will not be able to index/install your plugin. | |
885 | If you don't need static directories, use an empty `object`: | |
886 | ||
887 | ```json | |
888 | { | |
889 | ..., | |
890 | "staticDirs": {}, | |
891 | ... | |
892 | } | |
893 | ``` | |
894 | ||
895 | And if you don't need CSS or client script files, use an empty `array`: | |
896 | ||
897 | ```json | |
898 | { | |
899 | ..., | |
900 | "css": [], | |
901 | "clientScripts": [], | |
902 | ... | |
903 | } | |
904 | ``` | |
905 | ||
906 | ### Write code | |
907 | ||
908 | Now you can register hooks or settings, write CSS and add static directories to your plugin or your theme :) | |
909 | It's up to you to check the code you write will be compatible with the PeerTube NodeJS version, and will be supported by web browsers. | |
910 | ||
911 | **JavaScript** | |
912 | ||
913 | If you want to write modern JavaScript, please use a transpiler like [Babel](https://babeljs.io/). | |
914 | ||
915 | **Typescript** | |
916 | ||
917 | If you want to use __Typescript__, you can add __PeerTube__ types as dev dependencies: | |
918 | ||
919 | ``` | |
920 | npm install --save-dev @peertube/peertube-types | |
921 | ``` | |
922 | ||
923 | This package exposes *server* definition files by default: | |
924 | ```ts | |
925 | import { RegisterServerOptions } from '@peertube/peertube-types' | |
926 | ||
927 | export async function register ({ registerHook }: RegisterServerOptions) { | |
928 | registerHook({ | |
929 | target: 'action:application.listening', | |
930 | handler: () => displayHelloWorld() | |
931 | }) | |
932 | } | |
933 | ``` | |
934 | ||
935 | But it also exposes client types and various models used in __PeerTube__: | |
936 | ```ts | |
937 | import { Video } from '@peertube/peertube-types'; | |
938 | import { RegisterClientOptions } from '@peertube/peertube-types/client'; | |
939 | ||
940 | function register({ registerHook, peertubeHelpers }: RegisterClientOptions) { | |
941 | registerHook({ | |
942 | target: 'action:admin-plugin-settings.init', | |
943 | handler: ({ npmName }: { npmName: string }) => { | |
944 | if ('peertube-plugin-transcription' !== npmName) { | |
945 | return; | |
946 | } | |
947 | }, | |
948 | }); | |
949 | ||
950 | registerHook({ | |
951 | target: 'action:video-watch.video.loaded', | |
952 | handler: ({ video }: { video: Video }) => { | |
953 | fetch(`${peertubeHelpers.getBaseRouterRoute()}/videos/${video.uuid}/captions`, { | |
954 | method: 'PUT', | |
955 | headers: peertubeHelpers.getAuthHeader(), | |
956 | }).then((res) => res.json()) | |
957 | .then((data) => console.log('Hi %s.', data)); | |
958 | }, | |
959 | }); | |
960 | } | |
961 | ||
962 | export { register }; | |
963 | ``` | |
964 | ||
965 | ### Add translations | |
966 | ||
967 | If you want to translate strings of your plugin (like labels of your registered settings), create a file and add it to `package.json`: | |
968 | ||
969 | ```json | |
970 | { | |
971 | ..., | |
972 | "translations": { | |
973 | "fr": "./languages/fr.json", | |
974 | "pt-BR": "./languages/pt-BR.json" | |
975 | }, | |
976 | ... | |
977 | } | |
978 | ``` | |
979 | ||
980 | The key should be one of the locales defined in [i18n.ts](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/i18n/i18n.ts). | |
981 | ||
982 | Translation files are just objects, with the english sentence as the key and the translation as the value. | |
983 | `fr.json` could contain for example: | |
984 | ||
985 | ```json | |
986 | { | |
987 | "Hello world": "Hello le monde" | |
988 | } | |
989 | ``` | |
990 | ||
991 | ### Build your plugin | |
992 | ||
993 | If you added client scripts, you'll need to build them using webpack. | |
994 | ||
995 | Install webpack: | |
996 | ||
997 | ``` | |
998 | $ npm install | |
999 | ``` | |
1000 | ||
1001 | Add/update your files in the `clientFiles` array of `webpack.config.js`: | |
1002 | ||
1003 | ``` | |
1004 | $ $EDITOR ./webpack.config.js | |
1005 | ``` | |
1006 | ||
1007 | Build your client files: | |
1008 | ||
1009 | ``` | |
1010 | $ npm run build | |
1011 | ``` | |
1012 | ||
1013 | You built files are in the `dist/` directory. Check `package.json` to correctly point to them. | |
1014 | ||
1015 | ||
1016 | ### Test your plugin/theme | |
1017 | ||
1018 | PeerTube dev server (ran with `npm run dev` on `localhost:3000`) can't inject plugin CSS. | |
1019 | It's the reason why we don't use the dev mode but build PeerTube instead. | |
1020 | ||
1021 | You'll need to have a local PeerTube instance: | |
1022 | * Follow the [dev prerequisites](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#prerequisites) | |
1023 | (to clone the repository, install dependencies and prepare the database) | |
1024 | * Build PeerTube: | |
1025 | ||
1026 | ``` | |
1027 | $ npm run build | |
1028 | ``` | |
1029 | ||
1030 | * Build the CLI: | |
1031 | ||
1032 | ``` | |
1033 | $ npm run setup:cli | |
1034 | ``` | |
1035 | ||
1036 | * Run PeerTube (you can access to your instance on http://localhost:9000): | |
1037 | ||
1038 | ``` | |
1039 | $ NODE_ENV=test npm start | |
1040 | ``` | |
1041 | ||
1042 | * Register the instance via the CLI: | |
1043 | ||
1044 | ``` | |
1045 | $ node ./dist/server/tools/peertube.js auth add -u 'http://localhost:9000' -U 'root' --password 'test' | |
1046 | ``` | |
1047 | ||
1048 | Then, you can install or reinstall your local plugin/theme by running: | |
1049 | ||
1050 | ``` | |
1051 | $ node ./dist/server/tools/peertube.js plugins install --path /your/absolute/plugin-or-theme/path | |
1052 | ``` | |
1053 | ||
1054 | ### Publish | |
1055 | ||
1056 | Go in your plugin/theme directory, and run: | |
1057 | ||
1058 | ``` | |
1059 | $ npm publish | |
1060 | ``` | |
1061 | ||
1062 | Every time you want to publish another version of your plugin/theme, just update the `version` key from the `package.json` | |
1063 | and republish it on NPM. Remember that the PeerTube index will take into account your new plugin/theme version after ~24 hours. | |
1064 | ||
1065 | > If you need to force your plugin update on a specific __PeerTube__ instance, you may update the latest available version manually: | |
1066 | > ```sql | |
1067 | > UPDATE "plugin" SET "latestVersion" = 'X.X.X' WHERE "plugin"."name" = 'plugin-shortname'; | |
1068 | > ``` | |
1069 | > You'll then be able to click the __Update plugin__ button on the plugin list. | |
1070 | ||
1071 | ### Unpublish | |
1072 | ||
1073 | If for a particular reason you don't want to maintain your plugin/theme anymore | |
1074 | you can deprecate it. The plugin index will automatically remove it preventing users to find/install it from the PeerTube admin interface: | |
1075 | ||
1076 | ```bash | |
1077 | $ npm deprecate peertube-plugin-xxx@"> 0.0.0" "explain here why you deprecate your plugin/theme" | |
1078 | ``` | |
1079 | ||
1080 | ## Plugin & Theme hooks/helpers API | |
1081 | ||
1082 | See the dedicated documentation: https://docs.joinpeertube.org/api-plugins | |
1083 | ||
1084 | ||
1085 | ## Tips | |
1086 | ||
1087 | ### Compatibility with PeerTube | |
1088 | ||
1089 | 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`). | |
1090 | So please: | |
1091 | * Don't make assumptions and check every parameter you want to use. For example: | |
1092 | ||
1093 | ```js | |
1094 | registerHook({ | |
1095 | target: 'filter:api.video.get.result', | |
1096 | handler: video => { | |
1097 | // We check the parameter exists and the name field exists too, to avoid exceptions | |
1098 | if (video && video.name) video.name += ' <3' | |
1099 | ||
1100 | return video | |
1101 | } | |
1102 | }) | |
1103 | ``` | |
1104 | * 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) | |
1105 | * Don't use PeerTube dependencies. Use your own :) | |
1106 | ||
1107 | If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` field of your `package.json` field. | |
1108 | This way, older PeerTube versions will still use your old plugin, and new PeerTube versions will use your updated plugin. | |
1109 | ||
1110 | ### Spam/moderation plugin | |
1111 | ||
1112 | If you want to create an antispam/moderation plugin, you could use the following hooks: | |
1113 | * `filter:api.video.upload.accept.result`: to accept or not local uploads | |
1114 | * `filter:api.video-thread.create.accept.result`: to accept or not local thread | |
1115 | * `filter:api.video-comment-reply.create.accept.result`: to accept or not local replies | |
1116 | * `filter:api.video-threads.list.result`: to change/hide the text of threads | |
1117 | * `filter:api.video-thread-comments.list.result`: to change/hide the text of replies | |
1118 | * `filter:video.auto-blacklist.result`: to automatically blacklist local or remote videos | |
1119 | ||
1120 | ### Other plugin examples | |
1121 | ||
1122 | You can take a look to "official" PeerTube plugins if you want to take inspiration from them: https://framagit.org/framasoft/peertube/official-plugins |