Skip to content

Fields

Jump to bottom
Mike Medley edited this page May 20, 2023 · 45 revisions

About Fields

Each type of field that GM_config supports allows a different type of value to be saved using the GUI.

Common field properties

  1. All fields have default values that will be used if you don't include a "default" property with your field definition.

  2. All fields can optionally have a label element that can be set using a "label" property that can be either a string or a DOM element. If the "label" property is listed first in the field definition, it will appear to the left of the field, otherwise it will appear to the right. Sometimes this can get annoying so you can use a "labelPos" property with a value of either "left", "right", "above", or "below" to control the position of the label in relation to the field.

  3. All fields can have a "title" property that will show the text as a tooltip when hovering over the field.

text, int, float

Each of these field types (text, int, float) use an input element with a type of "text". The difference is that GM_config enforces that "int" and "float" fields actually conform to those datatypes, and prevents the user from entering invalid data. Both "int" and "float" types can be prefixed with "unsigned" to ensure the value entered is non-negative.

text

The default value for the "text" field type is an empty string.

let gmc = new GM_config(
{
  'id': 'MyConfig', // The id used for this instance of GM_config
  'fields': // Fields object
  {
    'Name':
    {
      'label': 'Name', // Appears next to field
      'type': 'text', // Makes this setting a text input
      'title': 'Give us your name!', // Add a tooltip (hover over text)
      'size': 100, // Limit length of input (default is 25)
      'default': 'Sizzle McTwizzle' // Default value if user doesn't change it
    }
  }
});

int

The default value for the "int" field type is zero.

let gmc = new GM_config(
{
  'id': 'MyConfig', // The id used for this instance of GM_config
  'fields': // Fields object
  {
    'Age':
    {
      'label': 'Age', // Appears next to field
      'type': 'int', // Makes this setting a text input
      'min': 13, // Optional lower range limit
      'max': 122, // Optional upper range limit
      'default': 20 // Default value if user doesn't change it
    }
  }
});

float

The default value for the "float" field type is zero.

let gmc = new GM_config(
{
  'id': 'MyConfig', // The id used for this instance of GM_config
  'fields': // Fields object
  {
    'Income':
    {
      'label': 'Income', // Appears next to field
      'type': 'unsigned float', // Makes this setting a text input
      'default': 0 // Default value if user doesn't change it
    }
  }
});

checkbox

This type of field is stored as a boolean value and is displayed as an input element with a type of "checkbox". The default is false.

let gmc = new GM_config(
{
  'id': 'MyConfig', // The id used for this instance of GM_config
  'fields': // Fields object
  {
    'Status':
    {
      'label': 'Married', // Appears next to field
      'type': 'checkbox', // Makes this setting a checkbox input
      'default': false // Default value if user doesn't change it
    }
  }
});

select

This type of field is stored as a string and displayed using a dropdown box (a select element with child option elements). The default value is the first option provided in the field definition.

let gmc = new GM_config(
{
  'id': 'MyConfig', // The id used for this instance of GM_config
  'fields': // Fields object
  {
    'Work':
    {
      'label': 'Job', // Appears next to field
      'type': 'select', // Makes this setting a dropdown
      'options': ['Carpenter', 'Truck Driver', 'Porn Star'], // Possible choices
      'default': 'Truck Driver' // Default value if user doesn't change it
    }
  }
});

radio

This type of field is stored as a string and displayed using a series of radio elements. The default value is the first option provided in the field definition.

let gmc = new GM_config(
{
  'id': 'MyConfig', // The id used for this instance of GM_config
  'fields': // Fields object
  {
    'Gender':
    {
      'label': 'Gender', // Appears next to field
      'type': 'radio', // Makes this setting a series of radio elements
      'options': ['Male', 'Female'], // Possible choices
      'default': 'Male' // Default value if user doesn't change it
    }
  }
});

Using the above code, the "Male" and "Female" labels will appear to the right of the radio elements. If you want them to appear to the left, you must provide the options property first:

...
    'Gender':
    {
      'options': ['Male', 'Female'], // Possible choices
      'label': 'Gender', // Appears next to field
      ...

Alternatively, you can use a "labelPos" property to set the radio labels to the "left" or "right" of the radio element.

textarea

This type of field uses a textarea element and its default value is an empty string. Be careful when using this field type because all settings are converted to a JSON string when saved, so too much text entered in this field might cause a slow-down when reading and saving values. Also, when localStorage is used, there is a size limit on the amount of data that can be stored. I recommend adding an onchanged listener to this field to enforce a maximum length of input (or making this an unsaved field and storing the value separately).

let gmc = new GM_config(
{
  'id': 'MyConfig', // The id used for this instance of GM_config
  'fields': // Fields object
  {
    'bunchOtext':
    {
      'label': 'Bunch of Text',
      'type': 'textarea',
      'default': 'Enter some text here...'
    }
  }
});

hidden

This field is stored as a string, will not be seen by the user, and uses an input element with a type of "hidden". The default value is an empty string. There is no label for this field.

let gmc = new GM_config(
{
  'id': 'MyConfig', // The id used for this instance of GM_config
  'fields': // Fields object
  {
    'Secret':
    {
      'type': 'hidden', // Makes this setting a hidden input
      'value': 'Some hidden value' // Value stored
    }
  }
});

button

This field is used to create a clickable button and uses an input element with a type of "button". There is no value stored for this field.

let gmc = new GM_config(
{
  'id': 'MyConfig', // The id used for this instance of GM_config
  'fields': // Fields object
  {
    'Button':
    {
      'label': 'Click me!', // Appears on the button
      'type': 'button', // Makes this setting a button input
      'size': 100, // Control the size of the button (default is 25)
      'click': function() { // Function to call when button is clicked
        alert('Button clicked!');
      }
    }
  }
});

Sections

The GM_config panel can optionally be divided into sections. Simply add a "section" property (which can be a string or a DOM element) to any field and it, and any fields following it, will be placed into a new section. Each section has a header, and for convenience, each section is put in a dedicated block element (some people have used this to make sections collapsible). The section property can take a one or a two element array (or just a single string or DOM element), in which the first element will be used as the heading and the second element will be used as a subheading.

let gmc = new GM_config(
{
  'id': 'MyConfig', // The id used for this instance of GM_config
  'fields': // Fields object
  {
    'Name':
    {
      'label': 'Name', // Appears next to field
      'section': ['Personal Info About Yourself', 
        'We need this info to do stuff'], // Appears above the field
      'type': 'text', // Makes this setting a text input
      'title': 'Give us your name!', // Add a tooltip (hover over text)
      'size': 100, // Limit length of input (default is 25)
      'default': 'Sizzle McTwizzle' // Default value if user doesn't change it
    }
  }
});

Advance Field Usage

The above documentation gives you the basics of how to use the field types provided by GM_config. For more advanced field usage, see this page.

Home | FAQ

Clone this wiki locally