<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-
- [Concepts](#concepts)
- [Hooks](#hooks)
- [Static files](#static-files)
- [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)
- [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)
}
```
+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:
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: '<strong class="...">Hello</strong><br /><br />'
+
+ // 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')
result['admin-name]
settingsManager.onSettingsChange(settings => {
- settings['admin-name])
+ settings['admin-name']
})
}
```
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
}
```
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
+ })
+ })
}
```
}
```
+#### 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:
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 })
}
}
})
}
```
+#### 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
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
{
...,
"translations": {
- "fr-FR": "./languages/fr.json",
+ "fr": "./languages/fr.json",
"pt-BR": "./languages/pt-BR.json"
},
...
```
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:
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
projects / github / Chocobozzz / PeerTube.git / blobdiff