Skip to content

Commit c6914d5

Browse files
jjw24jjw24
authored
Merge pull request #77 from Yusyuriv/main
Add information about SettingsTemplate.yaml
2 parents cfcc3eb + 6b523ff commit c6914d5

File tree

3 files changed

+169
-0
lines changed

3 files changed

+169
-0
lines changed

‎_sidebar.md

+1
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
- [**Testing Guide**](/testing.md)
2525
- JSONRPC
2626
- [**JSON RPC Introduction**](/json-rpc.md)
27+
- [**JSON RPC Plugin Settings**](/json-rpc-settings.md)
2728
- Porting Plugins
2829
- [**Porting Plugins Guide**](/port-plugins.md)
2930
- [**How To Create A Theme**](/how-to-create-a-theme.md)

‎index.html

+1
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@
4545
<script src="//cdn.jsdelivr.net/npm/docsify-pagination/dist/docsify-pagination.min.js"></script>
4646
<script src="//unpkg.com/docsify-count/dist/countable.js"></script>
4747
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-csharp.min.js"></script>
48+
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>
4849
<script
4950
src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@3/dist/docsify-themeable/main.min.js"
5051
type="text/javascript">

‎json-rpc-settings.md

+167
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
## Plugin Settings
2+
3+
You might need to have some settings in your plugins that are easily changeable by users. Inputs for JSON RPC plugin settings are defined in the file called `SettingsTemplate.yaml` in the root of your plugin directory.
4+
5+
6+
### SettingsTemplate.yaml
7+
This is a YAML files that contains the settings page layout for your plugin. It contains an object with a single property called `body`. The `body` property contains an array of objects that define the layout of the settings page. Each object in the `body` array is a section of the settings page. Each section takes up the entire width of the page, which means you can't have one input on the left and one on the right. The layout of each section is always static: input description on the left, input on the right. Every object in the `body` array has the same structure: a `type` property that defines the type of this input (text input, textarea etc.), and an `attributes` property that contains everything else the object needs to render, such as label, description, or default value. The following is a list of the different types of inputs that can be used in the `SettingsTemplate.yaml` file.
8+
9+
---
10+
11+
#### `textBlock`
12+
This is a block of text with no input. Can't be edited by users, used only to display text.
13+
```yaml
14+
type: textBlock
15+
attributes:
16+
description: This is a block of text.
17+
```
18+
| Property name | Property description |
19+
|---------------|----------------------|
20+
| `description` | The text to display. |
21+
22+
#### `input`
23+
This is a simple text input.
24+
```yaml
25+
type: input
26+
attributes:
27+
name: inputName
28+
label: This is a text input
29+
description: Description of the input
30+
defaultValue: Hello there
31+
```
32+
| Property name | Property description |
33+
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
34+
| `name` | The name of the input. This is the key that you will use to access the value of the input in the settings object. |
35+
| `label` | The label for the input. If set, it's displayed to the left of the input. |
36+
| `description` | The description for the input. If set, it's displayed to the left of the input, right below the label. |
37+
| `defaultValue` | The default value for the input. It's the value your plugin will receive in the settings for that input until the user changes that value in settings. |
38+
39+
#### `inputWithFileBtn`
40+
This is a text input with a "Browse" button for selecting a file.
41+
```yaml
42+
type: inputWithFileBtn
43+
attributes:
44+
name: file
45+
label: This is a text input with a Browse button
46+
description: Description of the input
47+
defaultValue: Hello there
48+
```
49+
| Property name | Property description |
50+
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
51+
| `name` | The name of the input. This is the key that you will use to access the value of the input in the settings object. |
52+
| `label` | The label for the input. If set, it's displayed to the left of the input. |
53+
| `description` | The description for the input. If set, it's displayed to the left of the input, right below the label. |
54+
| `defaultValue` | The default value for the input. It's the value your plugin will receive in the settings for that input until the user changes that value in settings. |
55+
56+
#### `textarea`
57+
This is a multiline text input.
58+
59+
```yaml
60+
type: textarea
61+
attributes:
62+
name: multilineString
63+
label: This is a multiline text input
64+
description: Description of the input
65+
defaultValue: Hello there
66+
```
67+
| Property name | Property description |
68+
|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
69+
| `name` | The name of the input. This is the key that you will use to access the value of the input in the settings object. |
70+
| `label` | The label for the input. If set, it's displayed to the left of the input. |
71+
| `description` | The description for the input. If set, it's displayed to the left of the input, right below the label. |
72+
| `defaultValue` | The default value for the input. It the value your plugin will receive in the settings for that input until the user changes that value in settings. |
73+
74+
#### `passwordBox`
75+
This is a password input. The user will see dots instead of the actual characters they type.
76+
```yaml
77+
type: passwordBox
78+
attributes:
79+
name: password
80+
label: This is a password input
81+
description: Description of the input
82+
defaultValue: secret password
83+
```
84+
| Property name | Property description |
85+
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
86+
| `name` | The name of the input. This is the key that you will use to access the value of the input in the settings object. |
87+
| `label` | The label for the input. If set, it's displayed to the left of the input. |
88+
| `description` | The description for the input. If set, it's displayed to the left of the input, right below the label. |
89+
| `defaultValue` | The default value for the input. It's the value your plugin will receive in the settings for that input until the user changes that value in settings. |
90+
91+
#### `dropdown`
92+
This is a dropdown input. The user can select one of the predefined options.
93+
```yaml
94+
type: dropdown
95+
attributes:
96+
name: dropdownValue
97+
label: This is a dropdown input
98+
description: Description of the input
99+
defaultValue: Option 1
100+
options:
101+
- Option 1
102+
- Option 2
103+
- Option 3
104+
```
105+
| Property name | Property description |
106+
|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
107+
| `name` | The name of the input. This is the key that you will use to access the value of the input in the settings object. |
108+
| `label` | The label for the input. If set, it's displayed to the left of the input. |
109+
| `description` | The description for the input. If set, it's displayed to the left of the input, right below the label. |
110+
| `options` | An array of strings. Each string is an option that the user can select. |
111+
| `defaultValue` | The default value for the input. It's the value your plugin will receive in the settings for that input until the user changes that value in settings. If set, this must match one of the values in the `options` property. |
112+
113+
#### `checkbox`
114+
This is a simple checkbox.
115+
```yaml
116+
type: checkbox
117+
attributes:
118+
name: checkboxValue
119+
label: This is a checkbox
120+
description: Description of the checkbox
121+
defaultValue: true
122+
```
123+
| Property name | Property description |
124+
|----------------|-------------------------------------------------------------------------------------------------------------------------|
125+
| `name` | The name of the checkbox. This is the key that you will use to access the value of the checkbox in the settings object. |
126+
| `label` | The label for the checkbox. If set, it's displayed to the left of the checkbox. |
127+
| `description` | The description for the checkbox. If set, it's displayed to the left of the checkbox, right below the label. |
128+
| `defaultValue` | The default value for the checkbox. Can be either `true` or `false`. |
129+
130+
131+
### Example `SettingsTemplate.yaml` file
132+
```yaml
133+
body:
134+
- type: textBlock
135+
attributes:
136+
description: Welcome to the settings page for my plugin. Here you can configure the plugin to your liking.
137+
- type: input
138+
attributes:
139+
name: userName
140+
label: How should I call you?
141+
defaultValue: the user
142+
- type: textarea
143+
attributes:
144+
name: prependResult
145+
label: Text to prepend to result output
146+
description: >
147+
This text will be added to the beginning of the result output. For example, if you set this to
148+
"The result is: ", and the result is "42", the output will be "The result is: 42".
149+
- type: dropdown
150+
attributes:
151+
name: programmingLanguage
152+
label: Programming language to prefer for answers
153+
defaultValue: TypeScript
154+
options:
155+
- JavaScript
156+
- TypeScript
157+
- Python
158+
- "C#"
159+
- type: checkbox
160+
attributes:
161+
name: Prefer shorter answers
162+
description: If checked, the plugin will try to give answer much shorter than the usual ones.
163+
defaultValue: false
164+
```
165+
166+
### Visual editor for `SettingsTemplate.yaml`
167+
You can use a [visual editor](https://flow-launcher-plugin-settings-generator.pages.dev/) for creating the `SettingsTemplate.yaml` file. When you're done editing, click the `Generate SettingsTemplate.yaml` file and copy-paste its contents into your `SettingsTemplate.yaml` file. Optionally, you can also copy the generated typings for your settings object in your preferred programming language.

0 commit comments

Comments
 (0)