1d15f062 · samitouri/QOSami-HFS-2 · siGit Code & Deploy

@@ -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`

plugins: more doc