plugins: more doc
Massimo Melina committed
May 15, 2025 at 16:47 UTC
1d15f062641ab324fe390bd22ef9320cbb436165
1 file changed
+34
-8
dev-plugins.md
+34
-8
@@ -373,11 +373,26 @@ To avoid conflicts with other plugins, we suggest to wrap all your code like thi
373
### HFS object
374
375
In frontend you will have access to the `HFS` object of the global scope, which has many properties:
376
-- `onEvent` this is the main API function inside the frontend. Refer to dedicated section below.
377
-- `apiCall`
378
-- `useApi`
379
-- `reloadList`
380
-- `logout`
376
+- `onEvent` this is the main hook inside the frontend. Refer to dedicated section below.
377
+- `apiCall(cmd: string, params?: object, options?: object): Promise<any>` request an [HTTP API](https://hfs-3.apidog.io/),
378
+ where `cmd` is the name and `params` are the respective parameters. Options are:
379
+ - `timeout?: number | false` in seconds
380
+ - `onResponse?: (res: Response, body: any) => any`
381
+ - `method?: string`
382
+ - `skipParse?: boolean`
383
+ - `skipLog?: boolean`
384
+ - `restUri?: string`
385
+- `useApi(cmd: string | Falsy, params?: object, options?: object): object` hook form of `apiCall`.
386
+ The returned object contains:
387
+ - `data: any` result of the api
388
+ - `error: any` in case the api resulted in an error
389
+ - `reload: function` call it if you want to call the api again
390
+ - `loading: boolean` true if the api is loading
391
+ - `getData(): any` if you need to access to `data` inside closures, where it is stale if accessed directly
392
+ - `setData(value: any)` if you need to overwrite `data`
393
+ - `sub: function(callback)` if you need to subscribe for when the api is called again
394
+- `reloadList()` cause the list of files to be reloaded
395
+- `logout(): Promise` logout the current user
396
- `prefixUrl: string` normally an empty string, it will be set in case a [reverse-proxy wants to mount HFS on a path](https://github.com/rejetto/hfs/wiki/Reverse-proxy).
397
- `state: StateObject` [object with many values in it](https://github.com/rejetto/hfs/blob/main/frontend/src/state.ts)
398
- you'll find here some interesting values, like `username` and `loading`.
@@ -436,12 +451,13 @@ The following properties are accessible only immediately at top-level; don't cal
451
API at this level is done with frontend-events, that you can handle by calling
452
453
```typescript
439
-HFS.onEvent(eventName: string, callback: (parameters: object) => any)
454
+HFS.onEvent(eventName: string, callback: (parameters: object, extra: object) => any)
455
```
456
442
-Parameters of your callback and meaning of returned value varies with the event name.
457
+All events of this type have all parameters in a single object, so it's technically a single parameter.
458
+Its content, and what you can return in your callback, vary with the event name.
459
Refer to the specific event for further information.
444
-HFS object is the same you access globally. Here just for legacy, consider it deprecated.
460
+Second parameter is explained in the dedicated section, below.
461
462
Some frontend events can return HTML, which can be expressed in several ways:
463
- as a string containing markup
@@ -458,6 +474,16 @@ Most events have this `def` undefined as they have no default content and are de
474
but when this is not the case, you can replace the default content with nothing by returning `null`.
475
You can produce output for such events also by adding sections (with same name as the event) to file `custom.html`.
476
477
+#### Extra object
478
+
479
+This is an advanced topic, rarely needed.
480
+The "extra" object is the second parameter of your callback, and has the following properties:
481
+- `output: any[]` array of values returned by all plugin/callbacks.
482
+- `setOrder(order: number)` if you need to prioritize your output (and see it before) with respect to other plugins,
483
+ you can specify a negative number. Use a positive number to get the opposite.
484
+
485
+#### List of frontend events
486
+
487
This is a list of available frontend-events, with respective object parameter and output.
488
489
- `additionalEntryDetails`