diff options
Diffstat (limited to 'support/doc')
-rw-r--r-- | support/doc/plugins/guide.md (renamed from support/doc/plugins/quickstart.md) | 68 |
1 files changed, 66 insertions, 2 deletions
diff --git a/support/doc/plugins/quickstart.md b/support/doc/plugins/guide.md index 0e125e707..85e5f1e7d 100644 --- a/support/doc/plugins/quickstart.md +++ b/support/doc/plugins/guide.md | |||
@@ -1,5 +1,31 @@ | |||
1 | # Plugins & Themes | 1 | # Plugins & Themes |
2 | 2 | ||
3 | <!-- START doctoc generated TOC please keep comment here to allow auto update --> | ||
4 | <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> | ||
5 | |||
6 | |||
7 | - [Concepts](#concepts) | ||
8 | - [Hooks](#hooks) | ||
9 | - [Static files](#static-files) | ||
10 | - [CSS](#css) | ||
11 | - [Server helpers (only for plugins)](#server-helpers-only-for-plugins) | ||
12 | - [Settings](#settings) | ||
13 | - [Storage](#storage) | ||
14 | - [Publishing](#publishing) | ||
15 | - [Write a plugin/theme](#write-a-plugintheme) | ||
16 | - [Clone the quickstart repository](#clone-the-quickstart-repository) | ||
17 | - [Configure your repository](#configure-your-repository) | ||
18 | - [Update README](#update-readme) | ||
19 | - [Update package.json](#update-packagejson) | ||
20 | - [Write code](#write-code) | ||
21 | - [Test your plugin/theme](#test-your-plugintheme) | ||
22 | - [Publish](#publish) | ||
23 | - [Tips](#tips) | ||
24 | - [Compatibility with PeerTube](#compatibility-with-peertube) | ||
25 | - [Spam/moderation plugin](#spammoderation-plugin) | ||
26 | |||
27 | <!-- END doctoc generated TOC please keep comment here to allow auto update --> | ||
28 | |||
3 | ## Concepts | 29 | ## Concepts |
4 | 30 | ||
5 | Themes are exactly the same than plugins, except that: | 31 | Themes are exactly the same than plugins, except that: |
@@ -19,7 +45,7 @@ Example: | |||
19 | 45 | ||
20 | ```js | 46 | ```js |
21 | // This register function is called by PeerTube, and **must** return a promise | 47 | // This register function is called by PeerTube, and **must** return a promise |
22 | async function register ({ registerHook }) { | 48 | async function register ({ registerHook, registerSetting, settingsManager, storageManager, peertubeHelpers }) { |
23 | registerHook({ | 49 | registerHook({ |
24 | target: 'action:application.listening', | 50 | target: 'action:application.listening', |
25 | handler: () => displayHelloWorld() | 51 | handler: () => displayHelloWorld() |
@@ -87,7 +113,7 @@ registerSetting({ | |||
87 | const adminName = await settingsManager.getSetting('admin-name') | 113 | const adminName = await settingsManager.getSetting('admin-name') |
88 | ``` | 114 | ``` |
89 | 115 | ||
90 | ##### Storage | 116 | #### Storage |
91 | 117 | ||
92 | Plugins can store/load JSON data, that PeerTube will store in its database (so don't put files in there). | 118 | Plugins can store/load JSON data, that PeerTube will store in its database (so don't put files in there). |
93 | 119 | ||
@@ -235,3 +261,41 @@ $ npm publish | |||
235 | Every time you want to publish another version of your plugin/theme, just update the `version` key from the `package.json` | 261 | Every time you want to publish another version of your plugin/theme, just update the `version` key from the `package.json` |
236 | and republish it on NPM. Remember that the PeerTube index will take into account your new plugin/theme version after ~24 hours. | 262 | and republish it on NPM. Remember that the PeerTube index will take into account your new plugin/theme version after ~24 hours. |
237 | 263 | ||
264 | |||
265 | ## Tips | ||
266 | |||
267 | ### Compatibility with PeerTube | ||
268 | |||
269 | Unfortunately, we don't have enough resources to provide hook compatibility between minor releases of PeerTube (for example between `1.2.x` and `1.3.x`). | ||
270 | So please: | ||
271 | * Don't make assumptions and check every parameter you want to use. For example: | ||
272 | |||
273 | ```js | ||
274 | registerHook({ | ||
275 | target: 'filter:api.video.get.result', | ||
276 | handler: video => { | ||
277 | // We check the parameter exists and the name field exists too, to avoid exceptions | ||
278 | if (video && video.name) video.name += ' <3' | ||
279 | |||
280 | return video | ||
281 | } | ||
282 | }) | ||
283 | ``` | ||
284 | * Don't try to require parent PeerTube modules, only use `peertubeHelpers`. If you need another helper or a specific, please [create an issue](https://github.com/Chocobozzz/PeerTube/issues/new) | ||
285 | * Don't use PeerTube dependencies. Use your own :) | ||
286 | |||
287 | If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` `package.json` field. | ||
288 | This way, older PeerTube versions will still use your old plugin, and new PeerTube versions will use your updated plugin. | ||
289 | |||
290 | ### Spam/moderation plugin | ||
291 | |||
292 | If you want to create an antispam/moderation plugin, you could use the following hooks: | ||
293 | * `filter:api.video.upload.accept.result`: to accept or not local uploads | ||
294 | * `filter:api.video-thread.create.accept.result`: to accept or not local thread | ||
295 | * `filter:api.video-comment-reply.create.accept.result`: to accept or not local replies | ||
296 | * `filter:api.video-threads.list.result`: to change/hide the text of threads | ||
297 | * `filter:api.video-thread-comments.list.result`: to change/hide the text of replies | ||
298 | * `filter:video.auto-blacklist.result`: to automatically blacklist local or remote videos | ||
299 | |||
300 | |||
301 | |||