Update plugins doc

This commit is contained in:
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

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 (...) {
registerSetting({
name: 'admin-name', name: 'admin-name',
label: 'Admin name', label: 'Admin name',
type: 'input', type: 'input',
// type: input | input-checkbox | input-password | input-textarea | markdown-text | markdown-enhanced // type: input | input-checkbox | input-password | input-textarea | markdown-text | markdown-enhanced | 'select' | 'html'
default: 'my super name' 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,7 +241,9 @@ 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 (...) {
registerIdAndPassAuth({
authName: 'my-auth-method', authName: 'my-auth-method',
// PeerTube will try all id and pass plugins in the weight DESC order // PeerTube will try all id and pass plugins in the weight DESC order
@ -261,17 +275,20 @@ registerIdAndPassAuth({
// Auth failed // Auth failed
return null return null
} }
}) })
// Unregister this auth method // Unregister this auth method
unregisterIdAndPassAuth('my-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({
// result contains the userAuthenticated auth method you can call to authenticate a user
const result = registerExternalAuth({
authName: 'my-auth-method', authName: 'my-auth-method',
// Will be displayed in a button next to the login form // Will be displayed in a button next to the login form
@ -287,9 +304,9 @@ const result = registerExternalAuth({
// Same than registerIdAndPassAuth option // Same than registerIdAndPassAuth option
// hookTokenValidity: ... // hookTokenValidity: ...
}) })
router.use('/external-auth-callback', (req, res) => { router.use('/external-auth-callback', (req, res) => {
// Forward the request to PeerTube // Forward the request to PeerTube
result.userAuthenticated({ result.userAuthenticated({
req, req,
@ -299,10 +316,11 @@ router.use('/external-auth-callback', (req, res) => {
role: 2 role: 2
displayName: 'User display name' displayName: 'User display name'
}) })
}) })
// Unregister this external auth method // Unregister this external auth method
unregisterExternalAuth('my-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,6 +481,7 @@ await markdownRenderer.enhancedMarkdownToHTML('![alt-img](http://.../my-image.jp
To show a custom modal: To show a custom modal:
```js ```js
function register (...) {
peertubeHelpers.showModal({ peertubeHelpers.showModal({
title: 'My custom modal title', title: 'My custom modal title',
content: '<p>My custom modal content</p>', content: '<p>My custom modal content</p>',
@ -444,6 +493,7 @@ To show a custom modal:
// show confirm button and call action() after hiding modal // show confirm button and call action() after hiding modal
confirm: { value: 'confirm', action: () => {} }, 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 (...) {
peertubeHelpers.translate('User name')
.then(translation => console.log('Translated User name by ' + translation)) .then(translation => console.log('Translated User name by ' + translation))
}
``` ```
#### Get public settings #### Get public settings
@ -460,7 +512,8 @@ peertubeHelpers.translate('User name')
To get your public plugin settings: To get your public plugin settings:
```js ```js
peertubeHelpers.getSettings() function register (...) {
peertubeHelpers.getSettings()
.then(s => { .then(s => {
if (!s || !s['site-id'] || !s['url']) { if (!s || !s['site-id'] || !s['url']) {
console.error('Matomo settings are not set.') console.error('Matomo settings are not set.')
@ -469,15 +522,18 @@ peertubeHelpers.getSettings()
// ... // ...
}) })
}
``` ```
#### Get server config #### Get server config
```js ```js
peertubeHelpers.getServerConfig() function register (...) {
peertubeHelpers.getServerConfig()
.then(config => { .then(config => {
console.log('Fetched server config.', 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