f4312fda · samitouri/QOSami-HFS · siGit Code & Deploy

@@ -2,10 +2,10 @@

2

3 If the information you are searching for is not in this document, [please ask](https://github.com/rejetto/hfs/discussions).

4

5 -A plug-in is a folder with a `plugin.js` file in it. To install a plugin you just copy the folder into `plugins` folder.

6 -You will find `plugins` folder near `config.yaml`, and then in `USER_FOLDER/.hfs` for Linux and Mac, or near `hfs.exe` on Windows.

5 +A plug-in is a folder with a `plugin.js` file in it. To install a plugin you just copy the folder into the `plugins` folder.

6 +You will find `plugins` folder near `config.yaml`, and then in `USER_FOLDER/.hfs` for Linux and MacOS, or near `hfs.exe` on Windows.

7

8 -Plug-ins can be hot-swapped, and at some extent can be edited without restarting the server.

8 +Plug-ins can be hot-swapped, and to some extent can be edited without restarting the server.

9

10 Each plug-in has access to the same set of features.

11 Normally you'll have a plug-in that's a theme, and another that's a firewall,

@@ -40,8 +40,8 @@ Since it's a basic example, you could have simply defined it like this:

40 ```js

41 exports.frontend_css = 'mystyle.css'

42 ```

43 -but in more complex cases you'll need go through the `init`.

44 -If you need to access the api you must use `init`, since that's the only place where it is found, otherwise you

43 +but in more complex cases you'll need to go through the `init`.

44 +If you need to access the API you must use `init`, since that's the only place where it is found, otherwise you

45 can just use `exports`. The parameter `api` of the init is an object containing useful things [we'll see later](#api-object).

46

47 Let's first look at the things you can export:

@@ -52,10 +52,10 @@ All the following properties are optional unless otherwise specified.

52

53 - `description: string` try to explain what this plugin is for. (JSON syntax)

54 - `version: number` use progressive numbers to distinguish each release

55 -- `apiRequired: number | [min:number,max:number]` declare version(s) for which the plugin is designed for. Mandatory. [Refer to API version history](#api-version-history)

55 +- `apiRequired: number | [min:number,max:number]` declare version(s) for which the plugin is designed. Mandatory. [Refer to API version history](#api-version-history)

56 - `isTheme: boolean | "light" | "dark"` set true if this is a theme that's not supposed to work together with other themes.

57 Running a theme will cause other themes to be stopped. Missing this, HFS will check if the name of the plugin ends with `-theme`.

58 - Special values "light" and "dark" to declare the theme is (for example) dark and forces HFS to use dark-theme as a base.

58 + Special values "light" and "dark" to declare whether the theme is (for example) dark and forces HFS to use dark-theme as a base.

59 - `preview: string | string[]` one or more URLs to images you want to show before your plugin is downloaded. (JSON syntax)

60 - `depend: { repo: string, version: number }[]` declare what other plugins this depends on. (JSON syntax)

61 - `beforePlugin: string` control the order this plugin is executed relative to another

@@ -73,7 +73,7 @@ All the following properties are optional unless otherwise specified.

73 {

74 "web": "https://github.com/rejetto/file-icons",

75 "zip": "/archive/refs/heads/main.zip",

76 - "zipRoot: "file-icons-main/dist",

76 + "zipRoot": "file-icons-main/dist",

77 "main": "https://raw.githubusercontent.com/rejetto/file-icons/main/dist/plugin.js"

78 }

79 ```

@@ -254,7 +254,7 @@ The following information applies to the default frontend, and may not apply to

254

255 Once your script is loaded into the frontend (via `frontend_js`), you will have access to the `HFS` object in the global scope.

256

257 -The HFS objects contains many properties:

257 +The HFS object contains many properties:

258 - `onEvent` this is the main API function inside the frontend. Refer to dedicated section below.

259 - `apiCall`

260 - `useApi`

@@ -301,7 +301,7 @@ The HFS objects contains many properties:

301 - `fileShow(entry: DirEntry, options?: { startPlaying: true )` open file-show on the specified entry.

302 - `copyTextToClipboard(text: string)` self-explanatory.

303 - `urlParams: object` you'll find each parameter in the URL mapped in this object as string.

304 -- `fileShowComponents: { Video, Audio }` expose standard components used by file-show. Can be useful if you need extend them, inside `fileShow` event.

304 +- `fileShowComponents: { Video, Audio }` exposes standard components used by file-show. Can be useful if you need extend them, inside `fileShow` event.

305

306 The following properties are accessible only immediately at top-level; don't call it later in a callback.

307 - `getPluginConfig()` returns object of all config keys that are declared frontend-accessible by this plugin.

@@ -312,21 +312,19 @@ The following properties are accessible only immediately at top-level; don't cal

312 API at this level is done with frontend-events, that you can handle by calling

313

314 ```typescript

315 -HFS.onEvent(eventName, callback)

316 -

317 -//type callback = (parameters: object) => any

315 +HFS.onEvent(eventName: string, callback: (parameters: object) => any)

316 ```

317

318 Parameters of your callback and meaning of returned value varies with the event name.

319 Refer to the specific event for further information.

320 HFS object is the same you access globally. Here just for legacy, consider it deprecated.

321

324 -Some frontend-events can return Html, which can be expressed in several ways

325 -- as string, containing markup

326 -- as DOM Nodes, as for document.createElement()

327 -- as ReactElement

328 -- as array of ReactNode

329 -- null, undefined, false and empty-string will just be discarded

322 +Some frontend events can return HTML, which can be expressed in several ways:

323 +- as a string containing markup

324 +- as DOM Nodes, using methods like `document.createElement()`

325 +- as a ReactElement

326 +- as an array of ReactNode

327 +- `null`, `undefined`, `false`, and empty strings will be discarded

328

329 These events will receive a `def` property (in addition event's specific properties),

330 with the default content that will be displayed if no callback return a valid output.

@@ -560,7 +558,7 @@ The most prominent is the `ctx` object, short for "context".

558 To know what the Context object contains please refer to [Koa documentation](https://github.com/koajs/koa/blob/master/docs/api/context.md).

559

560 HFS adds a few useful properties in the `ctx.state` object. Some of it may turn to be useful,

563 -so we prepared this list as a quick reference, but beware that it may become out of date and needs double check.

561 +so we prepared this list as a quick reference, but beware that it may become out of date and needs a double check.

562 If so, please report, and we'll do our best to update it asap.

563 Where information is too little, you'll have to consult the source code, sorry.

564

@@ -627,8 +625,8 @@ Hint: if you go in your .hfs/plugins folder on linux and mac, and enter

625

626 ln -s /PATH_TO_YOUR_REPO/dist MY_PLUGIN_NAME

627

630 -you'll install your repo, so that you can edit the sources and see effects in real-time, and still be editing your repo,

631 -ready to commit.

628 +You'll install your repo so that you can edit the sources and see effects in real-time.

629 +This allows you to continue editing your repo and be ready to commit changes.

630

631 If you have platform-dependent files, you can put those files in `dist-PLATFORM` or `dist-PLATFORM-ARCHITECTURE`.

632 For example, if you want some files to be installed only on Windows with Intel CPUs, put them in `dist-win32-x64`.

doc: better english