// 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}`).
