Add data directory for plugins and some helpers

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

diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md
index e30d95fc94434b249977760bdfea5dd200e7049e..36ade117bb5a9b0c444b6897735dfae57ecd0f7e 100644 (file)
--- a/support/doc/plugins/guide.md
+++ b/support/doc/plugins/guide.md
@@ -15,7 +15,7 @@
     - [Add custom routes](#add-custom-routes)
     - [Add external auth methods](#add-external-auth-methods)
     - [Add new transcoding profiles](#add-new-transcoding-profiles)
     - [Add custom routes](#add-custom-routes)
     - [Add external auth methods](#add-external-auth-methods)
     - [Add new transcoding profiles](#add-new-transcoding-profiles)

-  - [Helpers](#helpers)
+    - [Server helpers](#server-helpers)

   - [Client API (themes & plugins)](#client-api-themes--plugins)
     - [Plugin static route](#plugin-static-route)
     - [Notifier](#notifier)
   - [Client API (themes & plugins)](#client-api-themes--plugins)
     - [Plugin static route](#plugin-static-route)
     - [Notifier](#notifier)


@@ -26,6 +26,7 @@
     - [Get server config](#get-server-config)
     - [Add custom fields to video form](#add-custom-fields-to-video-form)
     - [Register settings script](#register-settings-script)
     - [Get server config](#get-server-config)
     - [Add custom fields to video form](#add-custom-fields-to-video-form)
     - [Register settings script](#register-settings-script)

+    - [HTML placeholder elements](#html-placeholder-elements)

   - [Publishing](#publishing)
 - [Write a plugin/theme](#write-a-plugintheme)
   - [Clone the quickstart repository](#clone-the-quickstart-repository)
   - [Publishing](#publishing)
 - [Write a plugin/theme](#write-a-plugintheme)
   - [Clone the quickstart repository](#clone-the-quickstart-repository)


@@ -194,12 +195,30 @@ Plugins can store/load JSON data, that PeerTube will store in its database (so d
 Example:
 
 ```js
 Example:
 
 ```js

-function register (...) {
+function register ({
+  storageManager
+}) {

   const value = await storageManager.getData('mykey')
   await storageManager.storeData('mykey', { subkey: 'value' })
 }
 ```
 
   const value = await storageManager.getData('mykey')
   await storageManager.storeData('mykey', { subkey: 'value' })
 }
 ```
 

+You can also store files in the plugin data directory (`/{plugins-directory}/data/{npm-plugin-name}`).
+This directory and its content won't be deleted when your plugin is uninstalled/upgraded.
+
+```js
+function register ({
+  storageManager,
+  peertubeHelpers
+}) {
+  const basePath = peertubeHelpers.plugin.getDataDirectoryPath()
+
+  fs.writeFile(path.join(basePath, 'filename.txt'), 'content of my file', function (err) {
+    ...
+  })
+}
+```
+

 #### Update video constants
 
 You can add/delete video categories, licences or languages using the appropriate managers:
 #### Update video constants
 
 You can add/delete video categories, licences or languages using the appropriate managers:


@@ -225,9 +244,27 @@ function register (...) {
 You can create custom routes using an [express Router](https://expressjs.com/en/4x/api.html#router) for your plugin:
 
 ```js
 You can create custom routes using an [express Router](https://expressjs.com/en/4x/api.html#router) for your plugin:
 
 ```js

-function register (...) {
+function register ({
+  router
+}) {

   const router = getRouter()
   router.get('/ping', (req, res) => res.json({ message: 'pong' }))
   const router = getRouter()
   router.get('/ping', (req, res) => res.json({ message: 'pong' }))

+
+  // Users are automatically authenticated
+  router.get('/auth', (res, res) => {
+    const user = peertubeHelpers.user.getAuthUser(res)
+
+    const isAdmin = user.role === 0
+    const isModerator = user.role === 1
+    const isUser = user.role === 2
+
+    res.json({
+      username: user.username,
+      isAdmin,
+      isModerator,
+      isUser
+    })
+  })

 }
 ```
 
 }
 ```
 


@@ -424,7 +461,7 @@ async function register ({
 During live transcode input options are applied once for each target resolution.
 Plugins are responsible for detecting such situation and applying input options only once if necessary.
 
 During live transcode input options are applied once for each target resolution.
 Plugins are responsible for detecting such situation and applying input options only once if necessary.
 

-### Helpers
+#### Server helpers

 
 PeerTube provides your plugin some helpers. For example:
 
 
 PeerTube provides your plugin some helpers. For example:
 


@@ -628,6 +665,21 @@ async function register ({ registerSettingsScript }) {
 }
 ```
 
 }
 ```
 

+#### HTML placeholder elements
+
+PeerTube provides some HTML id so plugins can easily insert their own element:
+
+```js
+async function register (...) {
+  const elem = document.createElement('div')
+  elem.className = 'hello-world-h4'
+  elem.innerHTML = '<h4>Hello everybody! This is an element next to the player</h4>'
+
+  document.getElementById('plugin-placeholder-player-next').appendChild(elem)
+}
+```
+
+See the complete list on https://docs.joinpeertube.org/api-plugins

 
 ### Publishing
 
 
 ### Publishing
 


@@ -728,7 +780,7 @@ If you want to translate strings of your plugin (like labels of your registered
 {
   ...,
   "translations": {
 {
   ...,
   "translations": {

-    "fr-FR": "./languages/fr.json",
+    "fr": "./languages/fr.json",

     "pt-BR": "./languages/pt-BR.json"
   },
   ...
     "pt-BR": "./languages/pt-BR.json"
   },
   ...


@@ -736,7 +788,6 @@ If you want to translate strings of your plugin (like labels of your registered
 ```
 
 The key should be one of the locales defined in [i18n.ts](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/i18n/i18n.ts).
 ```
 
 The key should be one of the locales defined in [i18n.ts](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/i18n/i18n.ts).

-You **must** use the complete locales (`fr-FR` instead of `fr`).

 
 Translation files are just objects, with the english sentence as the key and the translation as the value.
 `fr.json` could contain for example:
 
 Translation files are just objects, with the english sentence as the key and the translation as the value.
 `fr.json` could contain for example: