X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fplugins%2Fguide.md;h=85aaf9f02ffe3300a0d2bb42bb9b25abe0a8e3a2;hb=171efc48e67498406feb6d7873b3482b41505515;hp=ea33b8d9f6907f92b20496d9538bb5fa2b2b2946;hpb=3e03b961b8ab897500dfea626f808c009f64e551;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md index ea33b8d9f..85aaf9f02 100644 --- a/support/doc/plugins/guide.md +++ b/support/doc/plugins/guide.md @@ -15,17 +15,21 @@ - [Add custom routes](#add-custom-routes) - [Add external auth methods](#add-external-auth-methods) - [Add new transcoding profiles](#add-new-transcoding-profiles) - - [Helpers](#helpers) + - [Server helpers](#server-helpers) - [Client API (themes & plugins)](#client-api-themes--plugins) - [Plugin static route](#plugin-static-route) - [Notifier](#notifier) - [Markdown Renderer](#markdown-renderer) + - [Auth header](#auth-header) + - [Plugin router route](#plugin-router-route) - [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) + - [HTML placeholder elements](#html-placeholder-elements) + - [Add/remove left menu links](#addremove-left-menu-links) - [Publishing](#publishing) - [Write a plugin/theme](#write-a-plugintheme) - [Clone the quickstart repository](#clone-the-quickstart-repository) @@ -37,6 +41,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) @@ -171,9 +176,18 @@ function register (...) { registerSetting({ name: 'admin-name', label: 'Admin name', + type: 'input', - // type: input | input-checkbox | input-password | input-textarea | markdown-text | markdown-enhanced | 'select' | 'html' - default: 'my super name' + // type: 'input' | 'input-checkbox' | 'input-password' | 'input-textarea' | 'markdown-text' | 'markdown-enhanced' | 'select' | 'html' + + // 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') @@ -194,29 +208,55 @@ Plugins can store/load JSON data, that PeerTube will store in its database (so d Example: ```js -function register (...) { +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 -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 } ``` @@ -225,9 +265,27 @@ function register (...) { You can create custom routes using an [express Router](https://expressjs.com/en/4x/api.html#router) for your plugin: ```js -function register (...) { +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 + }) + }) } ``` @@ -341,9 +399,16 @@ async function register ({ const streamString = streamNum ? ':' + streamNum : '' // You can also return a promise - // All these options are optional and defaults to [] + // All these options are optional return { + 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' @@ -417,7 +482,7 @@ async function register ({ 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. -### Helpers +#### Server helpers PeerTube provides your plugin some helpers. For example: @@ -482,6 +547,51 @@ function register (...) { } ``` +#### Auth header + +**PeerTube >= 3.2** + +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)) + } + }) +} +``` + +#### Plugin router route + +**PeerTube >= 3.3** + +To get your plugin router route, you can 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)) + } + }) +} +``` + #### Custom Modal To show a custom modal: @@ -554,10 +664,16 @@ async function register ({ registerVideoField, peertubeHelpers }) { label: 'My added field', descriptionHTML: 'Optional description', type: 'input-textarea', - default: '' + 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' + } } - for (const type of [ 'upload', 'import-url', 'import-torrent', 'update' ]) { + for (const type of [ 'upload', 'import-url', 'import-torrent', 'update', 'go-live' ]) { registerVideoField(commonOptions, { type }) } } @@ -621,11 +737,32 @@ async function register ({ registerSettingsScript }) { } ``` +#### 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 = '