X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fplugins%2Fguide.md;h=e567e6c1b352b689ee9ab6d1189067ebe6bc0c84;hb=9452d4fd3321148fb80b64a67bd9983fee6c208e;hp=d6d2114da546715be491ff2815ab45f47d9b37e9;hpb=365783532ea7942b96f5e83f4a4dc8f433a07603;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md index d6d2114da..e567e6c1b 100644 --- a/support/doc/plugins/guide.md +++ b/support/doc/plugins/guide.md @@ -3,24 +3,33 @@ - - [Concepts](#concepts) - [Hooks](#hooks) - [Static files](#static-files) - [CSS](#css) - - [Server helpers (only for plugins)](#server-helpers-only-for-plugins) + - [Server API (only for plugins)](#server-api-only-for-plugins) - [Settings](#settings) - [Storage](#storage) - [Update video constants](#update-video-constants) - [Add custom routes](#add-custom-routes) - [Add external auth methods](#add-external-auth-methods) - - [Client helpers (themes & plugins)](#client-helpers-themes--plugins) - - [Plugin static route](#plugin-static-route) + - [Add new transcoding profiles](#add-new-transcoding-profiles) + - [Server helpers](#server-helpers) + - [Client API (themes & plugins)](#client-api-themes--plugins) + - [Get plugin static and router routes](#get-plugin-static-and-router-routes) - [Notifier](#notifier) - [Markdown Renderer](#markdown-renderer) + - [Auth header](#auth-header) - [Custom Modal](#custom-modal) - [Translate](#translate) - [Get public settings](#get-public-settings) + - [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) @@ -29,8 +38,10 @@ - [Update package.json](#update-packagejson) - [Write code](#write-code) - [Add translations](#add-translations) + - [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) @@ -97,6 +108,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: @@ -150,31 +175,53 @@ body#custom-css { } ``` -### Server helpers (only for plugins) +### Server API (only for plugins) #### Settings Plugins can register settings, that PeerTube will inject in the administration interface. +The following fields will be automatically translated using the plugin translation files: `label`, `html`, `descriptionHTML`, `options.label`. +**These fields are injected in the plugin settings page as HTML, so pay attention to your translation files.** Example: ```js -registerSetting({ - name: 'admin-name', - label: 'Admin name', - type: 'input', - // type: input | input-checkbox | input-textarea | markdown-text | markdown-enhanced - default: 'my super name' -}) +function register (...) { + registerSetting({ + name: 'admin-name', + label: 'Admin name', -const adminName = await settingsManager.getSetting('admin-name') + type: 'input', + // type: 'input' | 'input-checkbox' | 'input-password' | 'input-textarea' | 'markdown-text' | 'markdown-enhanced' | 'select' | 'html' -const result = await settingsManager.getSettings([ 'admin-name', 'admin-password' ]) -result['admin-name] + // If type: 'select', give the select available options + options: [ + { label: 'Label 1', value: 'value1' }, + { label: 'Label 2', value: 'value2' } + ], -settingsManager.onSettingsChange(settings => { - settings['admin-name]) -}) + // If type: 'html', set the HTML that will be injected in the page + html: 'Hello

' + + // Optional + descriptionHTML: 'The purpose of this field is...', + + default: 'my super name', + + // If the setting is not private, anyone can view its value (client code included) + // If the setting is private, only server-side hooks can access it + private: false + }) + + const adminName = await settingsManager.getSetting('admin-name') + + const result = await settingsManager.getSettings([ 'admin-name', 'admin-password' ]) + result['admin-name] + + settingsManager.onSettingsChange(settings => { + settings['admin-name'] + }) +} ``` #### Storage @@ -184,26 +231,56 @@ Plugins can store/load JSON data, that PeerTube will store in its database (so d Example: ```js -const value = await storageManager.getData('mykey') -await storageManager.storeData('mykey', { subkey: 'value' }) +function register ({ + storageManager +}) { + const value = await storageManager.getData('mykey') + await storageManager.storeData('mykey', { subkey: 'value' }) +} +``` + +You can also store files in the plugin data directory (`/{plugins-directory}/data/{npm-plugin-name}`) **in PeerTube >= 3.2**. +This directory and its content won't be deleted when your plugin is uninstalled/upgraded. + +```js +function register ({ + storageManager, + peertubeHelpers +}) { + const basePath = peertubeHelpers.plugin.getDataDirectoryPath() + + fs.writeFile(path.join(basePath, 'filename.txt'), 'content of my file', function (err) { + ... + }) +} ``` #### 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 -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 +} ``` #### Add custom routes @@ -211,8 +288,28 @@ playlistPrivacyManager.deletePlaylistPrivacy(3) // Remove Private video playlist You can create custom routes using an [express Router](https://expressjs.com/en/4x/api.html#router) for your plugin: ```js -const router = getRouter() -router.get('/ping', (req, res) => res.json({ message: 'pong' })) +function register ({ + router +}) { + const router = getRouter() + router.get('/ping', (req, res) => res.json({ message: 'pong' })) + + // Users are automatically authenticated + router.get('/auth', async (res, res) => { + const user = await peertubeHelpers.user.getAuthUser(res) + + const isAdmin = user.role === 0 + const isModerator = user.role === 1 + const isUser = user.role === 2 + + res.json({ + username: user.username, + isAdmin, + isModerator, + isUser + }) + }) +} ``` The `ping` route can be accessed using: @@ -225,101 +322,254 @@ The `ping` route can be accessed using: 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): ```js -registerIdAndPassAuth({ - authName: 'my-auth-method', +function register (...) { - // PeerTube will try all id and pass plugins in the weight DESC order - // Exposing this value in the plugin settings could be interesting - getWeight: () => 60, + registerIdAndPassAuth({ + authName: 'my-auth-method', - // Optional function called by PeerTube when the user clicked on the logout button - onLogout: user => { - console.log('User %s logged out.', user.username') - }, + // PeerTube will try all id and pass plugins in the weight DESC order + // Exposing this value in the plugin settings could be interesting + getWeight: () => 60, - // Optional function called by PeerTube when the access token or refresh token are generated/refreshed - hookTokenValidity: ({ token, type }) => { - if (type === 'access') return { valid: true } - if (type === 'refresh') return { valid: false } - }, + // Optional function called by PeerTube when the user clicked on the logout button + onLogout: user => { + console.log('User %s logged out.', user.username') + }, + + // Optional function called by PeerTube when the access token or refresh token are generated/refreshed + hookTokenValidity: ({ token, type }) => { + if (type === 'access') return { valid: true } + if (type === 'refresh') return { valid: false } + }, + + // Used by PeerTube when the user tries to authenticate + login: ({ id, password }) => { + if (id === 'user' && password === 'super password') { + return { + username: 'user' + email: 'user@example.com' + role: 2 + displayName: 'User display name' + } + } + + // Auth failed + return null + } + }) + + // Unregister this auth method + unregisterIdAndPassAuth('my-auth-method') +} +``` + +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): + +```js +function register (...) { + + // result contains the userAuthenticated auth method you can call to authenticate a user + const result = registerExternalAuth({ + authName: 'my-auth-method', + + // Will be displayed in a button next to the login form + authDisplayName: () => 'Auth method' + + // If the user click on the auth button, PeerTube will forward the request in this function + onAuthRequest: (req, res) => { + res.redirect('https://external-auth.example.com/auth') + }, + + // Same than registerIdAndPassAuth option + // onLogout: ... + + // Same than registerIdAndPassAuth option + // hookTokenValidity: ... + }) + + router.use('/external-auth-callback', (req, res) => { + // Forward the request to PeerTube + result.userAuthenticated({ + req, + res, + username: 'user' + email: 'user@example.com' + role: 2 + displayName: 'User display name' + }) + }) + + // Unregister this external auth method + unregisterExternalAuth('my-auth-method) +} +``` + +#### Add new transcoding profiles + +Adding transcoding profiles allow admins to change ffmpeg encoding parameters and/or encoders. +A transcoding profile has to be chosen by the admin of the instance using the admin configuration. + +```js +async function register ({ + transcodingManager +}) { + + // Adapt bitrate when using libx264 encoder + { + const builder = (options) => { + const { input, resolution, fps, streamNum } = options - // Used by PeerTube when the user tries to authenticate - login: ({ id, password }) => { - if (id === 'user' && password === 'super password') { + const streamString = streamNum ? ':' + streamNum : '' + + // You can also return a promise + // All these options are optional return { - username: 'user' - email: 'user@example.com' - role: 2 - displayName: 'User display name' + scaleFilter: { + // Used to define an alternative scale filter, needed by some encoders + // Default to 'scale' + name: 'scale_vaapi' + }, + // Default to [] + inputOptions: [], + // Default to [] + outputOptions: [ + // Use a custom bitrate + '-b' + streamString + ' 10K' + ] } } - // Auth failed - return null + const encoder = 'libx264' + const profileName = 'low-quality' + + // Support this profile for VOD transcoding + transcodingManager.addVODProfile(encoder, profileName, builder) + + // And/Or support this profile for live transcoding + transcodingManager.addLiveProfile(encoder, profileName, builder) } -}) -// Unregister this auth method -unregisterIdAndPassAuth('my-auth-method') + { + const builder = (options) => { + const { streamNum } = options + + const streamString = streamNum ? ':' + streamNum : '' + + // Always copy stream when PeerTube use libfdk_aac or aac encoders + return { + copy: true + } + } + + const profileName = 'copy-audio' + + for (const encoder of [ 'libfdk_aac', 'aac' ]) { + transcodingManager.addVODProfile(encoder, profileName, builder) + } + } ``` -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): +PeerTube will try different encoders depending on their priority. +If the encoder is not available in the current transcoding profile or in ffmpeg, it tries the next one. +Plugins can change the order of these encoders and add their custom encoders: ```js -// result contains the userAuthenticated auth method you can call to authenticate a user -const result = registerExternalAuth({ - authName: 'my-auth-method', +async function register ({ + transcodingManager +}) { - // Will be displayed in a button next to the login form - authDisplayName: () => 'Auth method' + // Adapt bitrate when using libx264 encoder + { + const builder = () => { + return { + inputOptions: [], + outputOptions: [] + } + } - // If the user click on the auth button, PeerTube will forward the request in this function - onAuthRequest: (req, res) => { - res.redirect('https://external-auth.example.com/auth') - }, + // Support libopus and libvpx-vp9 encoders (these codecs could be incompatible with the player) + transcodingManager.addVODProfile('libopus', 'test-vod-profile', builder) - // Same than registerIdAndPassAuth option - // onLogout: ... + // Default priorities are ~100 + // Lowest priority = 1 + transcodingManager.addVODEncoderPriority('audio', 'libopus', 1000) - // Same than registerIdAndPassAuth option - // hookTokenValidity: ... -}) + transcodingManager.addVODProfile('libvpx-vp9', 'test-vod-profile', builder) + transcodingManager.addVODEncoderPriority('video', 'libvpx-vp9', 1000) -router.use('/external-auth-callback', (req, res) => { - // Forward the request to PeerTube - result.userAuthenticated({ - req, - res, - username: 'user' - email: 'user@example.com' - role: 2 - displayName: 'User display name' - }) -}) + transcodingManager.addLiveProfile('libopus', 'test-live-profile', builder) + transcodingManager.addLiveEncoderPriority('audio', 'libopus', 1000) + } +``` + +During live transcode input options are applied once for each target resolution. +Plugins are responsible for detecting such situation and applying input options only once if necessary. + +#### Server helpers + +PeerTube provides your plugin some helpers. For example: + +```js +async function register ({ + peertubeHelpers +}) { + // Block a server + { + const serverActor = await peertubeHelpers.server.getServerActor() + + await peertubeHelpers.moderation.blockServer({ byAccountId: serverActor.Account.id, hostToBlock: '...' }) + } -// Unregister this external auth method -unregisterExternalAuth('my-auth-method) + // Load a video + { + const video = await peertubeHelpers.videos.loadByUrl('...') + } +} ``` -### Client helpers (themes & plugins) +See the [plugin API reference](https://docs.joinpeertube.org/api-plugins) to see the complete helpers list. -#### Plugin static route +### Client API (themes & plugins) + +#### Get plugin static and router routes To get your plugin static route: ```js -const baseStaticUrl = peertubeHelpers.getBaseStaticRoute() -const imageUrl = baseStaticUrl + '/images/chocobo.png' +function register (...) { + const baseStaticUrl = peertubeHelpers.getBaseStaticRoute() + const imageUrl = baseStaticUrl + '/images/chocobo.png' +} ``` +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: ```js -const { notifier } = peertubeHelpers -notifier.success('Success message content.') -notifier.error('Error message content.') +function register (...) { + const { notifier } = peertubeHelpers + notifier.success('Success message content.') + notifier.error('Error message content.') +} ``` #### Markdown Renderer @@ -327,13 +577,39 @@ notifier.error('Error message content.') To render a formatted markdown text to HTML: ```js -const { markdownRenderer } = peertubeHelpers +function register (...) { + const { markdownRenderer } = peertubeHelpers + + await markdownRenderer.textMarkdownToHTML('**My Bold Text**') + // return My Bold Text + + await markdownRenderer.enhancedMarkdownToHTML('![alt-img](http://.../my-image.jpg)') + // return alt-img +} +``` + +#### Auth header -await markdownRenderer.textMarkdownToHTML('**My Bold Text**') -// return My Bold Text +**PeerTube >= 3.2** -await markdownRenderer.enhancedMarkdownToHTML('![alt-img](http://.../my-image.jpg)') -// return alt-img +To make your own HTTP requests using the current authenticated user, use an helper to automatically set appropriate headers: + +```js +function register (...) { + registerHook({ + target: 'action:auth-user.information-loaded', + handler: ({ user }) => { + + // Useless because we have the same info in the ({ user }) parameter + // It's just an example + fetch('/api/v1/users/me', { + method: 'GET', + headers: peertubeHelpers.getAuthHeader() + }).then(res => res.json()) + .then(data => console.log('Hi %s.', data.username)) + } + }) +} ``` #### Custom Modal @@ -341,17 +617,19 @@ await markdownRenderer.enhancedMarkdownToHTML('![alt-img](http://.../my-image.jp To show a custom modal: ```js - peertubeHelpers.showModal({ - title: 'My custom modal title', - content: '

My custom modal content

', - // Optionals parameters : - // show close icon - close: true, - // show cancel button and call action() after hiding modal - cancel: { value: 'cancel', action: () => {} }, - // show confirm button and call action() after hiding modal - confirm: { value: 'confirm', action: () => {} }, - }) +function register (...) { + peertubeHelpers.showModal({ + title: 'My custom modal title', + content: '

My custom modal content

', + // Optionals parameters : + // show close icon + close: true, + // show cancel button and call action() after hiding modal + cancel: { value: 'cancel', action: () => {} }, + // show confirm button and call action() after hiding modal + confirm: { value: 'confirm', action: () => {} }, + }) +} ``` #### Translate @@ -359,8 +637,10 @@ To show a custom modal: You can translate some strings of your plugin (PeerTube will use your `translations` object of your `package.json` file): ```js -peertubeHelpers.translate('User name') - .then(translation => console.log('Translated User name by ' + translation)) +function register (...) { + peertubeHelpers.translate('User name') + .then(translation => console.log('Translated User name by ' + translation)) +} ``` #### Get public settings @@ -368,22 +648,182 @@ peertubeHelpers.translate('User name') To get your public plugin settings: ```js -peertubeHelpers.getSettings() - .then(s => { - if (!s || !s['site-id'] || !s['url']) { - console.error('Matomo settings are not set.') - return +function register (...) { + peertubeHelpers.getSettings() + .then(s => { + if (!s || !s['site-id'] || !s['url']) { + console.error('Matomo settings are not set.') + return + } + + // ... + }) +} +``` + +#### Get server config + +```js +function register (...) { + peertubeHelpers.getServerConfig() + .then(config => { + console.log('Fetched server config.', config) + }) +} +``` + +#### Add custom fields to video form + +To add custom fields in the video form (in *Plugin settings* tab): + +```js +async function register ({ registerVideoField, peertubeHelpers }) { + const descriptionHTML = await peertubeHelpers.translate(descriptionSource) + const commonOptions = { + 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, ...videoFormOptions }) + } +} +``` + +PeerTube will send this field value in `body.pluginData['my-field-name']` and fetch it from `video.pluginData['my-field-name']`. + +So for example, if you want to store an additional metadata for videos, register the following hooks in **server**: + +```js +async function register ({ + registerHook, + storageManager +}) { + const fieldName = 'my-field-name' + + // Store data associated to this video + registerHook({ + target: 'action:api.video.updated', + handler: ({ video, body }) => { + if (!body.pluginData) return + + const value = body.pluginData[fieldName] + if (!value) return + + storageManager.storeData(fieldName + '-' + video.id, value) } + }) - // ... + // Add your custom value to the video, so the client autofill your field using the previously stored value + registerHook({ + target: 'filter:api.video.get.result', + handler: async (video) => { + if (!video) return video + if (!video.pluginData) video.pluginData = {} + + const result = await storageManager.getData(fieldName + '-' + video.id) + video.pluginData[fieldName] = result + + return video + } }) +} +``` + +#### Register settings script + +To hide some fields in your settings plugin page depending on the form state: + +```js +async function register ({ registerSettingsScript }) { + registerSettingsScript({ + isSettingHidden: options => { + if (options.setting.name === 'my-setting' && options.formValues['field45'] === '2') { + return true + } + + return false + } + }) +} +``` +#### 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 + +PeerTube provides some HTML id so plugins can easily insert their own element: + +```js +async function register (...) { + const elem = document.createElement('div') + elem.className = 'hello-world-h4' + elem.innerHTML = '

Hello everybody! This is an element next to the player

' + + document.getElementById('plugin-placeholder-player-next').appendChild(elem) +} +``` + +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 @@ -466,11 +906,62 @@ 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** + +If you want to use __Typescript__, you can add __PeerTube__ types as dev dependencies: + +``` +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`: @@ -479,7 +970,7 @@ If you want to translate strings of your plugin (like labels of your registered { ..., "translations": { - "fr-FR": "./languages/fr.json", + "fr": "./languages/fr.json", "pt-BR": "./languages/pt-BR.json" }, ... @@ -487,7 +978,6 @@ If you want to translate strings of your plugin (like labels of your registered ``` The key should be one of the locales defined in [i18n.ts](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/i18n/i18n.ts). -You **must** use the complete locales (`fr-FR` instead of `fr`). Translation files are just objects, with the english sentence as the key and the translation as the value. `fr.json` could contain for example: @@ -525,13 +1015,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: @@ -543,7 +1036,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: @@ -569,10 +1062,24 @@ $ 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 -See the dedicated documentation: https://docs.joinpeertube.org/#/api-plugins +See the dedicated documentation: https://docs.joinpeertube.org/api-plugins ## Tips @@ -594,7 +1101,7 @@ registerHook({ } }) ``` - * 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) + * 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) * Don't use PeerTube dependencies. Use your own :) If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` field of your `package.json` field.