Simple Tampermonkey script config library
This script should not be not be installed directly. It is a library for other scripts to include with the meta directive // @require https://update.greasyfork.org/scripts/470224/1456932/Tampermonkey%20Config.js
GM_configSimple config lib for Tampermonkey scripts. (Greasy Fork) (GitHub)
prop.input)prop.processor)prop.formatter)This library needs the following permissions to work:
// @grant GM_setValue // Save your config
// @grant GM_getValue // Get your config
// @grant GM_deleteValue // Automatically delete your config (Optional. If granted, this lib will delete user config that is equal to default value)
// @grant GM_registerMenuCommand // Register menu
// @grant GM_unregisterMenuCommand // Update menu
// @grant GM_addValueChangeListener // Listen for config changes
Delete the comment if you copied and pasted the code, or there might be errors. You may want to delete @grant none (if present). If you used window object in your script, try @grant unsafeWindow and then let window = unsafeWindow.
console.log(GM_config.version); // *Print version*
The first step is to define your config description, which is a dictionary and each of its key (apart from possible $default) represents the id of a config item.
$defaultBy using $default, you can easily create a lot of config items of the same type. If $default is not specified in config description, following values will be used to fill unspecified fields in a config item:
{ // Priority: Lowest
type: "string",
input: "prompt",
processor: "same",
formatter: "normal"
}
If you'd like to modify the default value, you may provide $default in your config description to override the above default values. e.g.:
const configDesc = {
"$default": { // Priority: Low
value: true,
input: "current",
processor: "not",
formatter: "boolean"
},
switch_true: {
name: "Switch true"
},
switch_false: {
name: "Switch false",
value: false // Priority: Highest
}
}
Usually, however, the following prop.type is the best choice to quickly set up similar config items, and $default is solely used for setting autoClose to false:
const configDesc = {
"$default": {
autoClose: false
},
// ...
}
prop.typeThe type of the config item, used for quickly setting up common properties. Currently supported types are:
#builtin_types = {
str: { // String
value: "",
input: "prompt",
processor: "same",
formatter: "normal",
},
bool: { // Boolean
value: false,
input: "current",
processor: "not",
formatter: "boolean",
},
int: { // Integer
value: 0,
input: "prompt",
processor: "int",
formatter: "normal",
},
float: { // Float
value: 0.0,
input: "prompt",
processor: "float",
formatter: "normal",
},
action: { // Action
value: null,
input: (prop, orig) => {...}, // Do not override. To setup callback(s), listen for this attribute's `get` events using `config.addEventListener`
processor: "same",
formatter: "name_only",
autoClose: true,
},
};
You may use it like this:
const configDesc = {
switch_true: {
name: "Switch true",
type: "bool" // Priority: High
},
switch_false: {
name: "Switch false",
type: "bool", // Priority: High
value: false // Priority: Highest
}
}
prop.nameThe display name of the config item. Expected type: string.
prop.valueThe default value of the config item, can be of any type. Note that you should consider its validity, because this lib will not check default value's validity for you.
prop.input
(prop, orig) => input
How to get user input. Expected a string (built-in input method) or a function (invoked when user clicks the menu item). It accepts the name of config item and returns user input. If not specified by both prop.input and $default.input, prompt will be used, i.e. ask for user input using prompt(). Note that "user input value" does not necessarily have to be actually input by user, it can be provided by script. (e.g. built-in input method current).
Built-in input methods:
prompt: Ask for user input using prompt() (default value)current: Current value will be used as user input (Usually used with prop.processor=not so as to create a switch, or with custom processor to create a generator)name_only: Only show the name of the config item (Used internally by action type)prop.processor
(input) => stored
How to process user input. Expected a string (built-in processor) or a function. It accepts user input and returns value to be stored. Throw error if user input is invalid. If not specified by both prop.formatter and $default.formatter, same will be used, i.e. return user input directly. A common use case is to convert user input to integers or floats.
Built-in processors:
same: Return user input directlynot: Invert boolean value (Usually used with prop.input=current so as to create a switch)int: Convert to integerint_range-min-max: Convert to integer in range [min, max]
-, because there might be errors.<min> and <max> can be any integer. Not provided inferred as no limit on that side.float: Convert to floatfloat_range-min-max: Convert to float in range [min, max]
-, because there might be errors.<min> and <max> can be any float. Not provided inferred as no limit on that side.prop.formatter
(name, value) => string
How to display the menu item. Expected a string (built-in formatter) or a function. It accepts the name of config item and its current value, and returns the text to be displayed on the menu. If not specified by both prop.formatter and $default.formatter, normal will be used.
Built-in formatters:
normal: Display in the format of name: valueboolean: Display method aimed for boolean values. true will be displayed as name: ✔, false will be displayed as name: ✘.Supports prop.accessKey, prop.autoClose, prop.title (Require TM >=4.20.0). If a function is provided, it will be called with argument prop, name and value, and the returned string will be passed to Tampermonkey. See Tampermonkey docs for details.
The priority of the properties is as follows (from highest to lowest):
type of the config item$default$defaultAfter defining your config description, you can register the menu item by constructing a GM_config instance. The constructor accepts the following two arguments:
configDesc: Your config descriptionoptions: Options (optional)
immediate: Whether to register the menu items immediately.
true, the menu item will be registered immediately. (default value)false, the user need to click "Show configuration" to register it.debug: Whether to enable debug mode. If set to true, debug information will be printed to console. Default value is false. (Can be modified by config.debug at any time)const config = new GM_config(configDesc, { immediate: false }); // *Register menu*
console.log(config.get("price")); // *You may now start using the config 🎉*
After registering the menu, you can get/set config by accessing the GM_config instance. e.g:
console.log(config.get("price")); // *Get config*
config.set("price", 100); // *Modify config* (The menu will be updated automatically)
Alternatively, operate on config.proxy to get/set config. e.g:
console.log(config.proxy.price); // *Get config*
config.proxy.price = 100; // *Modify config* (The menu will be updated automatically)
You can listen for config get/set by calling config.addEventListener(type, listener, options?):
config.addEventListener("set", (e) => {
console.log(e.detail); // *Config is modified*
});
config.addEventListener("get", (e) => {
console.log(e.detail); // *Config is accessed*
});
It should be noted that get event is only triggered when the config is accessed by the script in the current window, while set event is triggered when the config is modified by the script in any window. This feature of set makes multi-tab synchronization possible.
As you might have expected, you can remove the listener by calling config.removeEventListener(type, listener, options?). These two methods are identical to EventTarget.addEventListener and EventTarget.removeEventListener.
e.detail is a dictionary with the following properties:
prop: The id of the config item accessed/modified.before: The value of the config item before the operation.after: The value of the config item after the operation.remote: Indicating whether this modification is caused by other script instances. Always false for get event (cannot detect other instances' accesses).This feature is often used to update your script dynamically when config is modified. In this lib, auto-updating menu is implemented by this feature.
prop.name and current value to prop.input to get user inputprop.processor to get processed valueInstall below code as a script, and see how does it work:
// ==UserScript==
// @name Test Config
// @namespace http://tampermonkey.net/
// @version 1.0.1
// @description This is an example to demostrate the usage of greasyfork.org/scripts/470224.
// @author PRO
// @match https://greasyfork.org/*
// @icon https://greasyfork.org/vite/assets/blacklogo16-bc64b9f7.png
// @grant GM_setValue
// @grant GM_getValue
// @grant GM_registerMenuCommand
// @grant GM_unregisterMenuCommand
// @grant GM_addValueChangeListener
// @require https://update.greasyfork.org/scripts/470224/1456701/Tampermonkey%20Config.js
// @license gpl-3.0
// ==/UserScript==
(function() {
'use strict';
const configDesc = { // Config description
$default: {
autoClose: false
},
anyString: {
name: "Any String",
type: "str"
},
anyBoolean: {
name: "Any boolean",
type: "bool"
},
anyInteger:{
name: "Any integer",
type: "int"
},
anyFloat: {
name: "Any float",
type: "float"
},
someAction: {
name: "Some action",
title: "Click me!",
type: "action"
},
password: {
name: "Password", // Display name
value: "tmp", // Default value
input: "prompt", // How to get user input (Invoked when user clicks the menu command)
// Built-in values:
// "current": Current value will be passed to `processor` as user input (generator-like)
// "prompt": Use `prompt` to get user input (default value)
// <function>: Custom function to get user input, should return certain value to be processed by `processor`
// (prop, orig) => input
processor: (v) => {
if (v.length < 3) throw "Too short!";
return v;
}
//
},
enabled: {
name: "Enabled",
title: (prop, name, value) => value ? "Disable some feature" : "Enable some feature",
value: true,
// The following can be replaced by `type: "bool"`
input: "current",
processor: "not", // Process user inputs, throw error if invalid
// Built-in processors:
// "same": Return user input directly (default value)
// "not": Invert boolean value
// "int": Convert to integer
// "int_range-min-max": Convert to integer in range [min, max], raise error if invalid ("" for no limit)
// "float": Convert to float
// "float_range-min-max": Convert to float in range [min, max], raise error if invalid ("" for no limit)
// <function>: Custom function to process value
// (input) => stored
formatter: "boolean", // Format value to be displayed in menu command
// Built-in formatters:
// "normal": `${name}: ${value}`
// "boolean": `${name}: ${value ? "✔" : "✘"}`
// <function>: Custom function to format value
// (name, value) => string
},
val: {
name: "Positive float",
value: 11.4,
processor: "float_range-0-" // Convert to float in range [0, +∞)
}
}
const config = new GM_config(configDesc, { immediate: false, debug: true }); // Register menu commands
function someAction() {
console.log("Action is invoked!");
}
config.addEventListener("get", (e) => { // Listen to `get` events for `someAction`
if (e.detail.prop === "someAction") {
someAction();
}
});
config.addEventListener("set", (e) => { // Listen to config changes
console.log(e.detail);
});
window.setTimeout(() => { // Change config values, and menu commands will be updated automatically
config.proxy.val += 1; // Remember to validate the value before setting it
}, 5000);
})();
Alternatively, you can try out this lib in action with Greasy Fork Enhance.
This project is in early development, and the API may change in the future. If you have any suggestions or find any bugs, please feel free to open an issue or pull request.
