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,20 +156,23 @@ 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
function register (...) {
registerSetting({ 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'
}) })
@ -179,6 +184,7 @@ 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
function register (...) {
const value = await storageManager.getData('mykey') const value = await storageManager.getData('mykey')
await storageManager.storeData('mykey', { subkey: 'value' }) await storageManager.storeData('mykey', { subkey: 'value' })
}
``` ```
#### Update video constants #### Update video constants
@ -197,6 +205,7 @@ 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
function register (...) {
videoLanguageManager.addLanguage('al_bhed', 'Al Bhed') videoLanguageManager.addLanguage('al_bhed', 'Al Bhed')
videoLanguageManager.deleteLanguage('fr') videoLanguageManager.deleteLanguage('fr')
@ -208,6 +217,7 @@ 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
function register (...) {
const router = getRouter() const router = getRouter()
router.get('/ping', (req, res) => res.json({ message: 'pong' })) router.get('/ping', (req, res) => res.json({ message: 'pong' }))
}
``` ```
The `ping` route can be accessed using: The `ping` route can be accessed using:
@ -229,6 +241,8 @@ 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
function register (...) {
registerIdAndPassAuth({ registerIdAndPassAuth({
authName: 'my-auth-method', authName: 'my-auth-method',
@ -265,11 +279,14 @@ registerIdAndPassAuth({
// 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
function register (...) {
// result contains the userAuthenticated auth method you can call to authenticate a user // result contains the userAuthenticated auth method you can call to authenticate a user
const result = registerExternalAuth({ const result = registerExternalAuth({
authName: 'my-auth-method', authName: 'my-auth-method',
@ -303,6 +320,7 @@ router.use('/external-auth-callback', (req, res) => {
// 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
function register (...) {
const baseStaticUrl = peertubeHelpers.getBaseStaticRoute() const baseStaticUrl = peertubeHelpers.getBaseStaticRoute()
const imageUrl = baseStaticUrl + '/images/chocobo.png' 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
function register (...) {
const { notifier } = peertubeHelpers const { notifier } = peertubeHelpers
notifier.success('Success message content.') notifier.success('Success message content.')
notifier.error('Error message content.') notifier.error('Error message content.')
}
``` ```
#### Markdown Renderer #### Markdown Renderer
@ -419,6 +465,7 @@ notifier.error('Error message content.')
To render a formatted markdown text to HTML: To render a formatted markdown text to HTML:
```js ```js
function register (...) {
const { markdownRenderer } = peertubeHelpers const { markdownRenderer } = peertubeHelpers
await markdownRenderer.textMarkdownToHTML('**My Bold Text**') await markdownRenderer.textMarkdownToHTML('**My Bold Text**')
@ -426,6 +473,7 @@ await markdownRenderer.textMarkdownToHTML('**My Bold Text**')
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
function register (...) {
peertubeHelpers.translate('User name') 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,6 +512,7 @@ peertubeHelpers.translate('User name')
To get your public plugin settings: To get your public plugin settings:
```js ```js
function register (...) {
peertubeHelpers.getSettings() peertubeHelpers.getSettings()
.then(s => { .then(s => {
if (!s || !s['site-id'] || !s['url']) { if (!s || !s['site-id'] || !s['url']) {
@ -469,15 +522,18 @@ peertubeHelpers.getSettings()
// ... // ...
}) })
}
``` ```
#### Get server config #### Get server config
```js ```js
function register (...) {
peertubeHelpers.getServerConfig() 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