366 lines
8.7 KiB
Markdown
366 lines
8.7 KiB
Markdown
---
|
|
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, [text-button fields](#text-button-field) may be more appropriate for your use case.
|
|
```
|
|
|
|
#### 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.
|
|
```
|
|
|
|
### Text input field
|
|
|
|
Text input fields let you get text input for more complex needs. They are defined like so:
|
|
|
|
```js
|
|
{
|
|
type: "text-input",
|
|
text: "Description",
|
|
initialValue: () => "Initial value",
|
|
oninput: (value, element) => {
|
|
// Do something.
|
|
}
|
|
}
|
|
```
|
|
|
|
### 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
|
|
`element` can be a DOM element or a function that will be called and expected to return the element.
|
|
```
|
|
|
|
```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.
|
|
```
|