mirror of
https://github.com/NovaGM/Documentation.git
synced 2024-08-14 23:53:01 +00:00
Added module settings documentation
This commit is contained in:
parent
8244822884
commit
bc733236aa
2 changed files with 323 additions and 0 deletions
5
module-development/README.md
Normal file
5
module-development/README.md
Normal file
|
@ -0,0 +1,5 @@
|
||||||
|
# Module Development
|
||||||
|
|
||||||
|
Documentation for GooseMod module developpers
|
||||||
|
|
||||||
|
{% include list.liquid all=true %}
|
318
module-development/settings.md
Normal file
318
module-development/settings.md
Normal file
|
@ -0,0 +1,318 @@
|
||||||
|
---
|
||||||
|
title: Module Settings
|
||||||
|
sort: 2
|
||||||
|
---
|
||||||
|
|
||||||
|
# Adding settings to your module
|
||||||
|
|
||||||
|
## Accessing the GooseMod settings interface
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
## Adding a new settings page
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Do remember to remove the settings pages you add when your module gets disabled
|
||||||
|
though.
|
||||||
|
|
||||||
|
First import `createItem`:
|
||||||
|
```js
|
||||||
|
import { createItem } from '@goosemod/settings';
|
||||||
|
```
|
||||||
|
|
||||||
|
Then in your module's `onLoadingFinished`, call to `createItem` like this:
|
||||||
|
```js
|
||||||
|
createItem("Page name", [
|
||||||
|
"version",
|
||||||
|
// field objects
|
||||||
|
]);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Removing a settings page
|
||||||
|
|
||||||
|
When your module is disabled, it should undo all modifications made, to
|
||||||
|
restore the state of Discord prior to when it was enabled.
|
||||||
|
|
||||||
|
[Adding a settings page](#adding-a-new-settings-page) was easy enough, but
|
||||||
|
removing one is even easier.
|
||||||
|
|
||||||
|
First add `removeItem` to your imports from `@goosemod/settings`:
|
||||||
|
```js
|
||||||
|
import { createItem, removeItem } from '@goosemod/settings';
|
||||||
|
```
|
||||||
|
|
||||||
|
Then in your module's `onRemove`, call to `removeItem` like so:
|
||||||
|
```js
|
||||||
|
removeItem("Page name");
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
## Types of settings fields
|
||||||
|
|
||||||
|
Settings fields are objects, each having a `type` property defining its type,
|
||||||
|
a `text` property defining the field's text.
|
||||||
|
|
||||||
|
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:
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
// field definition elements
|
||||||
|
subtext: "subtext goes there",
|
||||||
|
// other field definition elements
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Divider field
|
||||||
|
|
||||||
|
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:
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
type: "divider"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```note
|
||||||
|
Divider fields **do not** use the `subtext` property. However they have a
|
||||||
|
`text` property.
|
||||||
|
```
|
||||||
|
|
||||||
|
```warning
|
||||||
|
The divider field's `text` property has not yet been experimented with
|
||||||
|
and documented.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Header field
|
||||||
|
|
||||||
|
Header fields let you make categories in your settings page, they are defined
|
||||||
|
like so:
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
type: "header",
|
||||||
|
text: "Header text"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```note
|
||||||
|
Header fields do not use the `subtext` property.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Text field
|
||||||
|
|
||||||
|
Text fields let you write text without user controls, they are defined like so:
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
type: "text",
|
||||||
|
text: "Write your text here"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Button field
|
||||||
|
|
||||||
|
Button fields let you add simple buttons to launch actions, they are defined
|
||||||
|
like so:
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
type: "button",
|
||||||
|
text: "Action",
|
||||||
|
onclick: () => {
|
||||||
|
// Do something.
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```note
|
||||||
|
Buttons do not use the `subtext` property.
|
||||||
|
```
|
||||||
|
|
||||||
|
```note
|
||||||
|
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.
|
||||||
|
```
|
||||||
|
|
||||||
|
```tip
|
||||||
|
Given that button fields are so bare, I'd recommend using
|
||||||
|
[text-button fields](#text-button-field) in most cases.
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Text-Button field
|
||||||
|
|
||||||
|
A regular [text field](#text-field) with a smaller [button](#button-field).
|
||||||
|
They are defined like so:
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
type: "text-and-button",
|
||||||
|
text: "Description",
|
||||||
|
buttonText: "Action",
|
||||||
|
onclick: () => {
|
||||||
|
// Do something.
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```note
|
||||||
|
Unlike [button fields](#button-field), text-button fields include a
|
||||||
|
[divider field](#divider-field), so you don't need to add one after.
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Text-Button-Danger field
|
||||||
|
|
||||||
|
Exactly like the [text-button field](#text-button-field), but the button has
|
||||||
|
the danger styling (red). They are defined like so:
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
type: "text-and-danger-button",
|
||||||
|
text: "Description",
|
||||||
|
buttonText: "Action",
|
||||||
|
onclick: () => {
|
||||||
|
// Do something.
|
||||||
|
}
|
||||||
|
},
|
||||||
|
```
|
||||||
|
|
||||||
|
```note
|
||||||
|
Due to the design language surrounding them, you should only use these if the
|
||||||
|
action could have impactful consequences.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Toggle field
|
||||||
|
|
||||||
|
Toggle fields let you make on/off switches for your basic settings, they are
|
||||||
|
defined like so:
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
type: "toggle",
|
||||||
|
text: "Description",
|
||||||
|
onToggle: value => {
|
||||||
|
// Do something with value (true/false).
|
||||||
|
},
|
||||||
|
isToggled: () => {
|
||||||
|
// Define what state the toggle switch should be in when loading the page.
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Toggle-Text-Button field
|
||||||
|
|
||||||
|
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:
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
type: "toggle-text-button",
|
||||||
|
text: "Description",
|
||||||
|
onToggle: value => {
|
||||||
|
// Do something with value (true/false)
|
||||||
|
},
|
||||||
|
isToggled: () => {
|
||||||
|
// Define what state the toggle switch should be in when loading the page.
|
||||||
|
return false;
|
||||||
|
},
|
||||||
|
buttonText: "Action",
|
||||||
|
onclick: () => {
|
||||||
|
// Do something
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Toggle-Text-Button-Danger
|
||||||
|
|
||||||
|
Exactly like the [toggle-text-button field](#toggle-text-button-field), but
|
||||||
|
the button has the danger styling (red). They are defined like so:
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
type: "toggle-text-danger-button",
|
||||||
|
text: "Description",
|
||||||
|
onToggle: value => {
|
||||||
|
// Do something with value (true/false)
|
||||||
|
},
|
||||||
|
isToggled: () => {
|
||||||
|
// Define what state the toggle switch should be in when loading the page.
|
||||||
|
return false;
|
||||||
|
},
|
||||||
|
buttonText: "Action",
|
||||||
|
onclick: () => {
|
||||||
|
// Do something
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```note
|
||||||
|
Due to the design language surrounding them, you should only use these if the
|
||||||
|
action could have impactful consequences.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Colour field
|
||||||
|
|
||||||
|
Colour fields let you make colour pickers for your settings, they are defined
|
||||||
|
like so:
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
type: "text-and-color",
|
||||||
|
text: "Description",
|
||||||
|
oninput: value => {
|
||||||
|
// Do something with value.
|
||||||
|
},
|
||||||
|
initialValue: () => {
|
||||||
|
// Define what colour should be displayed when loading the page.
|
||||||
|
return "#00000";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```note
|
||||||
|
The colour picker doesn't support alpha channel (opacity) yet.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Card field
|
||||||
|
|
||||||
|
```warning
|
||||||
|
Not yet experimented with or duocumented.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Search field
|
||||||
|
|
||||||
|
```warning
|
||||||
|
Not yet experimented with or duocumented.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sidebar field
|
||||||
|
|
||||||
|
```warning
|
||||||
|
Not yet experimented with or duocumented.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Custom field
|
||||||
|
|
||||||
|
Custom fields only support a single property: `element`. They are defined like
|
||||||
|
so:
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
type: "custom",
|
||||||
|
element: (() => {
|
||||||
|
// Return a DOM element
|
||||||
|
let e = document.createElement("span");
|
||||||
|
e.innerText = "Custom Element";
|
||||||
|
return e;
|
||||||
|
})()
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```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/KeanuGooseMod/Modules/blob/master/settings-experiment/custom-settings.js#L1-L57).
|
||||||
|
```
|
Loading…
Reference in a new issue