NovaGM/Documentation
1
0
Fork 0
mirror of https://github.com/NovaGM/Documentation.git synced 2024-08-14 23:53:01 +00:00
Code Issues Projects Releases Wiki Activity

Updated module settings for GMv8.5.0 amd GMv8.6.0

Browse source
This commit is contained in:
フズキ 2021-05-22 23:02:54 +02:00
parent 70bd71b4e2
commit 18cd7e1595
No known key found for this signature in database
GPG key ID: E06450E46F83376C
1 changed files with 107 additions and 71 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

178
module-development/settings.md
View file

@ -7,22 +7,15 @@ sort: 2
## Accessing the GooseMod settings interface ## Accessing the GooseMod settings interface
The GooseMod settings interface can be accessed in your modules by importing The GooseMod settings interface can be accessed in your modules by importing `@goosemod/settings`. You can extend Discord's settings with more categories, pages, and other elements by importing the right procedures.
`@goosemod/settings`. You can extend Discord's settings with more categories,
pages, and other elements by importing the right procedures.
## Adding a new settings page ## Adding a new settings page
When GooseMod loads all modules, it first creates a new category called When GooseMod loads all modules, it first creates a new category called `GooseMod Modules`, so that all modules thereafter add their settings under this category by default.
`GooseMod Modules`, so that all modules thereafter add their settings under
this category by default.
Adding your own settings page is pretty straightforward: once your module has Adding your own settings page is pretty straightforward: once your module has been completely loaded it will call its defined `onLoadingFinished` prodedure, all that's needed to add a page is call `createItem` from the settings import.
been completely loaded it will call its defined `onLoadingFinished` prodedure,
all that's needed to add a page is call `createItem` from the settings import.
Do remember to remove the settings pages you add when your module gets disabled Do remember to remove the settings pages you add when your module gets disabled though.
though.
First import `createItem`: First import `createItem`:
@ -41,11 +34,9 @@ createItem('Page name', [
## Removing a settings page ## Removing a settings page
When your module is disabled, it should undo all modifications made, to When your module is disabled, it should undo all modifications made, to restore the state of Discord prior to when it was enabled.
restore the state of Discord prior to when it was enabled.
[Adding a settings page](#adding-a-new-settings-page) was easy enough, but [Adding a settings page](#adding-a-new-settings-page) was easy enough, but removing one is even easier.
removing one is even easier.
First add `removeItem` to your imports from `@goosemod/settings`: First add `removeItem` to your imports from `@goosemod/settings`:
@ -61,12 +52,9 @@ removeItem('Page name');
## Types of settings fields ## Types of settings fields
Settings fields are objects, each having a `type` property defining its type, Settings fields are objects, each having a `type` property defining its type, a `text` property defining the field's text.
a `text` property defining the field's text.
Most fields also have a `subtext` property to add additional information if Most fields also have a `subtext` property to add additional information if needed, for example: precising the default values of your settings. The way you would define a fields subtext is like so:
needed, for example: precising the default values of your settings. The way
you would define a fields subtext is like so:
```js ```js
{ {
@ -78,8 +66,7 @@ you would define a fields subtext is like so:
### Divider field ### Divider field
A simple divider to separate your fields. Most other fields already add a A simple divider to separate your fields. Most other fields already add a divider, so needing one is a more specific use case. They are defined like so:
divider, so needing one is a more specific use case. They are defined like so:
```js ```js
{ {
@ -88,19 +75,16 @@ divider, so needing one is a more specific use case. They are defined like so:
``` ```
```note ```note
Divider fields **do not** use the `subtext` property. However they have a Divider fields **do not** use the `subtext` property. However they have a `text` property.
`text` property.
``` ```
```warning ```warning
The divider field's `text` property has not yet been experimented with The divider field's `text` property has not yet been experimented with and documented.
and documented.
``` ```
### Header field ### Header field
Header fields let you make categories in your settings page, they are defined Header fields let you make categories in your settings page, they are defined like so:
like so:
```js ```js
{ {
@ -126,8 +110,7 @@ Text fields let you write text without user controls, they are defined like so:
### Button field ### Button field
Button fields let you add simple buttons to launch actions, they are defined Button fields let you add simple buttons to launch actions, they are defined like so:
like so:
```js ```js
{ {
@ -144,15 +127,11 @@ Buttons do not use the `subtext` property.
``` ```
```note ```note
Button fields are pretty bare and only simple buttons. If you use them, you may Button fields are pretty bare and only simple buttons. If you use them, you may want to add a [text field](#text-field) before to explain their function and a [divider field](#divider-field) afterwards to properly separate them from the following fields.
want to add a [text field](#text-field) before to explain their function and a
[divider field](#divider-field) afterwards to properly separate them from the
following fields.
``` ```
```tip ```tip
Given that button fields are so bare, I'd recommend using Given that button fields are so bare, [text-button fields](#text-button-field) may be more appropriate for your use case.
[text-button fields](#text-button-field) in most cases.
``` ```
#### Text-Button field #### Text-Button field
@ -172,14 +151,12 @@ They are defined like so:
``` ```
```note ```note
Unlike [button fields](#button-field), text-button fields include a Unlike [button fields](#button-field), text-button fields include a [divider field](#divider-field), so you don't need to add one after.
[divider field](#divider-field), so you don't need to add one after.
``` ```
#### Text-Button-Danger field #### Text-Button-Danger field
Exactly like the [text-button field](#text-button-field), but the button has Exactly like the [text-button field](#text-button-field), but the button has the danger styling (red). They are defined like so:
the danger styling (red). They are defined like so:
```js ```js
{ {
@ -193,14 +170,12 @@ the danger styling (red). They are defined like so:
``` ```
```note ```note
Due to the design language surrounding them, you should only use these if the Due to the design language surrounding them, you should only use these if the action could have impactful consequences.
action could have impactful consequences.
``` ```
### Toggle field ### Toggle field
Toggle fields let you make on/off switches for your basic settings, they are Toggle fields let you make on/off switches for your basic settings, they are defined like so:
defined like so:
```js ```js
{ {
@ -218,9 +193,7 @@ defined like so:
#### Toggle-Text-Button field #### Toggle-Text-Button field
A [toggle field](#toggle-field) with a small [button](#button-field), or a A [toggle field](#toggle-field) with a small [button](#button-field), or a [text-button field](#text-button-field) with a [toggle switch](#toggle-field). They are defined like so:
[text-button field](#text-button-field) with a [toggle switch](#toggle-field).
They are defined like so:
```js ```js
{ {
@ -242,8 +215,7 @@ They are defined like so:
#### Toggle-Text-Button-Danger #### Toggle-Text-Button-Danger
Exactly like the [toggle-text-button field](#toggle-text-button-field), but Exactly like the [toggle-text-button field](#toggle-text-button-field), but the button has the danger styling (red). They are defined like so:
the button has the danger styling (red). They are defined like so:
```js ```js
{ {
@ -264,14 +236,12 @@ the button has the danger styling (red). They are defined like so:
``` ```
```note ```note
Due to the design language surrounding them, you should only use these if the Due to the design language surrounding them, you should only use these if the action could have impactful consequences.
action could have impactful consequences.
``` ```
### Colour field ### Colour field
Colour fields let you make colour pickers for your settings, they are defined Colour fields let you make colour pickers for your settings, they are defined like so:
like so:
```js ```js
{ {
@ -291,43 +261,109 @@ like so:
The colour picker doesn't support alpha channel (opacity) yet. The colour picker doesn't support alpha channel (opacity) yet.
``` ```
### Card field ### Text input field
```warning Text input fields let you get text input for more complex needs. They are defined like so:
Not yet experimented with or documented.
```js
{
type: "text-input",
text: "Description",
initialValue: () => "Initial value",
oninput: (value, element) => {
// Do something.
}
}
``` ```
### Search field
```warning ```warning
Not yet experimented with or documented. Not yet experimented with.
```
### Sidebar field
```warning
Not yet experimented with or documented.
``` ```
### Custom field ### Custom field
Custom fields only support a single property: `element`. They are defined like Custom fields only support a single property: `element`. They are defined like so:
so:
```js ```js
{ {
type: "custom", type: "custom",
element: (() => { element: () => {
// Return a DOM element // Return a DOM element
let e = document.createElement("span"); let e = document.createElement("span");
e.innerText = "Custom Element"; e.innerText = "Custom Element";
return e; return e;
})() }
} }
``` ```
```note ```note
Custom fields can be used to make any kind of field that is not built into `element` can be a DOM element or a function that will be called and expected to return the element.
GooseMod. For example, [here is a procedure building a text input field](https://github.com/NovaGM/Modules/blob/master/settings-experiment/custom-settings.js#L1).
``` ```
```note
Custom fields can be used to make any kind of field that is not built into GooseMod.
For example, [here is a procedure building a text input field](https://github.com/NovaGM/Modules/blob/master/comfy-theme/custom-settings.js#L1) made when there was no [text input field](#text-input) yet.
```
### Internal fields
These fields are used internally by GooseMod for specific uses. You may reuse them, but you'll want to do your own research and testing.
#### Card field
Can be seen in the module and theme stores, each entry has a card.
Defined [here](https://github.com/GooseMod/GooseMod/blob/master/src/ui/settings.js#L697-L1126).
```warning
Not yet experimented with or documented.
```
#### Search field
Can be seen in the module and theme stores.
Defined [here](https://github.com/GooseMod/GooseMod/blob/master/src/ui/settings.js#L1128-L1203).
```warning
Not yet experimented with or documented.
```
#### Sidebar field
Defined [here](https://github.com/GooseMod/GooseMod/blob/master/src/ui/settings.js#L1205-L1309).
```warning
Not yet experimented with or documented.
```
### Dropdown fields
#### Dropdown field
Dropdown field to offer multipple defined choices. Can be seen in the GooseMod settings page, to force select a language.
Defined [here](https://github.com/GooseMod/GooseMod/blob/master/src/ui/settings.js#L1450-L1520).
```warning
Not yet experimented with or documented.
```
#### Inline dropdown field
Dropdown field to offer multipple defined choices, designed to be used side by side. Can be seen in the module and theme stores.
Defined [here](https://github.com/GooseMod/GooseMod/blob/master/src/ui/settings.js#L1392-L1448).
```warning
Not yet experimented with or documented.
```
#### GM footer
Footer for the GooseMod settings page.
Defined [here](https://github.com/GooseMod/GooseMod/blob/master/src/ui/settings.js#L1321-L1390).
```note
Not intended for use in modules.
```