sizzlemctwizzle / gm_config

A lightweight, reusable, cross-browser graphical settings framework for inclusion in user scripts.

For GM_config usage information, read the wiki.

Notice: You may be impacted by a recent change to how values are read from storage

See what GM_config can do with:

• a server side live example please visit the demo page.
• a client side live example please visit the GM_config Unit Test, install the user script, and refresh that same page. Check out the Userscript Beginners HOWTO if you are new to user scripts.

For TypeScript developers, types are available in the types/ directory. They can be included by adding the following like to a TypeScript file:

/// <reference path="local/path/to/types/directory" />

Demo:

gm_config's Issues

GM_config.onInit callback destruction

Using the "old method of initializing" GM_config.onInit callback gets destructed after first open. Successive reopens should be able to call this in some use cases.

I know it is possible to move everything to the .onOpen callback however it would be nice to contain it in the gmc object to follow OO programming instead of a stray function called function onInit() { /* do something */ };

e.g.

var gmc = new GM_configStruct();
gmc.id = "gmc114843";
...
gmc.onInit = function () {
  console.log('.onInit()');
}

console.log(gmc.onInit); // Returns string representation of the function

gmc.init(
  document.createElement("div"), // Embed in DOM
  "Some title",
  ".someCSS { display: none; }", // Custom CSS
  gmc.onInit, // Reference of function to execute
  {
    'someId': {
      "type": 'checkbox',
      "label": 'Tick me',
      "default": true
    }
  }
);
...
gmc.onOpen = function () {
  console.log(gmc.onInit); // Returns default instance instead of the above initialized e.g. function() {};
  gmc.onInit();
}

gmc.onSave = function () {
  let write, open;
...
  if (true) /* Some boolean test */
    write = open = true;
...
  if (open) { gmc.close(); gmc.open(); }
}

Please advise. :)

Open two config window at once on the same page

Since you can now open the config window in an element you should be able to have more than one on the same page. To facilitate this the GM_config instance should have an id property which it uses like a namespace for storing values and creating elements.

opening config

when I call the config to open using GM_config.open(); and load the page, I get the config window just fine.

However, I cannot get the config window to open using the Grease Monkey User Scripts Commands area.

The line I am using is:
GM_registerMenuCommand("config open test", GM_config.open);

I see the "config open test" in the menu, but clicking on it does nothing.

Using GM_config outside of iframe takes over my block level element

When passing a div as an argument to the init function, GMC takes over my block level element including the id attribute.

The reason why this is an issue is due to #4 being a non-issue.
When Save and Close are clicked by the user GMC obliterates the div completely.

Hover callback for fields

This is just an idea. I'm sure how much use it would be to have an attribute for fields called "hover" that would be a function called when ever a user hovered over a field. It could probably allow for fancier explaining of what a field does than what our current tooltips allow.

Again, it's just an idea and I'm not sure if it'd be entirely useful.

field type "int" allows multiple decimal points

I'm assuming from skimming over the current code that type int is supposed to be integers and type float is supposed to be decimals... if this is the case then int allows multiple decimal points. Also related negative values don't seem to be permitted either.

Give GMC an explicit FOSS license

I think it's about time GM_config was released under an explicit free and open source license. So far I'm thinking either some Creative Commons or BSD license. My goal would be to choose a license that allows anyone to use GMC in a script regardless of the license of that script. At the same time in order to use GMC they would have acknowledge the original contributors of GMC. Right now I'm leaning towards the 3-clause BSD license.

GM_config.open(); GM_config.close(); GM_config.open(); causes duplicate settings outside of iframe

...
GM_config.open();
GM_config.close();
GM_config.open();

causes duplicate settings outside of iframe.

Simplify Field Element Creation

The fields are really similar so we don't need all that duplicated code in every switch case. Plus that section of code is huge and cryptic.

GitHub Documentation

I definitely think there needs to be some GitHub documetation for GM_config. So far the majority of features are largely undocumented and several things have changed over time.

Currently the most documentation we have is the stuff I wrote on the group page, but that just covers the most basic usage. There is a guide but it only does a little explaining(most of which is out of date) and then sort of goes off on a tangent and talks about a bunch of extensions to GM_config the author wrote which is just overwhelming.

There is currently no source of comprehensive documentation. I've decided that github pages would be a good idea so people can easily contribute to it.

NFR: Ability to reverse form elements and span elements on create

New Feature Request

In order to facilitate left aligned fields with proper text wrapping I need the ability to reverse these two DOM elements... however reversing them permanently will produce an improper form element wrap on the default right aligned form elements.

My thought is to modify toNode to be a little more logical on determining the order of initialization. e.g.

'someId': {
  "label": 'someLabel',
  "type": 'someType',
  "default": someDefault
}

this would produce the default span element first then the form element in the DOM whereas

'someId': {
  "type": 'someType',
  "default": someDefault,
  "label": 'someLabel'
}

would produce the form element first then the span element in the DOM

There may be a default CSS float property to be considered as well.

This is one option that I can think of to indicate the "flag" to switch the two around... .if label gets parsed first then that means right aligned form elements if not then left aligned form elements.

See also potential alternative at #24

field position error

my config

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                                                             
    }                                                                           
})

output: http://i.imgur.com/4BSsk.png

As you can see, Name field and 'Joe Simmons' are mispositioned.

I use github version.

Uncaught TypeError: Cannot call method 'search' of undefined

Hello.
I'm getting that error in console every time I press "Save" button on the settings form.

Setting are being saved. But that error is annoying.

I'm using tampermonkey, googlchrome and jquery.

Make save button only save

Could GMC put in an Apply button that doesn't close the iframe nor the DOM block level object and just commits the values.

This should alleviate any issues when placing GMC in a DOM block level element.

Project icon

I'm thinking that GMC could use a project icon for referencing it on script homepages instead of just plain text.

It has been suggested that the script icon with a gear superimposed on it is suitable.

I rather like this suggestion :)

Restore to default is misleading

Restore to defaults sounds incorrect... wouldn't it be something like reset to defaults or load defaults?

Ordered field type

Add a new field type for a user orderable list. JSON for this field:

someList: {
  label: "This is a list of things that you can order",
  type: "ordered",
  values: ["my", "name", "is", "sizzle"]
}

The default ordering would be the order they were passed to GM_config.init.

This would be a select element with the "multiple" attribute set to true. There would be an up and down arrow that the user can use to move the selected element up and down in the select element.

Since the script author could add or remove values, reading saved values could be complicated.

README.md points to invalid url

README points to invalid url so recommend pointing it back to GH wiki

Save

Save seems to do nothing when clicked when passing an element to use instead of an iframe.

Tested versions are this commit and forward.

Mozilla/5.0 (X11; U; Linux i686 (x86_64); en-US; rv:1.9.2.6) Gecko/20100625 Firefox/3.6.6
Mozilla/5.0 (X11; U; Linux i686 (x86_64); en-US; rv:1.9.2.8) Gecko/20100722 Firefox/3.6.8

Open confing frame in div

Hello.
I can't find any decent documentation.

I want to open my confing form in div.

myConfig = new GM_configStruct()
myConfig.init($("div.content-mid"), "Ustawienia skryptu \"Bloodwars Tools by Hooch\"", {
    "loginAuto" : {
        "label" : "sfsdf",
        "type" : "checkbox",
        "default" : false
    //(...) rest of elements
});

But config sill opens in iframe.
myConfig.open();

Second thing:
I pass to init this element:
"msgFightHiddenMode" : {
"label" : "sdfsdfi",
"type" : "select",
"options" : ["A", "B"],
"default" : "A"
}

What if I want to change order of A and B ?
The I have to change in code every place where I'm using it.

    if(myConfig.get("msgFightHiddenMode") == 1) {
        battleDesc.hide();
    }

I have to change all 1's to 0's and vice versa.

Implement Fields As Objects

Introduced fields as a separate class with methods of their own. I think this change makes the code much easier to comprehend.

Label-less fields

Currently the only way to have a field without a label is to use an empty string. If there is no label property in the field definition then no label element should be created.

I've got an idea of using this in combination with #16 and #51.

Strict mode fixes

Current upstream has some strict mode warnings.

Commit will come shortly

More CSS standardization and cleanup:

Previous CSS commit of e54424e was incomplete and needs a little more attention for the time being.

1. Basic CSS needs newline for DOM consistency so that appended selectors (rules) don't use the same last old to new first line in the style tag
2. Standardize on previous white space
3. Minimize HEX constants

NFR: link field type

New Feature Request

Make a link field that I can move around... may be related to #21

Uncaught TypeError: Cannot call method 'log' of undefined

Hello.
Even when I create empty project I'm getting that error.

// ==UserScript==
// @name Test
// @Version 0.1
// @include http:///
// @require https://raw.github.com/sizzlemctwizzle/GM_config/master/gm_config.js
// ==/UserScript==

alert("test");

That script works only if i remove require metadata.

NFR: textContent vs innerHTML

New Feature Request

Is it possible to use another attribute such as innerHTML for certain field types as well as the title field without burning the building down? I'd like to put some content in by default for the title and maybe eventually a few links spread throughout the text.

Full JSON initialization of GM_config

We probably should have done this from the beginning since trying to identify arguments to init is messy and a pain. From now on you will be able to pass a single JSON argument that initializes everything. To provide full backwards compatibility you MUST set the "id" property. We will preform a typeof arguments[0].id == "string" to identify when to use the new initialization method. Even if someone has a field called "id" its type will be "object". There will probably have to be an additional check to make sure it isn't a DOM element (since those have and id prop too). Here is an example of how the new initialization will look:

GM_config.init(
{
  'id': 'GM_config',
  'title': 'Script Settings',
  'fields': 
    {
      'Name':
      {
        'label': 'Name',
        'type': 'text',
        'default': 'Sizzle McTwizzle'
      }
    },
  'css': '#GM_config_section_0 { display: none !important; }',
  'frame': someElement,
  'events':
    {
      init: function() { alert('onInit()'); },
      open: function() { alert('onOpen()'); },
      save: function() { alert('onSave()'); },
      close: function() { alert('onClose()'); },
      reset: function() { alert('onReset()'); }
    }
});

Once this change has been made, this is the type of initialization that will be documented in the wiki. I'm not big on version numbers in this project, but I see everything after making GM_config object oriented as version 2 and after this change I see it as version 3. So I've added a new milestone to this issues, along with a few other issues I would like to see in version 3 of GM_config.

Update Element Creation Function

Use create function from here that doesn't require a separate nested array.

NFR: plain label field type

fields are what I have been referring to as "entities"... first off each "field" is encapsulated in another top level element... no problems here (yet) but what if I want just a plain label (e.g. textNode or label element.)

The possible feature request, if it doesn't already exist, is I'd like to just put a "note" in every once in a while... in toolkit circles this is usually called a label... e.g. textNode || label element that has no form entry.

Custon css style for cointainer

Hello.
I know how to pass custom css to init function.
I am not using iframe. I'am using div that is on page.

GM_confing is adding custom syle attribute to that div. How can I edit that style property?

style="position: fixed; z-index: 999; width: 75%; height: 75%; max-height: 95%; max-width: 95%; border-top-width: 1px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px; border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-top-color: rgb(0, 0, 0); border-right-color: rgb(0, 0, 0); border-bottom-color: rgb(0, 0, 0); border-left-color: rgb(0, 0, 0); border-image: initial; overflow-x: auto; overflow-y: auto; bottom: auto; right: auto; margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; top: 281px; left: 201px; opacity: 1; display: block; "

Restore to default

Restore to default seem to do nothing when clicked when passing an element to use instead of an iframe.

Tested versions are this commit and forward.

Mozilla/5.0 (X11; U; Linux i686 (x86_64); en-US; rv:1.9.2.6) Gecko/20100625 Firefox/3.6.6

Custom Field Types

As a very advance feature, users will be able to implement custom field types. They provide a default value for the type along with three functions (toNode, toValue, reset) that allows GM_config to handle the custom type. These custom functions will actually replace the default functions on field objects of this type (which will give them the scope to do all sorts of interesting shit). Implementation of this feature directly requires the implementation of #53.

GM_config.init(
{
  'id': 'GM_config',
  'fields': 
    {
      'SomeField':
      {
        // All these properties are passed to the custom functions
        'type': 'someType'
        'someProp': 'What ever'
      }
    },
  'types':
    {
      'someType': {
        'default': 'Some default value for this type',
        toNode: function() { 
          // toNode is expected to return a DOM element
          // it also needs to store a reference to the element on this.node
        },
        toValue: function() { 
          // toValue is expected to return a string value
          // or null if this.node is null
        },
        reset: function() { 
          // reset is expected to reset the field to its default value
          // or do nothing if this.node is null
        }
      }
    }
});

"Magic button" Failure?

Well I'm finally getting around to testing out this portion of GMC... and I'm not really sure how this was designed initially but in your GMC Unit Test the Magic button fails to alert "hey!"

Target init code:

...
    'magic': {
        'label': 'Magic Button',
        'type': 'button',
        'script': function() { alert('hey!'); }
    },
...

I've narrowed it down to this line. Neither conditional appears to work. I did a simple test to see if it was GMs alert sandbox issue and it doesn't appear to be.

Since I haven't actually used this portion of GMC before I'm not sure if a recommended fix below will work, which scope is needed and how much backwards compatibility is needed.

At first glance it would appear that this code:

typeof scr == 'function' ? setTimeout(scr, 0) : eval(scr);

would seem to need to be:

typeof scr == 'function' ? scr() : eval(scr);

... but I don't know since I can't seem to find this input type in the documentation anywhere. Even looking at Joes branch code he has the same line as this one. Izzys docs don't appear to have a reference either.

Ideally I am not sure that GMC would want to support something other than an actual Function Object... e.g. don't allow the first string of code parameter for setTimeout and most definitely do the best to avoid using eval. e.g. that line should probably become:

if (typeof scr == 'function') scr();

What sort of future does this feature hold? It would nice to keep some sort of functionality in but it would appear that a change needs to be done for it to work. I can think of many ways to implement this.

Please advise. :)

Mozilla/5.0 (X11; Linux x86_64; rv:20.0) Gecko/20100101 Firefox/20.0
Greasemonkey 1.8.x
Well-used running profile

Method to add and remove fields during runtime

You can add and redefine fields in memory by calling init() multiple times (you can change anything else set in init the same way). You can also remove a field in memory by calling init() with that field set to null. Obviously, if you modify a field with the settings panel open and the user tries to save, it will lead to a null value being saved since the field in panel doesn't belong to the field in memory. To remedy this you can either close and reopen the panel (easiest) or remove the old field and replace it with the new one.

NFR: Have the ability to pass an argument to .open() to change insertion type

New Feature Request

This would probably only apply to the block level initialized GMC's... but perhaps have the ability to pass an argument to .open() that would allow the dialog to show in the iframe instead of the div...e.g. One page would have it embedded into an existing element... the other pages would be able to choose programatically to use the default block level element OR pick to show in an iframe via attaching to a button or some other element. Not sure if this is possible (already?).

select toolbox item doesn't reset to default value

Patch forthcoming

Why exactly is this toolbox item using numerical entities for the .value? In order to maintain current compatibility I would assume that it would need to stay this way but it may not be exactly the preferred implementation long term.

Fields which aren't saved

Basically the idea is that if have a "save" property with the value of false (the default is true obviously) then that field will be displayed in the config panel but not saved. You can still call toValue on the field object to get it's value while the window is open and the values of these fields will collectively send to the onSave callback.

I can already think of a use for this in combination with #16 that would allow a user to add options to the ordered list.

'select' settings are not persistent

When I first install a script with 'select' boxes, the saving settings work.
But if I EVER edit the script, they no longer are - it becomes impossible to configure a 'select' box. Even uninstalling the script does not solve the problem.
Happened not only in my script, but when editing the Unit Test occupation field - same results.
Why does this happen? Is/can there be a fix?

[Firefox 6.0.2, GM 0.9.10, @require raw js here]

Select field without a default causes a fatal error

http://userscripts.org/topics/127151#posts-498245

I've confirmed this using my unit test as well.

NFR: Allow nested object creation

New Feature Request

This is offered as a possible alternative to the issue #23 and goes along the lines of my thinking for #15 as well.

It would be helpful for coders to be able to control what happens with DOM creation.

An example init settings object could be this:

{
  {
    "checkBoxItem1": {
        "label": '',    // Would be nice to omit this line if possible.
        "type": 'checkbox',
        "default": true
    },
    "labelItem1": {
      "label": 'The actual text for item 1'
    }
  },
  {
    "checkBoxItem2": {
        "label": '',    // Would be nice to omit this line if possible.
        "type": 'checkbox',
        "default": true
    },
    "labelItem2": {
      "label": 'The actual text for item 2'
    }
  }
}

This would create the DOM something like this

...

<div class="config_var" title="">
  <span id="something1" class="something">
    <input type="checkbox" id="gmc_field_checkBoxItem1" value="true">
  </span>
  <span id="something2" class="something">
    <span id="gmc_labelItem1_field_label" class="field_label">The actual text for item 1</span>
  </span>
</div>
<div class="config_var" title="">
  <span id="something3" class="something">
    <input type="checkbox" id="gmc_field_checkBoxItem2" value="true">
  </span>
  <span id="something4" class="something">
    <span id="gmc_labelItem2_field_label" class="field_label">The actual text for item 2</span>
  </span>
</div>

...

This would create a third tier of object creation instead of the standard two... plus it could be backwards compatible perhaps.

Let me know what you think. :)

NFR: onReset callback

NFR: onReset callback

In order to facilitate another event handler of sorts it would be helpful to have a callback when the user clicks Reset to defaults. Most processing can be done in the onSave callback but with Count Issues when a user clicks Reset to defaults I can't trap that event easily and resize the textareas dynamically which is in line with how GMC shows the defaults.

Many thanks for the look.

Password field type

Add a field type for password input. Not sure this is great idea because of the false sense of security it could give someone.

Deleted Issue

Load stored values before init() is called

It might be necessary to access stored values before calling init() if the values determine what settings you send to init (like the language of the menu). Basically I'm thinking of calling read() in GM_configStruct and placing the result in a "stored" property, which would then be used in init().

Save and Close outside of iframe removes GM_config completely from the DOM

Save and Close buttons outside of iframe removes GM_config completely from the DOM.

Using this raw commit is this the desired behavior?

Warning: assignment to undeclared variable create

Warning: assignment to undeclared variable create
Source file: file:///~/.mozilla/firefox/seed.default/extensions/{e4a8a97b-f2ed-450b-b12d-ee082ba24781}/components/greasemonkey.js
Line: 1361

Tested against this commit with this installable version of installWith

Good luck on the line number ;) Ever so briefly browsing over the GMC source I see that it's actually part of the object so this would indicate you might be missing a this somewhere or a reference to GM_config... but that's just a guess. This may be a sign of a larger issue or maybe not. :)

Mozilla/5.0 (X11; U; Linux i686 (x86_64); en-US; rv:1.9.2.8) Gecko/20100722 Firefox/3.6.8

Use <label> encapsulation for radio groups and fix ordering of existing label

Similar to #37 this will allow clicking of the label entities to select in radio groups

patch forthcoming

Allow number fields to have a range.

Allow the developer to specify a min and max property. Both properties are optional.

node is undefined

Error: node is undefined
Source file: file:///~/.mozilla/firefox/seed.default/extensions/%7Be4a8a97b-f2ed-450b-b12d-ee082ba24781%7D/components/greasemonkey.js
Line: 950

Using this commit