documenting backend plugin's api
Massimo Melina committed
Jan 13, 2022 at 10:48 UTC
0d83d7b965b0d51cfe2df929879e4876a8fae6e4
1 file changed
+26
-2
README.md
+26
-2
@@ -136,11 +136,35 @@ This file is javascript module that is supposed to expose one or more of the sup
136
- `unload: () => void` callback called when unloading a plugin. This is a good place for example to clearInterval().
137
- `onDirEntry: ({ entry: DirEntry, listPath: string }) => void | false` by providing this callback you can manipulate the record
138
that is sent to the frontend (`entry`), or you can return false to exclude this entry from the results.
139
+- `api: object` if your plugin exports an empty object with name `api`, it will be filled with useful functions.
140
+ You'll just need this line
141
+ ```js
142
+ const api = exports.api = {}
143
+ ```
144
+ Now let's have a look at what you'll find inside.
145
+ - `getConfig(key: string): any` this is the way to go if you need some configuration to do your job.
146
+
147
+ Eg: you want a `message` text. This should be put by the user in the main config file, under the `plugins_config` property.
148
+ If for example your plugin is called `banner`, in the `config.yaml` you should have
149
+ ```yaml
150
+ plugins_config:
151
+ banner:
152
+ message: Hi there!
153
+ ```
154
+ Now you can use `api.getConfig('message')` to read it.
155
+
156
+ Beware: `api` object is filled just after plugin initialization. So it will be empty if you use it right-away, but it will
157
+ be good if you use it inside a callback. If you need to do something with it at the very start, then please make your code like this
158
+ ```js
159
+
160
+ setTimeout(() => { // delay execution just a bit
161
+ console.log('getting my message correctly', api.getConfig('message')) // this is good
162
+ })
163
+ //console.log( api.getConfig('message') ) // this would fail because the api object is still empty
164
+ ```
165
166
Each plug-in can have a `public` folder, and its files will be accessible at `/~/plugins/PLUGIN_NAME/FILENAME`.
167
142
-If your plugin needs to get some configuration, it should require the `getPluginConfig(pluginName:string)` function.
143
-The content will be read from the main config file, under the `plugins_config` property.
168
169
### Front-end specific
170