You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+186-8Lines changed: 186 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,20 +1,30 @@
1
1
# TinyWebEx AutomaticSettings
2
2
3
-
A simple module that allows you to specify your add-on settings in HTML-only, so you can focus on adding settings and not care about how to load and save them.
4
-
It is also designed to be used with settings pages that save their settings automatically. There is no need for an "OK" button or so. However, it is flexible enough to allow you to not use this feature.
3
+
A simple module that allows you to specify your add-on settings in HTML-only, so you can focus on adding settings and not care about how to load and save them. This means you do not have to write any custom JavaScript!
4
+
It is also designed to be used with settings pages that save their settings automatically. There is no need for an "OK" button or similar confirmation after the user entered the data.
5
+
6
+
## Features
7
+
* supports ["managed options"](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/storage/managed), i.e. loads options from the managed storage and marks them as "unchangable", i.e. disabled.
8
+
* can automatically load all options into your HTML
9
+
* can automatically save all options in a useful data format (number values are also saved as numbers, not strings)
10
+
*[saving multiple options grouped together in JS objects](#option-groups)
11
+
*[MessageHandler integration](https://github.com/TinyWebEx/MessageHandler), e.g. to show errors when saving or loading an option fails, or to show a message if some managed options are used.
12
+
*[can automatically let your reset button spring to live](#reset-button)
5
13
6
14
## Usage
7
15
8
16
It mostly just works with some additions to your HTML code. The HTML code itself can be quite flexible then:
9
17
10
-
*`class="setting"` attached to an `input` HTML tag enables handling of this setting. It is thus required.
11
-
* The name (`name="greatSettingsNum"`) must be properly specified and is used.
12
-
* Add a class via `class="save-on-change"` if the setting should be automatically saved when it is ["changed"/updated]().
13
-
* Otherwise add `class="save-on-input"` if the setting should be automatically saved when it the [input event]() is triggered. This is e.g. useful when the simple change of an element is not enough to trigger a save. See the examples below on where that may be useful.
18
+
*`class="setting"` attached to an `input` HTML tag enables the loading of this setting. It is thus required.
19
+
* The [name attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#name) (e.g. `name="greatSettingsNum"`) must be properly specified and is used for saving the option in the `sync` storage.
20
+
* Add a class via `class="save-on-change"` if the setting should be automatically saved when it is [changed](https://developer.mozilla.org/docs/Web/Events/change).
21
+
* Otherwise add `class="save-on-input"` if the setting should be automatically saved when it the [input event](https://developer.mozilla.org/docs/Web/Events/input) is triggered. This is e.g. useful when the simple change of an element is not enough to trigger a save. See the examples below on where that may be useful.
22
+
* You can optionally bind to different evens and validate entered data or overwrite loading and saving procedures via JavaScript.
23
+
* Note that input fields that are disabled are never saved and their input/update events are ignored. Managed options are set to this disabled state, so that these are ignored.
14
24
15
25
## Examples
16
26
17
-
Obviously the examples below are minimal examples. Please anyway use proper HTML markup with `label` and such things. This has just nothing to do with this add-on. :)
27
+
Obviously the examples below are minimal examples. Please anyway use proper HTML markup with `label` and so on. You can add almost any elements anywhere. This has just nothing to do with this add-on. 🙂
18
28
19
29
### Checkbox
20
30
@@ -32,7 +42,175 @@ This e.g. changes a numeric value setting as `greatSettingsNum`:
* add `data-type="radiogroup"` to mark the container of the radio options as a radiogroup.
86
+
* if you use a `fieldset` you can bind the save trigger to this fieldset as shown above, or to each individual `input type="radio"`. It's just easy to forget one element if you specify it individually, that's why the behaviour shown above is recommended.
87
+
* Note, however, that it is always required to add the `setting` class to the container (i.e. `fieldset`), to enable the loading of this setting. Note that this is _not_ required for the indidual options.
88
+
It can be useful, however, to prevent multiple triggers, if you e.g. have other options inside of the fieldset. These are e.g. also automatically triggered when a chield input is triggered, so this can lead to it being saved multiple times. This usually is not a (noteworthy) problem, but you can see it in the console log messages.
89
+
90
+
## Option groups
91
+
92
+
A usual use case is to save multiple options in a JavaScript object, i.e. something like this:
93
+
```js
94
+
groupName = {
95
+
size:170,
96
+
sizeType:"auto",
97
+
ignoreUserSize:true
98
+
};
99
+
```
100
+
101
+
This is natively supported by this add-on. Just add an attribute `data-optiongroup="groupName"` to all the options that you want to have grouped in an object. This can e.g. be useful if you have a [radio group](#radio-options) with sub-options that you want to have saved with the value of the radio buttons themselves.
102
+
For instance, the following HTML would result in the object shown above:
To enable this plugin, you still a few lines of JavaScript - respectively one line:
136
+
```js
137
+
AutomaticSettings.init();
138
+
```
139
+
140
+
This does load the options and registers bindings etc.
141
+
142
+
Obviously you need to pay attention to the fact to only do this after the DOM has been loaded, i.e. [the script should be deferred](https://developer.mozilla.org/docs/Web/HTML/Element/script#attr-defer).
143
+
144
+
## Trigger
145
+
146
+
You can additionally intercept loading and saving some settings or check the validity or similar things of some settings via JavaScript. This is all done via `AutomaticSettings.Trigger`.
147
+
In most cases, you always pass the registration functions the name of the option to be saved as a string and the function that you want to register as a callback. Most triggers are valid for a single option, whose name you specify, in order to prevent that
148
+
You can register as many triggers, as you want.
149
+
150
+
Generally, it is recommend to register all triggers _before_ calling the [`init` method](#loading-the-settings) of this module, but it also works to register triggers at any time.
151
+
152
+
### Update & Change trigger
153
+
154
+
You can use `AutomaticSettings.Trigger.registerUpdate` or `AutomaticSettings.Trigger.registerChange` to register a custom callback that is executed when the user updates (triggered by [input](https://developer.mozilla.org/docs/Web/Events/input)) or [changes](https://developer.mozilla.org/docs/Web/Events/change) an input option.
155
+
156
+
In both cases, you get the `optionValue` of the setting, the option name and the original event that triggered the request, so you can also find out the HTML element.
157
+
158
+
This is mostly useful if some options depend on each other (that happens often when using [option groups](#option-groups) e.g.), so you can interactively disable elements based on the user selection/input; or, if you want top verify the data the user entered and show some warnings or so.
159
+
160
+
Note however, that this way is separate from the whole loading & saving of the data, so you cannot prevent an invalid value from being saved or so, here. Do [overwrite the loading or saving behaviour](#overwriting-loading-and-saving-behaviour) if you want to do this.
161
+
162
+
Note that you need to add the additional classes `trigger-on-update` (for the update trigger/`registerUpdate`) or `trigger-on-change` (for the input trigger/`registerChange`) to the respective options, to make this feature work. Without it, the library does not bind to these elements.
163
+
164
+
### Save trigger
165
+
166
+
You can use `AutomaticSettings.Trigger.registerSave` to register a "save trigger" that is executed when an option is saved (actually directly before it is saved).
167
+
It is thus quite useful to automatically apply the option or send it to other parts of the browser extension, so they are notified that a the value of the option changed. This is a useful feature for your usability, because the `AutomaticSetings` module automatically saves all options, so they should also automatically be applied, so the user immediately sees the difference.
168
+
169
+
You can also use it to validate the input and cancel saving, you need to throw some errors then. Note that you should then show an appropriate error message yourself, as this error is not catched by the library - in contrast to everything else that happens afterwards, i.e. the saving of the option itself, e.g.
170
+
171
+
### Triggers before and after loading
172
+
173
+
When the triggers are used as expected, you usually get to one problem: Directly after your options have been loaded, you may see an inconsistent state, as your [save triggers](#save-trigger) did not yet run and no checks on the previously loaded data is done, etc.
174
+
175
+
To solve this, there is `AutomaticSettings.Trigger.registerAfterLoad`, which can be used to register a handler that is run after _all_ settings have been loaded. To make it easier to implement you can even pass it the special variable `AutomaticSettings.Trigger.RUN_ALL_SAVE_TRIGGER` that tells it to automatically execute all save triggers, you have registered. This is usually what you want. 🙂
176
+
177
+
Similarly there is `AutomaticSettings.Trigger.registerBeforeLoad` to let you execute stuff before any option is loaded.
178
+
179
+
### Overwriting loading and saving behavior
180
+
181
+
Sometimes it is needed to present data to the user in one way, but save it in another way. Thus, you need to manipulate how data is loaded or saved.
182
+
If [option groups](#option-groups) are not enough for you, you can use `AutomaticSettings.Trigger.addCustomLoadOverride` and `AutomaticSettings.Trigger.addCustomSaveOverride` to override the respective features.
183
+
184
+
As always in these triggers, you get some information about the option that is loaded/saved and can check that. However, in addition you can get the data returned by your [save trigger](#save-trigger) in `saveTriggerValues`, so you can re-use it.
185
+
186
+
In contrast to the [save triggers](#save-trigger) you can also actually influence/overwrite whether/how the value is loaded/saved. By default, the library assumes you now handle loading and saving by yourself, i.e. you need to interact with the HTML DOM (for loading) or the storage API (for saving) directly. By all means, you are overwriting the loading/saving process...
187
+
However, you can also return a special value that is returned by `AutomaticSettings.Trigger.overrideContinue` to indicate you want to continue saving/loading, but use different data for it, i.e. you just modify the data to load/save. You just pass it the value you want to continue the process.
188
+
189
+
In the end, it can e.g. look like this:
190
+
191
+
```js
192
+
/**
193
+
* Saves the option XY.
194
+
*
195
+
* @private
196
+
* @param{Object}param
197
+
* @param{Object}param.optionValue the value of the changed option
198
+
* @param{string}param.option the name of the option that has been changed
199
+
* @param{Array}param.saveTriggerValues all values returned by potentially
200
+
* previously run save triggers
201
+
* @returns{Promise}
202
+
*/
203
+
functionsaveOptionXy(param) {
204
+
// our proper data is saved in saveTriggerValues by previously run save trigger
* Load, save and apply options to HTML options page.
46
+
*
47
+
* @public
48
+
* @module AutomaticSettings
49
+
* @requires AutomaticSettings/Trigger
50
+
*/
51
+
52
+
// import and expose module parts
53
+
export { default as Trigger } from "./internal/Trigger.js";
54
+
export * from "./internal/LoadAndSave.js";
55
+
export { setDefaultOptionProvider } from "./internal/OptionsModel.js";
56
+
</code></pre>
57
+
</article>
58
+
</section>
59
+
60
+
61
+
62
+
63
+
64
+
65
+
</div>
66
+
67
+
<brclass="clear">
68
+
69
+
<footer>
70
+
Documentation generated by <ahref="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Sun Jan 20 2019 22:24:02 GMT+0100 (Mitteleuropäische Normalzeit) using the <ahref="https://github.com/clenemt/docdash">docdash</a> theme.
0 commit comments