settings.json API

Overview

The settings.json file can be in JSON format as well as JSON5. JSON5 is a newer implementation of JSON that allows comments, trailing commas, and some other great things.

settings.json Skeleton File

        
          {
  "fields": [

  ]
}

        
      

API

Discover the settings.json API. Only the settings that are included in this file are passed to the module.js script.

Fields

The settings.json has a single acceptable top-level field called fields, which is an array of objects that controls the acceptable inputs for each related setting.

These are the allowed fields of a settings.json field

• name <string> The name of the settings field
• default <?any> The default value of the field
• required <?boolean> If true the user will not be able to save the settings until this field has a value
• type <?string> Specify the type of the setting (string, number, boolean)
• min <?number> Minimum value for a number field or the minimum length of a string field
• max <?number> Maximum value for a number field or the maximum length of a string field

The only required field is name. Although type is not required, it is useful to set as it will automatically convert the user's settings to match the type. For example, if the type is number but a string is provided, the string will be converted to a number prior to being saved.

Note: type does not refer to the setting's related HTML tag. The HTML tag can be anything including input, textarea, or select.

        
          {
            "fields": [
              // A text field that is required
              {
                "name": "myText",
                "required": true
              },

              // A number field that is required and a default value, a min value, and a max value
              {
                "name": "myNumber",
                "required": true,
                "default": 1,
                "min": 1,
                "max": 10
              },

              // A number field that is required and a default value, a min value, and a max value
              {
                "name": "myTextArea",
                "required": true
              },
              {
                "name": "myCheck"
              },
              {
                "name": "mySelect",
                "required": true,
                "type": "number"
              }
            ]
          }