OpenCloud
/
PeerTube
mirror of https://github.com/Chocobozzz/PeerTube
1
0
Fork 0
Code Issues Releases Wiki Activity

Update plugins doc

pull/3747/head
Chocobozzz 2021-04-09 15:17:46 +02:00
parent 22820226e5
commit d2466f0ac9
No known key found for this signature in database
GPG Key ID: 583A612D890159BE
2 changed files with 196 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
shared/models/plugins/register-server-setting.model.ts
View File

@ -1,6 +1,6 @@
import { RegisterClientFormFieldOptions } from './register-client-form-field.model' import { RegisterClientFormFieldOptions } from './register-client-form-field.model'
export type RegisterServerSettingOptions = RegisterClientFormFieldOptions & { export type RegisterServerSettingOptions = RegisterClientFormFieldOptions & {
// If the setting is not private, anyone can view its value (client code included) // 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 // If the setting is private, only server-side hooks can access it
// Mainly used by the PeerTube client to get admin config // Mainly used by the PeerTube client to get admin config

314
support/doc/plugins/guide.md
View File

@ -8,14 +8,15 @@
- [Hooks](#hooks) - [Hooks](#hooks)
- [Static files](#static-files) - [Static files](#static-files)
- [CSS](#css) - [CSS](#css)
- [Server helpers (only for plugins)](#server-helpers-only-for-plugins) - [Server API (only for plugins)](#server-api-only-for-plugins)
- [Settings](#settings) - [Settings](#settings)
- [Storage](#storage) - [Storage](#storage)
- [Update video constants](#update-video-constants) - [Update video constants](#update-video-constants)
- [Add custom routes](#add-custom-routes) - [Add custom routes](#add-custom-routes)
- [Add external auth methods](#add-external-auth-methods) - [Add external auth methods](#add-external-auth-methods)
- [Add new transcoding profiles](#add-new-transcoding-profiles) - [Add new transcoding profiles](#add-new-transcoding-profiles)
- [Client helpers (themes & plugins)](#client-helpers-themes--plugins) - [Helpers](#helpers)
- [Client API (themes & plugins)](#client-api-themes--plugins)
- [Plugin static route](#plugin-static-route) - [Plugin static route](#plugin-static-route)
- [Notifier](#notifier) - [Notifier](#notifier)
- [Markdown Renderer](#markdown-renderer) - [Markdown Renderer](#markdown-renderer)
@ -24,6 +25,7 @@
- [Get public settings](#get-public-settings) - [Get public settings](#get-public-settings)
- [Get server config](#get-server-config) - [Get server config](#get-server-config)
- [Add custom fields to video form](#add-custom-fields-to-video-form) - [Add custom fields to video form](#add-custom-fields-to-video-form)
- [Register settings script](#register-settings-script)
- [Publishing](#publishing) - [Publishing](#publishing)
- [Write a plugin/theme](#write-a-plugintheme) - [Write a plugin/theme](#write-a-plugintheme)
- [Clone the quickstart repository](#clone-the-quickstart-repository) - [Clone the quickstart repository](#clone-the-quickstart-repository)
@ -154,31 +156,35 @@ body#custom-css {
} }
``` ```
### Server helpers (only for plugins) ### Server API (only for plugins)
#### Settings #### Settings
Plugins can register settings, that PeerTube will inject in the administration interface. 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: Example:
```js ```js
registerSetting({ function register (...) {
name: 'admin-name', registerSetting({
label: 'Admin name', name: 'admin-name',
type: 'input', label: 'Admin name',
// type: input | input-checkbox | input-password | input-textarea | markdown-text | markdown-enhanced type: 'input',
default: 'my super name' // type: input | input-checkbox | input-password | input-textarea | markdown-text | markdown-enhanced | 'select' | 'html'
}) default: 'my super name'
})
const adminName = await settingsManager.getSetting('admin-name') const adminName = await settingsManager.getSetting('admin-name')
const result = await settingsManager.getSettings([ 'admin-name', 'admin-password' ]) const result = await settingsManager.getSettings([ 'admin-name', 'admin-password' ])
result['admin-name] result['admin-name]
settingsManager.onSettingsChange(settings => { settingsManager.onSettingsChange(settings => {
settings['admin-name]) settings['admin-name])
}) })
}
``` ```
#### Storage #### Storage
@ -188,8 +194,10 @@ Plugins can store/load JSON data, that PeerTube will store in its database (so d
Example: Example:
```js ```js
const value = await storageManager.getData('mykey') function register (...) {
await storageManager.storeData('mykey', { subkey: 'value' }) const value = await storageManager.getData('mykey')
await storageManager.storeData('mykey', { subkey: 'value' })
}
``` ```
#### Update video constants #### Update video constants
@ -197,17 +205,19 @@ await storageManager.storeData('mykey', { subkey: 'value' })
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 managers:
```js ```js
videoLanguageManager.addLanguage('al_bhed', 'Al Bhed') function register (...) {
videoLanguageManager.deleteLanguage('fr') videoLanguageManager.addLanguage('al_bhed', 'Al Bhed')
videoLanguageManager.deleteLanguage('fr')
videoCategoryManager.addCategory(42, 'Best category') videoCategoryManager.addCategory(42, 'Best category')
videoCategoryManager.deleteCategory(1) // Music videoCategoryManager.deleteCategory(1) // Music
videoLicenceManager.addLicence(42, 'Best licence') videoLicenceManager.addLicence(42, 'Best licence')
videoLicenceManager.deleteLicence(7) // Public domain videoLicenceManager.deleteLicence(7) // Public domain
videoPrivacyManager.deletePrivacy(2) // Remove Unlisted video privacy videoPrivacyManager.deletePrivacy(2) // Remove Unlisted video privacy
playlistPrivacyManager.deletePlaylistPrivacy(3) // Remove Private video playlist privacy playlistPrivacyManager.deletePlaylistPrivacy(3) // Remove Private video playlist privacy
}
``` ```
#### Add custom routes #### Add custom routes
@ -215,8 +225,10 @@ 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: You can create custom routes using an [express Router](https://expressjs.com/en/4x/api.html#router) for your plugin:
```js ```js
const router = getRouter() function register (...) {
router.get('/ping', (req, res) => res.json({ message: 'pong' })) const router = getRouter()
router.get('/ping', (req, res) => res.json({ message: 'pong' }))
}
``` ```
The `ping` route can be accessed using: The `ping` route can be accessed using:
@ -229,80 +241,86 @@ 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): 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 ```js
registerIdAndPassAuth({ function register (...) {
authName: 'my-auth-method',
// PeerTube will try all id and pass plugins in the weight DESC order registerIdAndPassAuth({
// Exposing this value in the plugin settings could be interesting authName: 'my-auth-method',
getWeight: () => 60,
// Optional function called by PeerTube when the user clicked on the logout button // PeerTube will try all id and pass plugins in the weight DESC order
onLogout: user => { // Exposing this value in the plugin settings could be interesting
console.log('User %s logged out.', user.username') getWeight: () => 60,
},
// Optional function called by PeerTube when the access token or refresh token are generated/refreshed // Optional function called by PeerTube when the user clicked on the logout button
hookTokenValidity: ({ token, type }) => { onLogout: user => {
if (type === 'access') return { valid: true } console.log('User %s logged out.', user.username')
if (type === 'refresh') return { valid: false } },
},
// Used by PeerTube when the user tries to authenticate // Optional function called by PeerTube when the access token or refresh token are generated/refreshed
login: ({ id, password }) => { hookTokenValidity: ({ token, type }) => {
if (id === 'user' && password === 'super password') { if (type === 'access') return { valid: true }
return { if (type === 'refresh') return { valid: false }
username: 'user' },
email: 'user@example.com'
role: 2 // Used by PeerTube when the user tries to authenticate
displayName: 'User display name' 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
} }
})
// Auth failed // Unregister this auth method
return null unregisterIdAndPassAuth('my-auth-method')
} }
})
// 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): 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 ```js
// result contains the userAuthenticated auth method you can call to authenticate a user function register (...) {
const result = registerExternalAuth({
authName: 'my-auth-method',
// Will be displayed in a button next to the login form // result contains the userAuthenticated auth method you can call to authenticate a user
authDisplayName: () => 'Auth method' const result = registerExternalAuth({
authName: 'my-auth-method',
// If the user click on the auth button, PeerTube will forward the request in this function // Will be displayed in a button next to the login form
onAuthRequest: (req, res) => { authDisplayName: () => 'Auth method'
res.redirect('https://external-auth.example.com/auth')
},
// Same than registerIdAndPassAuth option // If the user click on the auth button, PeerTube will forward the request in this function
// onLogout: ... onAuthRequest: (req, res) => {
res.redirect('https://external-auth.example.com/auth')
},
// Same than registerIdAndPassAuth option // Same than registerIdAndPassAuth option
// hookTokenValidity: ... // onLogout: ...
})
router.use('/external-auth-callback', (req, res) => { // Same than registerIdAndPassAuth option
// Forward the request to PeerTube // hookTokenValidity: ...
result.userAuthenticated({
req,
res,
username: 'user'
email: 'user@example.com'
role: 2
displayName: 'User display name'
}) })
})
// Unregister this external auth method router.use('/external-auth-callback', (req, res) => {
unregisterExternalAuth('my-auth-method) // 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 #### Add new transcoding profiles
@ -393,15 +411,41 @@ async function register ({
} }
``` ```
### Client helpers (themes & plugins) ### 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: '...' })
}
// Load a video
{
const video = await peertubeHelpers.videos.loadByUrl('...')
}
}
```
See the [plugin API reference](https://docs.joinpeertube.org/api-plugins) to see the complete helpers list.
### Client API (themes & plugins)
#### Plugin static route #### Plugin static route
To get your plugin static route: To get your plugin static route:
```js ```js
const baseStaticUrl = peertubeHelpers.getBaseStaticRoute() function register (...) {
const imageUrl = baseStaticUrl + '/images/chocobo.png' const baseStaticUrl = peertubeHelpers.getBaseStaticRoute()
const imageUrl = baseStaticUrl + '/images/chocobo.png'
}
``` ```
#### Notifier #### Notifier
@ -409,9 +453,11 @@ const imageUrl = baseStaticUrl + '/images/chocobo.png'
To notify the user with the PeerTube ToastModule: To notify the user with the PeerTube ToastModule:
```js ```js
const { notifier } = peertubeHelpers function register (...) {
notifier.success('Success message content.') const { notifier } = peertubeHelpers
notifier.error('Error message content.') notifier.success('Success message content.')
notifier.error('Error message content.')
}
``` ```
#### Markdown Renderer #### Markdown Renderer
@ -419,13 +465,15 @@ notifier.error('Error message content.')
To render a formatted markdown text to HTML: To render a formatted markdown text to HTML:
```js ```js
const { markdownRenderer } = peertubeHelpers function register (...) {
const { markdownRenderer } = peertubeHelpers
await markdownRenderer.textMarkdownToHTML('**My Bold Text**') await markdownRenderer.textMarkdownToHTML('**My Bold Text**')
// return <strong>My Bold Text</strong> // return <strong>My Bold Text</strong>
await markdownRenderer.enhancedMarkdownToHTML('![alt-img](http://.../my-image.jpg)') await markdownRenderer.enhancedMarkdownToHTML('![alt-img](http://.../my-image.jpg)')
// return <img alt=alt-img src=http://.../my-image.jpg /> // return <img alt=alt-img src=http://.../my-image.jpg />
}
``` ```
#### Custom Modal #### Custom Modal
@ -433,17 +481,19 @@ await markdownRenderer.enhancedMarkdownToHTML('![alt-img](http://.../my-image.jp
To show a custom modal: To show a custom modal:
```js ```js
peertubeHelpers.showModal({ function register (...) {
title: 'My custom modal title', peertubeHelpers.showModal({
content: '<p>My custom modal content</p>', title: 'My custom modal title',
// Optionals parameters : content: '<p>My custom modal content</p>',
// show close icon // Optionals parameters :
close: true, // show close icon
// show cancel button and call action() after hiding modal close: true,
cancel: { value: 'cancel', action: () => {} }, // show cancel button and call action() after hiding modal
// show confirm button and call action() after hiding modal cancel: { value: 'cancel', action: () => {} },
confirm: { value: 'confirm', action: () => {} }, // show confirm button and call action() after hiding modal
}) confirm: { value: 'confirm', action: () => {} },
})
}
``` ```
#### Translate #### Translate
@ -451,8 +501,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): You can translate some strings of your plugin (PeerTube will use your `translations` object of your `package.json` file):
```js ```js
peertubeHelpers.translate('User name') function register (...) {
.then(translation => console.log('Translated User name by ' + translation)) peertubeHelpers.translate('User name')
.then(translation => console.log('Translated User name by ' + translation))
}
``` ```
#### Get public settings #### Get public settings
@ -460,24 +512,28 @@ peertubeHelpers.translate('User name')
To get your public plugin settings: To get your public plugin settings:
```js ```js
peertubeHelpers.getSettings() function register (...) {
.then(s => { peertubeHelpers.getSettings()
if (!s || !s['site-id'] || !s['url']) { .then(s => {
console.error('Matomo settings are not set.') if (!s || !s['site-id'] || !s['url']) {
return console.error('Matomo settings are not set.')
} return
}
// ... // ...
}) })
}
``` ```
#### Get server config #### Get server config
```js ```js
peertubeHelpers.getServerConfig() function register (...) {
.then(config => { peertubeHelpers.getServerConfig()
console.log('Fetched server config.', config) .then(config => {
}) console.log('Fetched server config.', config)
})
}
``` ```
#### Add custom fields to video form #### Add custom fields to video form
@ -540,6 +596,26 @@ async function register ({
}) })
} }
``` ```
#### 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
}
})
}
```
### Publishing ### Publishing
PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes