Developing widgets: Widget settings - Glitter/Glitter GitHub Wiki

Intro

When creating a widget that is supposed to be used multiple times, or shared with other people, it is often useful to provide configuration options so that it can be tweaked to their specific needs (think: providing Google Analytics key, a link to a YouTube video/profile, etc.).

Here is what that might look like:

Defining settings fields

Settings fields can be defined in the package.json file of your Glitter widget. Inside the "glitter" property, define a new property "settings" which is an array that accepts settings field objects.

{
  "glitter": {
    "title": "Example widget",
    


    "settings": [
      {
        "name": "firstName",
        "type": "text",
        "label": "First Name"
      },
      {
        "name": "lastName",
        "type": "text",
        "label": "Last Name"
      }
    ]
  },
}

You can see a minimal structure example above. For the full list of options, check below.

List of available field types

Type	Description
text	Text input field. Supports multiline input and different HTML5 input types

text field configuration

Property	Description	Accepted values	Default value	Required
name	Field identifier that you will use to refer to the field later in your code	string - any	N/A	Yes
label	Label for the field. Should be descriptive	string - any	N/A	Yes
description	Additional description of the field for providing context to the user	string - any	""	No
multiline	Whether to allow multiline (textarea) input	boolean - true, false	false	No
inputType	One of HTML5 input types	string - text, number, date, color...	text	No
size	Width of the field. Use smaller sizes for smaller expected inputs	string - small, medium, large	large	No
required	Used to make the field required for filling out before a widget instance can be added	boolean - true, false	false	No

Accessing widget settings from within your widget

It is recommended to wait for a GlitterReady event before initializing your widget, at which point you can access settings data from within your widget:

window.addEventListener('GlitterReady', e => {
  // Settings are now available under e.detail.settings 
  console.log(e.detail.settings);
  // Object
  //   age: "0"
  //   firstName: "Glitter"
});

Default widget boilerplate generated when creating new widgets already includes React/Vue examples.