Move to new documentation links

[github/Chocobozzz/PeerTube.git] / support / doc / plugins / guide.md

diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md
index 52e3b6052e38d3b9bda736cf01a595a0ffe0040f..2cc544f1c4850221729e10bc433d782a55eccb9b 100644 (file)
--- a/support/doc/plugins/guide.md
+++ b/support/doc/plugins/guide.md
@@ -12,6 +12,7 @@
     - [Storage](#storage)
     - [Update video constants](#update-video-constants)
     - [Add custom routes](#add-custom-routes)
+    - [Add custom WebSocket handlers](#add-custom-websocket-handlers)
     - [Add external auth methods](#add-external-auth-methods)
     - [Add new transcoding profiles](#add-new-transcoding-profiles)
     - [Server helpers](#server-helpers)
@@ -317,6 +318,43 @@ The `ping` route can be accessed using:
  * Or `/plugins/:pluginName/router/ping`
 
 
+#### Add custom WebSocket handlers
+
+**PeerTube >= 5.0**
+
+You can create custom WebSocket servers (like [ws](https://github.com/websockets/ws) for example) using `registerWebSocketRoute`:
+
+```js
+function register ({
+  registerWebSocketRoute,
+  peertubeHelpers
+}) {
+  const wss = new WebSocketServer({ noServer: true })
+
+  wss.on('connection', function connection(ws) {
+    peertubeHelpers.logger.info('WebSocket connected!')
+
+    setInterval(() => {
+      ws.send('WebSocket message sent by server');
+    }, 1000)
+  })
+
+  registerWebSocketRoute({
+    route: '/my-websocket-route',
+
+    handler: (request, socket, head) => {
+      wss.handleUpgrade(request, socket, head, ws => {
+        wss.emit('connection', ws, request)
+      })
+    }
+  })
+}
+```
+
+The `my-websocket-route` route can be accessed using:
+ * `/plugins/:pluginName/:pluginVersion/ws/my-websocket-route`
+ * Or `/plugins/:pluginName/ws/my-websocket-route`
+
 #### Add external auth methods
 
 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):
@@ -395,7 +433,27 @@ function register (...) {
       username: 'user'
       email: 'user@example.com'
       role: 2
-      displayName: 'User display name'
+      displayName: 'User display name',
+
+      // Custom admin flags (bypass video auto moderation etc.)
+      // https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/users/user-flag.model.ts
+      // PeerTube >= 5.1
+      adminFlags: 0,
+      // Quota in bytes
+      // PeerTube >= 5.1
+      videoQuota: 1024 * 1024 * 1024, // 1GB
+      // PeerTube >= 5.1
+      videoQuotaDaily: -1, // Unlimited
+
+      // Update the user profile if it already exists
+      // Default behaviour is no update
+      // Introduced in PeerTube >= 5.1
+      userUpdater: ({ fieldName, currentValue, newValue }) => {
+        // Always use new value except for videoQuotaDaily field
+        if (fieldName === 'videoQuotaDaily') return currentValue
+
+        return newValue
+      }
     })
   })
 
@@ -527,7 +585,7 @@ async function register ({
 }
 ```
 
-See the [plugin API reference](https://docs.joinpeertube.org/api-plugins) to see the complete helpers list.
+See the [plugin API reference](https://docs.joinpeertube.org/api/plugins) to see the complete helpers list.
 
 ### Client API (themes & plugins)
 
@@ -781,7 +839,7 @@ PeerTube provides some selectors (using `id` HTML attribute) on important blocks
 
 For example `#plugin-selector-login-form` could be used to hide the login form.
 
-See the complete list on https://docs.joinpeertube.org/api-plugins
+See the complete list on https://docs.joinpeertube.org/api/plugins
 
 #### HTML placeholder elements
 
@@ -797,7 +855,7 @@ async function register (...) {
 }
 ```
 
-See the complete list on https://docs.joinpeertube.org/api-plugins
+See the complete list on https://docs.joinpeertube.org/api/plugins
 
 #### Add/remove left menu links
 
@@ -914,7 +972,10 @@ If you want to write modern JavaScript, please use a transpiler like [Babel](htt
 
 **Typescript**
 
-If you want to use __Typescript__, you can add __PeerTube__ types as dev dependencies:
+The easiest way to use __Typescript__ for both front-end and backend code is to clone [peertube-plugin-quickstart-typescript](https://github.com/JohnXLivingston/peertube-plugin-quickstart-typescript/) (also available on [framagit](https://framagit.org/Livingston/peertube-plugin-quickstart-typescript/)) instead of `peertube-plugin-quickstart`.
+Please read carefully the [README file](https://github.com/JohnXLivingston/peertube-plugin-quickstart-typescript/blob/main/README.md), as there are some other differences with `peertube-plugin-quickstart` (using SCSS instead of CSS, linting rules, ...).
+
+If you don't want to use `peertube-plugin-quickstart-typescript`, you can also manually add a dev dependency to __Peertube__ types:
 
 ```
 npm install --save-dev @peertube/peertube-types
@@ -1015,13 +1076,16 @@ You built files are in the `dist/` directory. Check `package.json` to correctly
 
 ### Test your plugin/theme
 
+PeerTube dev server (ran with `npm run dev` on `localhost:3000`) can't inject plugin CSS.
+It's the reason why we don't use the dev mode but build PeerTube instead.
+
 You'll need to have a local PeerTube instance:
  * Follow the [dev prerequisites](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#prerequisites)
  (to clone the repository, install dependencies and prepare the database)
- * Build PeerTube (`--light` to only build the english language):
+ * Build PeerTube:
 
 ```
-$ npm run build -- --light
+$ npm run build
 ```
 
  * Build the CLI:
@@ -1030,10 +1094,10 @@ $ npm run build -- --light
 $ npm run setup:cli
 ```
 
- * Run PeerTube (you can access to your instance on http://localhost:9000):
+ * Run PeerTube (you can access to your instance on `localhost:9000`):
 
 ```
-$ NODE_ENV=test npm start
+$ NODE_ENV=dev npm start
 ```
 
  * Register the instance via the CLI:
@@ -1076,7 +1140,7 @@ $ npm deprecate peertube-plugin-xxx@"> 0.0.0" "explain here why you deprecate yo
 
 ## Plugin & Theme hooks/helpers API
 
-See the dedicated documentation: https://docs.joinpeertube.org/api-plugins
+See the dedicated documentation: https://docs.joinpeertube.org/api/plugins
 
 
 ## Tips