X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fplugins%2Fguide.md;h=4a0d318a7428eda08541adefc502559c72418582;hb=06aad80165d09a8863ab8103149a8ff518b10641;hp=36ade117bb5a9b0c444b6897735dfae57ecd0f7e;hpb=302eba0d898e38dca14739486441c27c0be6c62f;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md index 36ade117b..4a0d318a7 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) @@ -20,13 +19,17 @@ - [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) + - [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) - [Publishing](#publishing) - [Write a plugin/theme](#write-a-plugintheme) - [Clone the quickstart repository](#clone-the-quickstart-repository) @@ -38,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) @@ -104,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: @@ -172,9 +190,27 @@ 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' + + // 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...', + + 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') @@ -183,7 +219,7 @@ function register (...) { result['admin-name] settingsManager.onSettingsChange(settings => { - settings['admin-name]) + settings['admin-name'] }) } ``` @@ -203,7 +239,7 @@ function register ({ } ``` -You can also store files in the plugin data directory (`/{plugins-directory}/data/{npm-plugin-name}`). +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 @@ -221,21 +257,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 } ``` @@ -251,8 +295,8 @@ function register ({ router.get('/ping', (req, res) => res.json({ message: 'pong' })) // Users are automatically authenticated - router.get('/auth', (res, res) => { - const user = peertubeHelpers.user.getAuthUser(res) + router.get('/auth', async (res, res) => { + const user = await peertubeHelpers.user.getAuthUser(res) const isAdmin = user.role === 0 const isModerator = user.role === 1 @@ -526,6 +570,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: @@ -597,11 +686,21 @@ 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: '' + + 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 }) } } @@ -664,6 +763,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 @@ -681,10 +787,16 @@ 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. + + ### 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 @@ -869,6 +981,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