docs: better
Massimo Melina committed
Jun 4, 2023 at 12:28 UTC
3b5e891be9ed0e8c89256c52ecef063489599daf
1 file changed
+23
-11
dev-plugins.md
+23
-11
@@ -8,28 +8,41 @@ Each plug-in has access to the same set of features.
8
Normally you'll have a plug-in that's a theme, and another that's a firewall,
9
but nothing is preventing a single plug-in from doing both tasks.
10
11
-`plugin.js` is a javascript module that exports an `init` function like this:
11
+## Exported object
12
+`plugin.js` is a javascript module, and its main way to communicate with HFS is by exporting things.
13
+For example, it can define its description like this
14
+```js
15
+exports.description = "I'm a nice plugin"
16
+```
17
+
18
+The set of things exported goes by the name "exported object".
19
+A plugin can define an `init` function like this:
20
```js
21
exports.init = api => ({
22
frontend_css: 'mystyle.css'
23
})
24
```
25
18
-The init function is called when the module is loaded and should return an object with things to customize.
19
-In the example above we are asking a css file to be loaded in the frontend.
20
-The parameter `api` object contains some useful things we'll see later.
21
-You can decide to return things in the `init` function, or directly in the `exports`.
22
-If you need to access the api you must use `init`, otherwise you can go directly with `exports`.
26
+The init function is called by HFS when the module is loaded and should return an object with more things to
27
+added/merged to the exported object. In the example above we are asking a css file to be loaded in the frontend.
28
+Since it's a basic example, you could have simply defined it like this:
29
+```js
30
+exports.frontend_css = 'mystyle.css'
31
+```
32
+but in more complex cases you'll need go through the `init`.
33
+Thus, you can decide to return things in the `init` function, or directly in the `exports`.
34
+If you need to access the api you must use `init`, since that's the only place where it is found, otherwise you
35
+can go directly with `exports`. The parameter `api` of the init is an object containing useful things [we'll see later](#api-object).
36
24
-Let's first look at the things you can return:
37
+Let's first look at the things you can export:
38
26
-## Things a plugin can return or export
39
+## Things a plugin can export
40
28
-All the following properties are essentially optional.
41
+All the following properties are optional unless otherwise specified.
42
43
- `description: string` try to explain what this plugin is for. This must go in `exports` and use "double quotes".
44
- `version: number` use progressive numbers to distinguish each release. This must go in `exports`.
32
-- `apiRequired: number | [min:number,max:number]` declare version(s) for which the plugin is designed for. You'll find api version in `src/const.ts`. This must go in `exports`.
45
+- `apiRequired: number | [min:number,max:number]` declare version(s) for which the plugin is designed for. You'll find api version in `src/const.ts`. This must go in `exports` and is mandatory.
46
- `frontend_css: string | string[]` path to one or more css files that you want the frontend to load. These are to be placed in the `public` folder (refer below).
47
You can also include external files, by entering a full URL.
48
- `frontend_js: string | string[]` path to one or more js files that you want the frontend to load. These are to be placed in the `public` folder (refer below).
@@ -132,7 +145,6 @@ The `api` object you get as parameter of the `init` contains the following:
145
```js
146
const { watchLoad } = api.require('./watchLoad')
147
```
135
-
148
You *should* try to keep this kind of behavior at its minimum, as name of sources and elements can change, and your
149
plugin can become incompatible with future versions.
150
If you need something for your plugin that's not covered by `api`, you can test it with this method, but you should