X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fplugins%2Fguide.md;h=1c809258ab39de80194091d2922706ed592b6fb7;hb=9d4c60dccc8e7e777ad139a82e9f61feda9d21fc;hp=5b7d1cb319b55c4a98ec018668ffbe79dc016cfb;hpb=ad35265d743e621d86f3f0796dd9d8795c599dca;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md index 5b7d1cb31..1c809258a 100644 --- a/support/doc/plugins/guide.md +++ b/support/doc/plugins/guide.md @@ -3,7 +3,6 @@ - - [Concepts](#concepts) - [Hooks](#hooks) - [Static files](#static-files) @@ -13,11 +12,12 @@ - [Storage](#storage) - [Update video constants](#update-video-constants) - [Add custom routes](#add-custom-routes) + - [Add custom WebSocket handlers](#add-custom-websocket-handlers) - [Add external auth methods](#add-external-auth-methods) - [Add new transcoding profiles](#add-new-transcoding-profiles) - [Server helpers](#server-helpers) - [Client API (themes & plugins)](#client-api-themes--plugins) - - [Plugin static route](#plugin-static-route) + - [Get plugin static and router routes](#get-plugin-static-and-router-routes) - [Notifier](#notifier) - [Markdown Renderer](#markdown-renderer) - [Auth header](#auth-header) @@ -27,7 +27,10 @@ - [Get server config](#get-server-config) - [Add custom fields to video form](#add-custom-fields-to-video-form) - [Register settings script](#register-settings-script) + - [Plugin selector on HTML elements](#plugin-selector-on-html-elements) - [HTML placeholder elements](#html-placeholder-elements) + - [Add/remove left menu links](#addremove-left-menu-links) + - [Create client page](#create-client-page) - [Publishing](#publishing) - [Write a plugin/theme](#write-a-plugintheme) - [Clone the quickstart repository](#clone-the-quickstart-repository) @@ -39,6 +42,7 @@ - [Build your plugin](#build-your-plugin) - [Test your plugin/theme](#test-your-plugintheme) - [Publish](#publish) + - [Unpublish](#unpublish) - [Plugin & Theme hooks/helpers API](#plugin--theme-hookshelpers-api) - [Tips](#tips) - [Compatibility with PeerTube](#compatibility-with-peertube) @@ -105,6 +109,20 @@ async function register ({ } ``` +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): + +```js +async function register ({ + registerHook, + peertubeHelpers: { logger } +}) { + registerHook({ + target: 'action:api.video.updated', + handler: ({ req, res }) => logger.debug('original request parameters', { params: req.params }) + }) +} +``` + On client side, these hooks are registered by the `clientScripts` files defined in `package.json`. All client scripts have scopes so PeerTube client only loads scripts it needs: @@ -177,6 +195,15 @@ function register (...) { type: 'input', // type: 'input' | 'input-checkbox' | 'input-password' | 'input-textarea' | 'markdown-text' | 'markdown-enhanced' | 'select' | 'html' + // If type: 'select', give the select available options + options: [ + { label: 'Label 1', value: 'value1' }, + { label: 'Label 2', value: 'value2' } + ], + + // If type: 'html', set the HTML that will be injected in the page + html: 'Hello

' + // Optional descriptionHTML: 'The purpose of this field is...', @@ -193,7 +220,7 @@ function register (...) { result['admin-name] settingsManager.onSettingsChange(settings => { - settings['admin-name]) + settings['admin-name'] }) } ``` @@ -231,21 +258,29 @@ function register ({ #### Update video constants -You can add/delete video categories, licences or languages using the appropriate managers: +You can add/delete video categories, licences or languages using the appropriate constant managers: ```js -function register (...) { - videoLanguageManager.addLanguage('al_bhed', 'Al Bhed') - videoLanguageManager.deleteLanguage('fr') +function register ({ + videoLanguageManager, + videoCategoryManager, + videoLicenceManager, + videoPrivacyManager, + playlistPrivacyManager +}) { + videoLanguageManager.addConstant('al_bhed', 'Al Bhed') + videoLanguageManager.deleteConstant('fr') - videoCategoryManager.addCategory(42, 'Best category') - videoCategoryManager.deleteCategory(1) // Music + videoCategoryManager.addConstant(42, 'Best category') + videoCategoryManager.deleteConstant(1) // Music + videoCategoryManager.resetConstants() // Reset to initial categories + videoCategoryManager.getConstants() // Retrieve all category constants - videoLicenceManager.addLicence(42, 'Best licence') - videoLicenceManager.deleteLicence(7) // Public domain + videoLicenceManager.addConstant(42, 'Best licence') + videoLicenceManager.deleteConstant(7) // Public domain - videoPrivacyManager.deletePrivacy(2) // Remove Unlisted video privacy - playlistPrivacyManager.deletePlaylistPrivacy(3) // Remove Private video playlist privacy + videoPrivacyManager.deleteConstant(2) // Remove Unlisted video privacy + playlistPrivacyManager.deleteConstant(3) // Remove Private video playlist privacy } ``` @@ -283,6 +318,41 @@ The `ping` route can be accessed using: * Or `/plugins/:pluginName/router/ping` +#### Add custom WebSocket handlers + +You can create custom WebSocket servers (like [ws](https://github.com/websockets/ws) for example) using `registerWebSocketRoute`: + +```js +function register ({ + registerWebSocketRoute, + peertubeHelpers +}) { + const wss = new WebSocketServer({ noServer: true }) + + wss.on('connection', function connection(ws) { + peertubeHelpers.logger.info('WebSocket connected!') + + setInterval(() => { + ws.send('WebSocket message sent by server'); + }, 1000) + }) + + registerWebSocketRoute({ + route: '/my-websocket-route', + + handler: (request, socket, head) => { + wss.handleUpgrade(request, socket, head, ws => { + wss.emit('connection', ws, request) + }) + } + }) +} +``` + +The `my-websocket-route` route can be accessed using: + * `/plugins/:pluginName/:pluginVersion/ws/my-websocket-route` + * Or `/plugins/:pluginName/ws/my-websocket-route` + #### Add external auth methods 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): @@ -497,7 +567,7 @@ See the [plugin API reference](https://docs.joinpeertube.org/api-plugins) to see ### Client API (themes & plugins) -#### Plugin static route +#### Get plugin static and router routes To get your plugin static route: @@ -508,6 +578,24 @@ function register (...) { } ``` +And to get your plugin router route, use `peertubeHelpers.getBaseRouterRoute()`: + +```js +function register (...) { + registerHook({ + target: 'action:video-watch.video.loaded', + handler: ({ video }) => { + fetch(peertubeHelpers.getBaseRouterRoute() + '/my/plugin/api', { + method: 'GET', + headers: peertubeHelpers.getAuthHeader() + }).then(res => res.json()) + .then(data => console.log('Hi %s.', data)) + } + }) +} +``` + + #### Notifier To notify the user with the PeerTube ToastModule: @@ -631,18 +719,37 @@ async function register ({ registerVideoField, peertubeHelpers }) { name: 'my-field-name, label: 'My added field', descriptionHTML: 'Optional description', + + // type: 'input' | 'input-checkbox' | 'input-password' | 'input-textarea' | 'markdown-text' | 'markdown-enhanced' | 'select' | 'html' + // /!\ 'input-checkbox' could send "false" and "true" strings instead of boolean type: 'input-textarea', + default: '', + // Optional, to hide a field depending on the current form state // liveVideo is in the options object when the user is creating/updating a live // videoToUpdate is in the options object when the user is updating a video hidden: ({ formValues, videoToUpdate, liveVideo }) => { return formValues.pluginData['other-field'] === 'toto' + }, + + // Optional, to display an error depending on the form state + error: ({ formValues, value }) => { + if (formValues['privacy'] !== 1 && formValues['privacy'] !== 2) return { error: false } + if (value === true) return { error: false } + + return { error: true, text: 'Should be enabled' } } } + const videoFormOptions = { + // Optional, to choose to put your setting in a specific tab in video form + // type: 'main' | 'plugin-settings' + tab: 'main' + } + for (const type of [ 'upload', 'import-url', 'import-torrent', 'update', 'go-live' ]) { - registerVideoField(commonOptions, { type }) + registerVideoField(commonOptions, { type, ...videoFormOptions }) } } ``` @@ -704,6 +811,13 @@ async function register ({ registerSettingsScript }) { }) } ``` +#### Plugin selector on HTML elements + +PeerTube provides some selectors (using `id` HTML attribute) on important blocks so plugins can easily change their style. + +For example `#plugin-selector-login-form` could be used to hide the login form. + +See the complete list on https://docs.joinpeertube.org/api-plugins #### HTML placeholder elements @@ -721,10 +835,31 @@ async function register (...) { See the complete list on https://docs.joinpeertube.org/api-plugins +#### Add/remove left menu links + +Left menu links can be filtered (add/remove a section or add/remove links) using the `filter:left-menu.links.create.result` client hook. + +#### Create client page + +To create a client page, register a new client route: + +```js +function register ({ registerClientRoute }) { + registerClientRoute({ + route: 'my-super/route', + onMount: ({ rootEl }) => { + rootEl.innerHTML = 'hello' + } + }) +} +``` + + ### Publishing -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 PeerTube index is available on https://packages.joinpeertube.org/ (it's just a REST API, so don't expect a beautiful website). +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. + +> The official plugin index source code is available at https://framagit.org/framasoft/peertube/plugin-index ## Write a plugin/theme @@ -807,11 +942,65 @@ And if you don't need CSS or client script files, use an empty `array`: ### Write code Now you can register hooks or settings, write CSS and add static directories to your plugin or your theme :) +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. + +**JavaScript** -**Caution:** 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. If you want to write modern JavaScript, please use a transpiler like [Babel](https://babeljs.io/). +**Typescript** + +The easiest way to use __Typescript__ for both front-end and backend code is to clone [peertube-plugin-quickstart-typescript](https://github.com/JohnXLivingston/peertube-plugin-quickstart-typescript/) (also available on [framagit](https://framagit.org/Livingston/peertube-plugin-quickstart-typescript/)) instead of `peertube-plugin-quickstart`. +Please read carefully the [README file](https://github.com/JohnXLivingston/peertube-plugin-quickstart-typescript/blob/main/README.md), as there are some other differences with `peertube-plugin-quickstart` (using SCSS instead of CSS, linting rules, ...). + +If you don't want to use `peertube-plugin-quickstart-typescript`, you can also manually add a dev dependency to __Peertube__ types: + +``` +npm install --save-dev @peertube/peertube-types +``` + +This package exposes *server* definition files by default: +```ts +import { RegisterServerOptions } from '@peertube/peertube-types' + +export async function register ({ registerHook }: RegisterServerOptions) { + registerHook({ + target: 'action:application.listening', + handler: () => displayHelloWorld() + }) +} +``` + +But it also exposes client types and various models used in __PeerTube__: +```ts +import { Video } from '@peertube/peertube-types'; +import { RegisterClientOptions } from '@peertube/peertube-types/client'; + +function register({ registerHook, peertubeHelpers }: RegisterClientOptions) { + registerHook({ + target: 'action:admin-plugin-settings.init', + handler: ({ npmName }: { npmName: string }) => { + if ('peertube-plugin-transcription' !== npmName) { + return; + } + }, + }); + + registerHook({ + target: 'action:video-watch.video.loaded', + handler: ({ video }: { video: Video }) => { + fetch(`${peertubeHelpers.getBaseRouterRoute()}/videos/${video.uuid}/captions`, { + method: 'PUT', + headers: peertubeHelpers.getAuthHeader(), + }).then((res) => res.json()) + .then((data) => console.log('Hi %s.', data)); + }, + }); +} + +export { register }; +``` + ### Add translations If you want to translate strings of your plugin (like labels of your registered settings), create a file and add it to `package.json`: @@ -865,13 +1054,16 @@ You built files are in the `dist/` directory. Check `package.json` to correctly ### Test your plugin/theme +PeerTube dev server (ran with `npm run dev` on `localhost:3000`) can't inject plugin CSS. +It's the reason why we don't use the dev mode but build PeerTube instead. + You'll need to have a local PeerTube instance: * Follow the [dev prerequisites](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#prerequisites) (to clone the repository, install dependencies and prepare the database) - * Build PeerTube (`--light` to only build the english language): + * Build PeerTube: ``` -$ npm run build -- --light +$ npm run build ``` * Build the CLI: @@ -883,7 +1075,7 @@ $ npm run setup:cli * Run PeerTube (you can access to your instance on http://localhost:9000): ``` -$ NODE_ENV=test npm start +$ NODE_ENV=dev npm start ``` * Register the instance via the CLI: @@ -909,6 +1101,20 @@ $ npm publish Every time you want to publish another version of your plugin/theme, just update the `version` key from the `package.json` and republish it on NPM. Remember that the PeerTube index will take into account your new plugin/theme version after ~24 hours. +> If you need to force your plugin update on a specific __PeerTube__ instance, you may update the latest available version manually: +> ```sql +> UPDATE "plugin" SET "latestVersion" = 'X.X.X' WHERE "plugin"."name" = 'plugin-shortname'; +> ``` +> You'll then be able to click the __Update plugin__ button on the plugin list. + +### Unpublish + +If for a particular reason you don't want to maintain your plugin/theme anymore +you can deprecate it. The plugin index will automatically remove it preventing users to find/install it from the PeerTube admin interface: + +```bash +$ npm deprecate peertube-plugin-xxx@"> 0.0.0" "explain here why you deprecate your plugin/theme" +``` ## Plugin & Theme hooks/helpers API