Userscripts.org

This group is for people who want to join in the development/refinement of a lightweight and reusable graphical settings framework for inclusion in user scripts.

If you post in the forum, please let me know so that I can respond because otherwise it could be awhile before I notice a new post. You could also contact the other GM_config devs: JoeSimmons, IzzySoft, and Marti

@require

GM_config is available for @require usage. You can get the current source here.

Reporting Issues and Requesting Features

You can report issues and request new features for the GitHub hosted version on the issue tracker. If you are really motivated you can fork my repo, make changes yourself and send me a pull request. If you're looking for a changelog, commits pushed to the GitHub repo are automatically posted in this topic.

Using GM_config

The only real weakness in my opinion user script have is that because they are so simple it is difficult for a script writer to make their script easily customizable for users. Having variables at the top of your script that users can change is definitely the simplest for the developer, but actually pretty difficult for most users who have no knowledge of Javascript.

A graphical settings menu is the best option for the user, but often the script writer must reinvent the wheel. I've seen countless scripts where the developer wrote their menu from scratch for that particular script. When I got around to making my own menu I decided that if I was going to go through all that effort, I was going to make something easily reusable and after a lot of work by me and Joe, and input from Izzy, GM_config was born. It is actually compatible with all browsers that support user scripts(Firefox, Safari, Chrome, and Opera). If you want to use in cross-browser user scripts you have to include the code directly, otherwise you can just include it through @require(hosted at http://github.com/sizzlemctwizzle/GM_config/raw/master/gm_config.js).

Before you can get the settings GM_config has stored you must call GM_config.init and pass the JSON settings object, the title of your script, any css to customize the panel, and optional callback functions. These values can be passed in any order.

GM_config.init('Configurable Options Script' /* Script title */,
/* Settings object */ 
{
	'Name': // This would be accessed using GM_config.get('Name')
	{
		'label': 'Name', // Appears next to field
		'type': 'text', // Makes this setting a text field
		'default': 'Joe Simmons' // Default value if user doesn't change it
	}
});

A text field is just one type of setting supported. 'textarea', 'int', and 'float' are all types that are set up the same way as above. Here is an example of how 'checkbox' works:

GM_config.init('Configurable Options Script' /* Script title */,
/* Settings object */ 
{
	'Name': // This would be accessed using GM_config.get('Name')
	{
		'label': 'Name', // Appears next to field
		'type': 'text', // Makes this setting a text field
		'default': 'Joe Simmons' // Default value if user doesn't change it
	}, // You just add more fields on as you need them
	'Married': // This would be accessed using GM_config.get('Married')
	{
		'label': 'Married',
		'type': 'checkbox',
		'default': false // store a boolean
	}
});

With the 'radio', and 'select' types you pass the options for the user to select from.

GM_config.init('Configurable Options Script' /* Script title */,
/* Settings object */ 
{
	'Name': // This would be accessed using GM_config.get('Name')
	{
		'label': 'Name', // Appears next to field
		'type': 'text', // Makes this setting a text field
		'default': 'Joe Simmons' // Default value if user doesn't change it
	}, // You just add more fields on as you need them
	'Married': // This would be accessed using GM_config.get('Married')
	{
		'label': 'Married',
		'type': 'checkbox',
		'default': false // store a boolean
	},
        'Work': // This would be accessed using GM_config.get('Word')
	{
        	'label': 'Job',
        	'type': 'select', // A drop-down select type
        	'options': ['Carpenter', 'Truck Driver', 'Porn Star'], // List of possible options
        	'default': 'Truck Driver'
        }
	'gender': 
	{
        	'label': 'Gender',
        	'type': 'radio', // radio boxes that the user can select
        	'options': ['Male', 'Female'], // Possible options
        	'default': 'Male'
        },
});

To open the settings menu you must call GM_config.open(). How you do that is up to you. Those are the basics of using GM_config. There are a handful of other advance features which this expanded usage guide does a good job of explaining.

Screenshot

Code to produce above screenshot:

GM_config.init('Configurable Options Script', {
    'name': {
        'section': ['Personal Info About Yourself', 'We need this info to do stuff'],
        'label': 'Name',
        'type': 'text',
        'default': 'Joe Simmons'
    },
    'age': {
        'label': 'Age',
        'type': 'int',
        'default': 19
    },
    'gender': {
        'label': 'Gender',
        'type': 'radio',
        'options': ['Male', 'Female'],
        'default': 'Male'
    },
    'income': {
        'label': 'Income',
        'type': 'float',
        'default': 50000.0
    },
    'status': {
        'label': 'Married',
        'type': 'checkbox',
        'default': false
    },
    'work': {
        'label': 'Job',
        'type': 'select',
        'options': ['Carpenter', 'Truck Driver', 'Porn Star'],
        'default': 'Truck Driver'
    }
});

Project Status

GM_config is nearly two years old now. It is very stable and mostly fully developed. I think it works very well and I consider it to be almost complete. The actual interface(API) is basically frozen so you can likely be certain that future updates won't stop your script from working. Somethings I'd like to get done are:

• Put radio buttons in a ul/li list.
• Add an order-able list type field.
• Allow init() to be called more than once and just appending new settings.
• More complete documentation