aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/plugins/guide.md
diff options
context:
space:
mode:
Diffstat (limited to 'support/doc/plugins/guide.md')
-rw-r--r--support/doc/plugins/guide.md132
1 files changed, 120 insertions, 12 deletions
diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md
index 8f8884d00..1aae65a1c 100644
--- a/support/doc/plugins/guide.md
+++ b/support/doc/plugins/guide.md
@@ -11,6 +11,11 @@
11 - [Server helpers (only for plugins)](#server-helpers-only-for-plugins) 11 - [Server helpers (only for plugins)](#server-helpers-only-for-plugins)
12 - [Settings](#settings) 12 - [Settings](#settings)
13 - [Storage](#storage) 13 - [Storage](#storage)
14 - [Update video constants](#update-video-constants)
15 - [Client helpers (themes & plugins)](#client-helpers-themes--plugins)
16 - [Plugin static route](#plugin-static-route)
17 - [Translate](#translate)
18 - [Get public settings](#get-public-settings)
14 - [Publishing](#publishing) 19 - [Publishing](#publishing)
15- [Write a plugin/theme](#write-a-plugintheme) 20- [Write a plugin/theme](#write-a-plugintheme)
16 - [Clone the quickstart repository](#clone-the-quickstart-repository) 21 - [Clone the quickstart repository](#clone-the-quickstart-repository)
@@ -18,8 +23,10 @@
18 - [Update README](#update-readme) 23 - [Update README](#update-readme)
19 - [Update package.json](#update-packagejson) 24 - [Update package.json](#update-packagejson)
20 - [Write code](#write-code) 25 - [Write code](#write-code)
26 - [Add translations](#add-translations)
21 - [Test your plugin/theme](#test-your-plugintheme) 27 - [Test your plugin/theme](#test-your-plugintheme)
22 - [Publish](#publish) 28 - [Publish](#publish)
29- [Plugin & Theme hooks/helpers API](#plugin--theme-hookshelpers-api)
23- [Tips](#tips) 30- [Tips](#tips)
24 - [Compatibility with PeerTube](#compatibility-with-peertube) 31 - [Compatibility with PeerTube](#compatibility-with-peertube)
25 - [Spam/moderation plugin](#spammoderation-plugin) 32 - [Spam/moderation plugin](#spammoderation-plugin)
@@ -40,18 +47,6 @@ A plugin registers functions in JavaScript to execute when PeerTube (server and
40 For example to replace words in video comments, or change the videos list behaviour 47 For example to replace words in video comments, or change the videos list behaviour
41 * `action`: used to do something after a certain trigger. For example to send a hook every time a video is published 48 * `action`: used to do something after a certain trigger. For example to send a hook every time a video is published
42 * `static`: same than `action` but PeerTube waits their execution 49 * `static`: same than `action` but PeerTube waits their execution
43
44Example:
45
46```js
47// This register function is called by PeerTube, and **must** return a promise
48async function register ({ registerHook, registerSetting, settingsManager, storageManager, peertubeHelpers }) {
49 registerHook({
50 target: 'action:application.listening',
51 handler: () => displayHelloWorld()
52 })
53}
54```
55 50
56On server side, these hooks are registered by the `library` file defined in `package.json`. 51On server side, these hooks are registered by the `library` file defined in `package.json`.
57 52
@@ -63,6 +58,27 @@ On server side, these hooks are registered by the `library` file defined in `pac
63} 58}
64``` 59```
65 60
61And `main.js` defines a `register` function:
62
63Example:
64
65```js
66async function register ({
67 registerHook,
68 registerSetting,
69 settingsManager,
70 storageManager,
71 videoCategoryManager,
72 videoLicenceManager,
73 videoLanguageManager
74}) {
75 registerHook({
76 target: 'action:application.listening',
77 handler: () => displayHelloWorld()
78 })
79}
80```
81
66 82
67On client side, these hooks are registered by the `clientScripts` files defined in `package.json`. 83On client side, these hooks are registered by the `clientScripts` files defined in `package.json`.
68All client scripts have scopes so PeerTube client only loads scripts it needs: 84All client scripts have scopes so PeerTube client only loads scripts it needs:
@@ -84,6 +100,17 @@ All client scripts have scopes so PeerTube client only loads scripts it needs:
84} 100}
85``` 101```
86 102
103And these scripts also define a `register` function:
104
105```js
106function register ({ registerHook, peertubeHelpers }) {
107 registerHook({
108 target: 'action:application.init',
109 handler: () => onApplicationInit(peertubeHelpers)
110 })
111}
112```
113
87### Static files 114### Static files
88 115
89Plugins can declare static directories that PeerTube will serve (images for example) 116Plugins can declare static directories that PeerTube will serve (images for example)
@@ -93,6 +120,17 @@ or `/themes/{theme-name}/{theme-version}/static/` routes.
93### CSS 120### CSS
94 121
95Plugins can declare CSS files that PeerTube will automatically inject in the client. 122Plugins can declare CSS files that PeerTube will automatically inject in the client.
123If you need to override existing style, you can use the `#custom-css` selector:
124
125```
126body#custom-css {
127 color: red;
128}
129
130#custom-css .header {
131 background-color: red;
132}
133```
96 134
97### Server helpers (only for plugins) 135### Server helpers (only for plugins)
98 136
@@ -124,6 +162,58 @@ const value = await storageManager.getData('mykey')
124await storageManager.storeData('mykey', { subkey: 'value' }) 162await storageManager.storeData('mykey', { subkey: 'value' })
125``` 163```
126 164
165#### Update video constants
166
167You can add/delete video categories, licences or languages using the appropriate managers:
168
169```js
170videoLanguageManager.addLanguage('al_bhed', 'Al Bhed')
171videoLanguageManager.deleteLanguage('fr')
172
173videoCategoryManager.addCategory(42, 'Best category')
174videoCategoryManager.deleteCategory(1) // Music
175
176videoLicenceManager.addLicence(42, 'Best licence')
177videoLicenceManager.deleteLicence(7) // Public domain
178```
179
180### Client helpers (themes & plugins)
181
182### Plugin static route
183
184To get your plugin static route:
185
186```js
187const baseStaticUrl = peertubeHelpers.getBaseStaticRoute()
188const imageUrl = baseStaticUrl + '/images/chocobo.png'
189```
190
191#### Translate
192
193You can translate some strings of your plugin (PeerTube will use your `translations` object of your `package.json` file):
194
195```js
196peertubeHelpers.translate('User name')
197 .then(translation => console.log('Translated User name by ' + translation))
198```
199
200#### Get public settings
201
202To get your public plugin settings:
203
204```js
205peertubeHelpers.getSettings()
206 .then(s => {
207 if (!s || !s['site-id'] || !s['url']) {
208 console.error('Matomo settings are not set.')
209 return
210 }
211
212 // ...
213 })
214```
215
216
127### Publishing 217### Publishing
128 218
129PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes 219PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes
@@ -215,6 +305,24 @@ Now you can register hooks or settings, write CSS and add static directories to
215and will be supported by web browsers. 305and will be supported by web browsers.
216If you want to write modern JavaScript, please use a transpiler like [Babel](https://babeljs.io/). 306If you want to write modern JavaScript, please use a transpiler like [Babel](https://babeljs.io/).
217 307
308### Add translations
309
310If you want to translate strings of your plugin (like labels of your registered settings), create a file and add it to `package.json`:
311
312```json
313{
314 ...,
315 "translations": {
316 "fr-FR": "./languages/fr.json",
317 "pt-BR": "./languages/pt-BR.json"
318 },
319 ...
320}
321```
322
323The key should be one of the locales defined in [i18n.ts](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/i18n/i18n.ts).
324You **must** use the complete locales (`fr-FR` instead of `fr`).
325
218### Test your plugin/theme 326### Test your plugin/theme
219 327
220You'll need to have a local PeerTube instance: 328You'll need to have a local PeerTube instance: