tools
/
kconfig
1
0
Fork 0
Code Issues Pull Requests Projects Releases 3 Wiki Activity
kconfig/README.md

18 KiB
Raw Blame History

KConfig

a json config visualizer

Schema

JSON Schema Support

JSON Editor fully supports version 3 and 4 of the JSON Schema core and validation specifications. Some of The hyper-schema specification is supported as well.

$ref and definitions

JSON Editor supports schema references to external URLs and local definitions. Here's an example showing both:

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Full Name",
      "$ref": "#/definitions/name"
    },
    "location": {
      "$ref": "http://mydomain.com/geo.json"
    }
  },
  "definitions": {
    "name": {
      "type": "string",
      "minLength": 5
    }
  }
}

Local references must point to the definitions object of the root node of the schema. So, #/customkey/name will throw an exception.

If loading an external url via Ajax, the url must either be on the same domain or return the correct HTTP cross domain headers. If your URLs don't meet this requirement, you can pass in the references to JSON Editor during initialization (see Usage section above).

Self-referential $refs are supported. Check out examples/recursive.html for usage examples.

hyper-schema links

The links keyword from the hyper-schema specification can be used to add links to related documents.

JSON Editor will use the mediaType property of the links to determine how best to display them. Image, audio, and video links will display the media inline as well as providing a text link.

Here are a couple examples:

Simple text link

{
  "title": "Blog Post Id",
  "type": "integer",
  "links": [
    {
      "rel": "comments",
      "href": "/posts/{{self}}/comments/",
      // Optional - set CSS classes for the link
      "class": "comment-link open-in-modal primary-text"
    }
  ]
}

Make link download when clicked

{
  "title": "Document filename",
  "type": "string",
  "links": [
    {
      "rel": "Download File",
      "href": "/documents/{{self}}",
      // Can also set `download` to a string as per the HTML5 spec
      "download": true
    }
  ]
}

Show a video preview (using HTML5 video)

{
  "title": "Video filename",
  "type": "string",
  "links": [
    {
      "href": "/videos/{{self}}.mp4",
      "mediaType": "video/mp4"
    }
  ]
}

The href property is a template that gets re-evaluated every time the value changes. The variable self is always available. Look at the Dependencies section below for how to include other fields or use a custom template engine.

Property Ordering

There is no way to specify property ordering in JSON Schema (although this may change in v5 of the spec).

JSON Editor introduces a new keyword propertyOrder for this purpose. The default property order if unspecified is 1000. Properties with the same order will use normal JSON key ordering.

{
  "type": "object",
  "properties": {
    "prop1": {
      "type": "string"
    },
    "prop2": {
      "type": "string",
      "propertyOrder": 10
    },
    "prop3": {
      "type": "string",
      "propertyOrder": 1001
    },
    "prop4": {
      "type": "string",
      "propertyOrder": 1
    }
  }
}

In the above example schema, prop1 does not have an order specified, so it will default to 1000. So, the final order of properties in the form (and in returned JSON data) will be:

  1. prop4 (order 1)
  2. prop2 (order 10)
  3. prop1 (order 1000)
  4. prop3 (order 1001)

Default Properties

The default behavior of JSON Editor is to include all object properties defined with the properties keyword.

To override this behaviour, you can use the keyword defaultProperties to set which ones are included:

{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "age": {"type": "integer"}
  },
  "defaultProperties": ["name"]
}

Now, only the name property above will be included by default. You can use the "Object Properties" button to add the "age" property back in.

format

JSON Editor supports many different formats for schemas of type string. They will work with schemas of type integer and number as well, but some formats may produce weird results. If the enum property is specified, format will be ignored.

JSON Editor uses HTML5 input types, so some of these may render as basic text input in older browsers:

  • color
  • date
  • datetime-local
  • email
  • month
  • password
  • number
  • range
  • tel
  • text
  • textarea
  • time
  • url
  • week

Here is an example that will show a color picker in browsers that support it:

{
  "type": "object",
  "properties": {
    "color": {
      "type": "string",
      "format": "color"
    }
  }
}

String Editors Input Attributes

You can set custom attributes such as placeholder, class and data- on the input field using the special options keyword inputAttributes.

Like this:

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Full Name",
      "options": {
        "inputAttributes": {
          "placeholder":  "your name here...",
          "class": "myclass"
        }
      }
    }
  }
}

Specialized String Editors

Ace Editor is a syntax highlighting source code editor. You can use it by setting the format to any of the following:

  • actionscript
  • batchfile
  • c
  • c++
  • cpp (alias for c++)
  • coffee
  • csharp
  • css
  • dart
  • django
  • ejs
  • erlang
  • golang
  • groovy
  • handlebars
  • haskell
  • haxe
  • html
  • ini
  • jade
  • java
  • javascript
  • json
  • less
  • lisp
  • lua
  • makefile
  • markdown
  • matlab
  • mysql
  • objectivec
  • pascal
  • perl
  • pgsql
  • php
  • python
  • r
  • ruby
  • sass
  • scala
  • scss
  • smarty
  • sql
  • stylus
  • svg
  • twig
  • vbscript
  • xml
  • yaml
{
  "type": "string",
  "format": "yaml"
}

You can use the hyper-schema keyword media instead of format too if you prefer for formats with a mime type:

{
  "type": "string",
  "media": {
    "type": "text/html"
  }
}

You can enable Ace editor options individually by setting the options.ace in schema.

{
  "type": "string",
  "format": "sql",
  "options": {
    "ace": {
      "theme": "ace/theme/vibrant_ink",
      "tabSize": 2,
      "useSoftTabs": true,
      "wrap": true
    }
  }
}

Booleans

The default boolean editor is a select box with options "true" and "false". To use a checkbox instead, set the format to checkbox.

{
  "type": "boolean",
  "format": "checkbox"
}

Arrays

The default array editor takes up a lot of screen real estate. The table and tabs formats provide more compact UIs for editing arrays.

The table format works great when every array element has the same schema and is not too complex.

The tabs format can handle any array, but only shows one array element at a time. It has tabs on the left for switching between items.

The tabs-top format place tabs on the top.

Here's an example of the table format:

{
  "type": "array",
  "format": "table",
  "items": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      }
    }
  }
}

For arrays of enumerated strings, you can also use the select or checkbox format. These formats require a very specific schema to work:

{
  "type": "array",
  "uniqueItems": true,
  "items": {
    "type": "string",
    "enum": ["value1","value2"]
  }
}

By default, the checkbox editor (multiple checkboxes) will be used if there are fewer than 8 enum options. Otherwise, the select editor (a multiselect box) will be used.

You can override this default by passing in a format:

{
  "type": "array",
  "format": "select",
  "uniqueItems": true,
  "items": {
    "type": "string",
    "enum": ["value1","value2"]
  }
}

Objects

The default object layout is one child editor per row. The grid format will instead put multiple child editors per row. This can make the editor much more compact, but at a cost of not guaranteeing child editor order. This format will stretch columns to fill gaps untill all the 12 columns are filled.

{
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  },
  "format": "grid"
}

The grid-strict format instead will respect columns sizes (no stretching) and properties order. It introduces the new grid-break property to breaks the current row leaving a 4 colums gap.

{
  "type": "object",
  "format": "grid-strict",
  "properties": {
    "a": {
      "title": "a",
      "type": "string",
      "options": {
        "grid_columns": 4
      }
    },
    "b": {
      "title": "b",
      "type": "string",
      "options": {
        "grid_columns": 4,
        "grid_break": true
      }
    },
    "c": {
      "title": "c",
      "type": "string",
      "options": {
        "grid_columns": 6
      }
    },
    "d": {
      "title": "d",
      "type": "string",
      "options": {
        "grid_columns": 6
      }
    }
  }
}

The categories format groups properties in top-tabbed panels, one for each object or array property plus one that groups all added or other types of properties. Panel tabs titles came from object or array titles and for the grouping panel it defaults to "Basic", unless basicCategoryTitle is defined.

{
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  },
  "format": "categories",
  "basicCategoryTitle": "Main"
}

InfoText

Using the option infoText, will create a info button, displaying the text you set, on hovering.

{
  "type": "string",
  "title": "Name",
  "options": {
    "infoText": "Your full name"
  }
}

Dependencies

Sometimes, it's necessary to have one field's value depend on another's.

The dependency information is fetched from the dependencies field in the options field of the control. The dependencies field should be a map where the keys are the names of the fields depended on and the value is the expected value. The value may be an array to indicate multiple value possibilities. This uses the internal field value watch system to notify fields of changes in their dependencies.

Here's an example schema:

{
  "title": "An object",
  "type": "object",
  "properties": {
    "fieldOne": {
      "title": "I should be changed to 'foo'",
      "type": "string",
      "enum": ["foo","bar"],
      "default": "bar"
    },
    "depender1": {
      "title": "I depend on fieldOne to be 'foo'",
      "type": "string",
      "enum": ["lorem","ipsum"],
      "options": {
        "dependencies": {
          "fieldOne": "foo"
        }
      }
    },
    "depender2": {
      "title": "I depend on fieldOne to be 'bar'",
      "type": "string",
      "enum": ["dolor", "sit"],
      "options": {
        "dependencies": {
          "fieldOne": "bar"
        }
      }
    }
  }
}

The dependencies keyword from the JSON Schema specification is not nearly flexible enough to handle most use cases, so JSON Editor introduces a couple custom keywords that help in this regard.

The first step is to have a field "watch" other fields for changes.

{
  "type": "object",
  "properties": {
    "first_name": {
      "type": "string"
    },
    "last_name": {
      "type": "string"
    },
    "full_name": {
      "type": "string",
      "watch": {
        "fname": "first_name",
        "lname": "last_name"
      }
    }
  }
}

The keyword watch tells JSON Editor which fields to watch for changes.

The keys (fname and lname in this example) are alphanumeric aliases for the fields.

The values (first_name and last_name) are paths to the fields. To access nested properties of objects, use a dot for separation (e.g. "path.to.field").

By default paths are from the root of the schema, but you can make the paths relative to any ancestor node with a schema id defined as well. This is especially useful within arrays. Here's an example:

{
  "type": "array",
  "items": {
    "type": "object",
    "id": "arr_item",
    "properties": {
      "first_name": {
        "type": "string"
      },
      "last_name": {
        "type": "string"
      },
      "full_name": {
        "type": "string",
        "watch": {
          "fname": "arr_item.first_name",
          "lname": "arr_item.last_name"
        }
      }
    }
  }
}

Now, the full_name field in each array element will watch the first_name and last_name fields within the same array element.

Templates

Watching fields by itself doesn't do anything. For the example above, you need to tell JSON Editor that full_name should be fname [space] lname. JSON Editor uses a javascript template engine to accomplish this. A barebones template engine is included by default (simple {{variable}} replacement only), but many of the most popular template engines are also supported:

Here is the completed full_name example using the default barebones template engine:

{
  "type": "object",
  "properties": {
    "first_name": {
      "type": "string"
    },
    "last_name": {
      "type": "string"
    },
    "full_name": {
      "type": "string",
      "template": "{{fname}} {{lname}}",
      "watch": {
        "fname": "first_name",
        "lname": "last_name"
      }
    }
  }
}

Enum Values

Another common dependency is a drop down menu whose possible values depend on other fields. Here's an example:

{
  "type": "object",
  "properties": {
    "possible_colors": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "primary_color": {
      "type": "string"
    }
  }
}

Let's say you want to force primary_color to be one of colors in the possible_colors array. First, we must tell the primary_color field to watch the possible_colors array.

{
  "primary_color": {
    "type": "string",
    "watch": {
      "colors": "possible_colors"
    }
  }
}

Then, we use the special keyword enumSource to tell JSON Editor that we want to use this field to populate a drop down.

{
  "primary_color": {
    "type": "string",
    "watch": {
      "colors": "possible_colors"
    },
    "enumSource": "colors"
  }
}

Now, anytime the possible_colors array changes, the dropdown's values will be changed as well.

This is the most basic usage of enumSource. The more verbose form of this property supports filtering, pulling from multiple sources, constant values, etc.. Here's a more complex example (this uses the Swig template engine syntax to show some advanced features)

{
  // An array of sources
  "enumSource": [
    // Constant values
    ["none"],
    {
      // A watched field source
      "source": "colors",
      // Use a subset of the array
      "slice": [2,5],
      // Filter items with a template (if this renders to an empty string, it won't be included)
      "filter": "{% if item !== 'black' %}1{% endif %}",
      // Specify the display text for the enum option
      "title": "{{item|upper}}",
      // Specify the value property for the enum option
      "value": "{{item|trim}}"
    },
    // Another constant value at the end of the list
    ["transparent"]
  ]
}

You can also specify a list of static items with a slightly different syntax:

{
  "enumSource": [{
      // A watched field source
      "source": [
        {
          "value": 1,
          "title": "One"
        },
        {
          "value": 2,
          "title": "Two"
        }
      ],
      "title": "{{item.title}}",
      "value": "{{item.value}}"
    }]
  ]
}

The colors examples used an array of strings directly. Using the verbose form, you can also make it work with an array of objects. Here's an example:

{
  "type": "object",
  "properties": {
    "possible_colors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          }
        }
      }
    },
    "primary_color": {
      "type": "string",
      "watch": {
        "colors": "possible_colors"
      },
      "enumSource": [{
        "source": "colors",
        "value": "{{item.text}}"
      }]
    }
  }
}

All of the optional templates in the verbose form have the properties item and i passed into them. item refers to the array element. i is the zero-based index.

Sorting

To sort the dynamic EnumSource, you can set the EnumSource property sort to either asc or desc.

Dynamic Headers

The title keyword of a schema is used to add user friendly headers to the editing UI. Sometimes though, dynamic headers, which change based on other fields, are helpful.

Consider the example of an array of children. Without dynamic headers, the UI for the array elements would show Child 1, Child 2, etc.. It would be much nicer if the headers could be dynamic and incorporate information about the children, such as 1 - John (age 9), 2 - Sarah (age 11).

To accomplish this, use the headerTemplate property. All of the watched variables are passed into this template, along with the static title title (e.g. "Child"), the 0-based index i0 (e.g. "0" and "1"), the 1-based index i1, and the field's value self (e.g. {"name": "John", "age": 9}).

{
  "type": "array",
  "title": "Children",
  "items": {
    "type": "object",
    "title": "Child",
    "headerTemplate": "{{ i1 }} - {{ self.name }} (age {{ self.age }})",
    "properties": {
      "name": { "type": "string" },
      "age": { "type": "integer" }
    }
  }
}