aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-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
5Themes are exactly the same than plugins, except that: 31Themes 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
22async function register ({ registerHook }) { 48async 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({
87const adminName = await settingsManager.getSetting('admin-name') 113const adminName = await settingsManager.getSetting('admin-name')
88``` 114```
89 115
90##### Storage 116#### Storage
91 117
92Plugins can store/load JSON data, that PeerTube will store in its database (so don't put files in there). 118Plugins 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
235Every time you want to publish another version of your plugin/theme, just update the `version` key from the `package.json` 261Every time you want to publish another version of your plugin/theme, just update the `version` key from the `package.json`
236and republish it on NPM. Remember that the PeerTube index will take into account your new plugin/theme version after ~24 hours. 262and 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
269Unfortunately, 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`).
270So please:
271 * Don't make assumptions and check every parameter you want to use. For example:
272
273```js
274registerHook({
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
287If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` `package.json` field.
288This 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
292If 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