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

787 lines
18 KiB
Markdown
Raw Blame History

# KConfig
a json config visualizer
## Usage
```shell
Usage: kconfig [options]
-addr string
address to listen (default ":8000")
-dev
turn on dev mode
-f string
file to use as schema, if will watch file change every 120ms
-level int
log level [-1(trace):5(panic)] 7 to disable (default 1)
-name string
name of the app (default "kconfig")
-pretty
log message in human readable format (the original log is json)
```
### Example
`kconfig -addr 127.0.0.1:8000 -pretty -level 0 -f dist/test.jcs`
## Schema
JSON Schema Support
-----------------
JSON Editor fully supports version 3 and 4 of the JSON Schema [core][core] and [validation][validation] specifications.
Some of The [hyper-schema][hyper] specification is supported as well.
[core]: http://json-schema.org/latest/json-schema-core.html
[validation]: http://json-schema.org/latest/json-schema-validation.html
[hyper]: http://json-schema.org/latest/json-schema-hypermedia.html
### $ref and definitions
JSON Editor supports schema references to external URLs and local definitions. Here's an example showing both:
```json
{
"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
```js+jinja
{
"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
```js+jinja
{
"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)
```js+jinja
{
"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.
```json
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"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
```json
{
"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:
```json
{
"type": "string",
"media": {
"type": "text/html"
}
}
```
You can enable [Ace editor options](https://github.com/ajaxorg/ace/wiki/Configuring-Ace) individually by setting the `options.ace` in schema.
```json
{
"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`.
```json
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{
"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:
```json
{
"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.
```json
{
"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:
```json
{
"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:
```js+jinja
{
"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:
```json
{
"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.
```json
{
"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.
```json
{
"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)
```js+jinja
{
// 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:
```js+jinja
{
"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:
```js+jinja
{
"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}`).
```js+jinja
{
"type": "array",
"title": "Children",
"items": {
"type": "object",
"title": "Child",
"headerTemplate": "{{ i1 }} - {{ self.name }} (age {{ self.age }})",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer" }
}
}
}
```
Reference in New Issue View Git Blame Copy Permalink