jsoneditor/docs/api.md

562 lines
18 KiB
Markdown
Raw Normal View History

2013-05-04 17:54:03 +08:00
# API Reference
## JSONEditor
### Constructor
2015-12-15 02:58:17 +08:00
#### `JSONEditor(container [, options [, json]])`
2013-05-04 17:54:03 +08:00
Constructs a new JSONEditor.
*Parameters:*
2016-01-12 20:16:13 +08:00
- `{Element} container`
2016-01-12 19:40:23 +08:00
2014-07-28 14:45:31 +08:00
An HTML DIV element. The JSONEditor will be created inside this container element.
2016-01-12 19:40:23 +08:00
- `{Object} options`
Optional object with options. The available options are described under
[Configuration options](#configuration-options).
- `{JSON} json`
2016-01-12 20:16:13 +08:00
2013-05-04 17:54:03 +08:00
Initial JSON data to be loaded into the JSONEditor. Alternatively, the method `JSONEditor.set(json)` can be used to load JSON data into the editor.
*Returns:*
2016-01-12 19:40:23 +08:00
- `{JSONEditor} editor`
2016-01-12 20:16:13 +08:00
2013-05-04 17:54:03 +08:00
New instance of a JSONEditor.
2016-01-12 19:40:23 +08:00
### Configuration options
- `{Object} ace`
Provide a custom version of the [Ace editor](http://ace.c9.io/) and use this instead of the version that comes embedded with JSONEditor. Only applicable when `mode` is `code`.
Note that when using the minimalist version of JSONEditor (which has Ace excluded), JSONEditor will try to load the Ace plugins `ace/mode/json` and `ace/ext/searchbox`. These plugins must be loaded beforehand or be available in the folder of the Ace editor.
2016-01-12 20:16:13 +08:00
- `{Object} ajv`
2016-01-12 19:40:23 +08:00
Provide a custom instance of [ajv](https://github.com/epoberezkin/ajv), the
library used for JSON schema validation. Example:
```js
var options = {
ajv: Ajv({ allErrors: true, verbose: true })
2016-01-12 19:40:23 +08:00
}
```
- `{function} onChange()`
2016-01-12 19:40:23 +08:00
Set a callback function triggered when the contents of the JSONEditor change.
This callback does not pass the changed contents, use `get()` or `getText()` for that.
Note that `get()` can throw an exception in mode `text` or `code`, when the editor contains invalid JSON.
Will only be triggered on changes made by the user, not in case of programmatic changes via the functions `set`, `setText`, `update`, or `updateText`.
See also callback functions `onChangeJSON(json)` and `onChangeText(jsonString)`.
2016-01-12 19:40:23 +08:00
- `{function} onChangeJSON(json)`
Set a callback function triggered when the contents of the JSONEditor change.
Passes the changed contents as a JSON object.
Only applicable when option `mode` is `tree`, `form`, or `view`.
The callback will only be triggered on changes made by the user, not in case of programmatic changes via the functions `set`, `setText`, `update`, or `updateText`.
See also callback function `onChangeText(jsonString)`.
- `{function} onChangeText(jsonString)`
Set a callback function triggered when the contents of the JSONEditor change.
Passes the changed contents as a stringified JSON object.
The callback will only be triggered on changes made by the user, not in case of programmatic changes via the functions `set`, `setText`, `update`, or `updateText`.
See also callback function `onChangeJSON(json)`.
- `{function} onEditable(node)`
2016-01-12 19:40:23 +08:00
2017-04-15 18:28:46 +08:00
Set a callback function to determine whether individual nodes are editable or read-only. Only applicable when option `mode` is `tree`, `text`, or `code`.
In case of mode `tree`, the callback is invoked as `editable(node)`, where `node` is an object `{field: string, value: string, path: string[]}`. The function must either return a boolean value to set both the nodes field and value editable or read-only, or return an object `{field: boolean, value: boolean}` to set set the read-only attribute for field and value individually.
In modes `text` and `code`, the callback is invoked as `editable(node)` where `node` is an empty object (no field, value, or path). In that case the function can return false to make the text or code editor completely read-only.
2016-01-12 19:40:23 +08:00
- `{function} onError(error)`
2016-01-12 19:40:23 +08:00
Set a callback function triggered when an error occurs. Invoked with the error as first argument. The callback is only invoked
for errors triggered by a users action, like switching from code mode to tree mode or clicking the Format button whilst the editor doesn't contain valid JSON.
- `{function} onModeChange(newMode, oldMode)`
Set a callback function triggered right after the mode is changed by the user. Only applicable when
the mode can be changed by the user (i.e. when option `modes` is set).
- `{boolean} escapeUnicode`
If true, unicode characters are escaped and displayed as their hexadecimal code (like `\u260E`) instead of of the character itself (like `☎`). False by default.
- `{boolean} sortObjectKeys`
If true, object keys in 'tree', 'view' or 'form' mode list be listed alphabetically instead by their insertion order. Sorting is performed using a natural sort algorithm, which makes it easier to see objects that have string numbers as keys. False by default.
2016-01-12 19:40:23 +08:00
- `{boolean} history`
Enables history, adds a button Undo and Redo to the menu of the JSONEditor. True by default. Only applicable when `mode` is 'tree' or 'form'.
- `{String} mode`
Set the editor mode. Available values: 'tree' (default), 'view', 'form', 'code', 'text'. In 'view' mode, the data and datastructure is read-only. In 'form' mode, only the value can be changed, the datastructure is read-only. Mode 'code' requires the Ace editor to be loaded on the page. Mode 'text' shows the data as plain text.
- `{String[]} modes`
Create a box in the editor menu where the user can switch between the specified modes. Available values: see option `mode`.
- `{String} name`
Initial field name for the root node, is undefined by default. Can also be set using `JSONEditor.setName(name)`. Only applicable when `mode` is 'tree', 'view', or 'form'.
- `{Object} schema`
Validate the JSON object against a JSON schema. A JSON schema describes the
structure that a JSON object must have, like required properties or the type
that a value must have.
2016-01-12 19:40:23 +08:00
See [http://json-schema.org/](http://json-schema.org/) for more information.
- `{Object} schemaRefs`
Schemas that are referenced using the `$ref` property from the JSON schema that are set in the `schema` option,
the object structure in the form of `{reference_key: schemaObject}`
2016-01-12 19:40:23 +08:00
- `{boolean} search`
Enables a search box in the upper right corner of the JSONEditor. True by default. Only applicable when `mode` is 'tree', 'view', or 'form'.
- `{Number} indentation`
Number of indentation spaces. 2 by default. Only applicable when `mode` is 'code' or 'text'.
- `{String} theme`
Set the Ace editor theme, uses included 'ace/theme/jsoneditor' by default. Please note that only the default theme is included with jsoneditor, so if you specify another one you need to make sure it is loaded.
- `{Object} templates`
Array of templates that will appear in the context menu, Each template is a json object precreated that can be added as a object value to any node in your document.
The following example allow you can create a "Person" node and a "Address" node, each one will appear in your context menu, once you selected the whole json object will be created.
```js
var options = {
templates: [
{
text: 'Person',
title: 'Insert a Person Node',
className: 'jsoneditor-type-object',
field: 'PersonTemplate',
value: {
'firstName': 'John',
'lastName': 'Do',
'age': 28
}
},
{
text: 'Address',
title: 'Insert a Address Node',
field: 'AddressTemplate',
value: {
'street': "",
'city': "",
'state': "",
'ZIP code': ""
}
}
]
}
```
- `{Object} autocomplete`
*autocomplete* will enable this feature in your editor in tree mode, the object have the following **subelements**:
2017-07-02 19:43:10 +08:00
- `{number[]} confirmKeys`
Indicate the KeyCodes for trigger confirm completion, by default those keys are: [39, 35, 9] which are the code for [right, end, tab]
- `{boolean} caseSensitive`
Indicate if the autocomplete is going to be strict case-sensitive to match the options.
- `{Function} getOptions (text: string, path: string[], input: string, editor: JSONEditor)`
This function will return your possible options for create the autocomplete selection, you can control dynamically which options you want to display according to the current active editing node.
*Parameters:*
- `text` : The text in the current node part. (basically the text that the user is editing)
- `path` : The path of the node that is being edited as an array with strings.
- `input` : Can be "field" or "value" depending if the user is editing a field name or a value of a node.
- `editor` : The editor instance object that is being edited.
2017-07-02 19:43:10 +08:00
*Returns:*
- Can return an array with autocomplete options (strings), for example `['apple','cranberry','raspberry','pie']`
- Can return `null` when there are no autocomplete options.
- Can return an object `{startFrom: number, options: string[]}`. Here `startFrom` determines the start character from where the existing text will be replaced. `startFrom` is `0` by default, replacing the whole text.
- Can return a `Promise` resolving one of the return types above to support asynchronously retrieving a list with options.
- `{boolean} navigationBar`
2017-09-03 18:54:55 +08:00
2017-09-18 23:49:54 +08:00
Adds navigation bar to the menu - the navigation bar visualize the current position on the tree structure as well as allows breadcrumbs navigation. True by default. Only applicable when `mode` is 'tree', 'form' or 'view'.
- `{boolean} statusBar`
2018-04-11 23:54:04 +08:00
Adds status bar to the bottom of the editor - the status bar shows the cursor position and a count of the selected characters. True by default. Only applicable when `mode` is 'code' or 'text'.
2013-05-04 17:54:03 +08:00
2018-01-26 07:25:17 +08:00
- `{function} onTextSelectionChange`
Set a callback function triggered when a text is selected in the JSONEditor.
callback signature should be:
```js
/**
* @param {{row:Number, column:Number}} startPos selection start position
* @param {{row:Number, column:Number}} endPos selected end position
* @param {String} text selected text
2018-01-26 07:25:17 +08:00
*/
function onTextSelectionChange(startPos, endPos, text) {
2018-01-26 07:25:17 +08:00
...
}
```
Only applicable when `mode` is 'code' or 'text'.
- `{function} onSelectionChange`
2018-01-26 07:25:17 +08:00
Set a callback function triggered when Nodes are selected in the JSONEditor.
callback signature should be:
```js
/**
* @typedef {{value: String|Object|Number|Boolean, path: Array.<String|Number>}} SerializableNode
*
* @param {SerializableNode=} start
* @param {SerializableNode=} end
2018-01-26 07:25:17 +08:00
*/
2018-04-02 16:18:32 +08:00
function onSelectionChange(start, end) {
2018-01-26 07:25:17 +08:00
...
}
```
Only applicable when `mode` is 'tree'.
2018-04-02 16:18:32 +08:00
- `{string} language`
The default language comes from the browser navigator, but you can force a specific language. So use here string as 'en' or 'pt-BR'. Built-in languages: `en`, `pt-BR`. Other translations can be specified via the option `languages`.
- `{Object} languages`
You can override existing translations or provide a new translation for a specific language. To do it provide an object at languages with language and the keys/values to be inserted. For example:
```
'languages': {
'pt-BR': {
'auto': 'Automático testing'
},
'en': {
'auto': 'Auto testing'
}
}
```
All available fields for translation can be found in the source file `src/js/i18n.js`.
2018-06-21 02:27:36 +08:00
- `{HTMLElement} modalAnchor`
The container element where modals (like for sorting and filtering) are attached: an overlay will be created on top
of this container, and the modal will be created in the center of this container.
2013-05-04 17:54:03 +08:00
### Methods
#### `JSONEditor.collapseAll()`
Collapse all fields. Only applicable for mode 'tree', 'view', and 'form'.
#### `JSONEditor.destroy()`
Destroy the editor. Clean up DOM, event listeners, and web workers.
2013-05-04 17:54:03 +08:00
#### `JSONEditor.expandAll()`
Expand all fields. Only applicable for mode 'tree', 'view', and 'form'.
#### `JSONEditor.focus()`
Set focus to the JSONEditor.
2018-08-06 20:30:44 +08:00
#### `JSONEditor.get()`
2013-05-04 17:54:03 +08:00
2018-08-06 20:30:44 +08:00
Get JSON data.
2013-05-04 17:54:03 +08:00
2018-08-06 20:30:44 +08:00
This method throws an exception when the editor does not contain valid JSON,
which can be the case when the editor is in mode `code` or `text`.
*Returns:*
2013-05-04 17:54:03 +08:00
- `{JSON} json`
2016-01-12 20:16:13 +08:00
2018-08-06 20:30:44 +08:00
JSON data from the JSONEditor.
2013-05-04 17:54:03 +08:00
2018-08-06 20:30:44 +08:00
#### `JSONEditor.getMode()`
2013-05-04 18:02:20 +08:00
2018-08-06 20:30:44 +08:00
Retrieve the current mode of the editor.
2013-05-04 18:02:20 +08:00
2018-08-06 20:30:44 +08:00
*Returns:*
2013-05-04 18:02:20 +08:00
2016-01-12 20:16:13 +08:00
- `{String} mode`
2018-08-06 20:30:44 +08:00
Current mode of the editor for example `tree` or `code`.
2013-05-04 18:02:20 +08:00
2018-08-06 20:30:44 +08:00
#### `JSONEditor.getName()`
2013-05-04 17:54:03 +08:00
2018-08-06 20:30:44 +08:00
Retrieve the current field name of the root node.
2013-05-04 17:54:03 +08:00
2018-08-06 20:30:44 +08:00
*Returns:*
2013-05-04 17:54:03 +08:00
2016-01-12 20:16:13 +08:00
- `{String | undefined} name`
2018-08-06 20:30:44 +08:00
Current field name of the root node, or undefined if not set.
2018-08-06 20:30:44 +08:00
#### `JSONEditor.getNodesByRange(start, end)`
2013-05-04 17:54:03 +08:00
2018-08-06 20:30:44 +08:00
A utility function for getting a list of `SerializableNode` under certain range.
2013-05-04 17:54:03 +08:00
2018-08-06 20:30:44 +08:00
This function can be used as complementary to `getSelection` and `onSelectionChange` if a list of __all__ the selected nodes is required.
2015-12-15 02:58:17 +08:00
2013-05-04 17:54:03 +08:00
*Parameters:*
2014-07-28 14:45:31 +08:00
2018-08-06 20:30:44 +08:00
- `{path: Array.<String>} start`
2018-08-06 20:30:44 +08:00
Path for the first node in range
2018-08-06 20:30:44 +08:00
- `{path: Array.<String>} end`
2016-01-12 20:16:13 +08:00
2018-08-06 20:30:44 +08:00
Path for the last node in range
2018-08-06 20:30:44 +08:00
#### `JSONEditor.getSelection()`
2013-05-04 17:54:03 +08:00
2018-08-06 20:30:44 +08:00
Get the current selected nodes, Only applicable for mode 'tree'.
2013-05-04 17:54:03 +08:00
*Returns:*
2018-08-06 20:30:44 +08:00
- `{start:SerializableNode, end: SerializableNode}`
2013-05-04 17:54:03 +08:00
#### `JSONEditor.getText()`
Get JSON data as string.
*Returns:*
2014-07-28 14:45:31 +08:00
2016-01-12 20:16:13 +08:00
- `{String} jsonString`
Contents of the editor as string. When the editor is in code `text` or `code`,
the returned text is returned as-is. For the other modes, the returned text
is a compacted string. In order to get the JSON formatted with a certain
number of spaces, use `JSON.stringify(JSONEditor.get(), null, 2)`.
2013-05-04 17:54:03 +08:00
2018-01-26 07:25:17 +08:00
#### `JSONEditor.getTextSelection()`
Get the current selected text with the selection range, Only applicable for mode 'text' and 'code'.
*Returns:*
- `{start:{row:Number, column:Number},end:{row:Number, column:Number},text:String} selection`
2018-08-06 20:30:44 +08:00
#### `JSONEditor.set(json)`
2018-01-26 07:25:17 +08:00
2018-08-06 20:30:44 +08:00
Set JSON data.
Resets the state of the editor (expanded nodes, search, selection).
See also `JSONEditor.update(json)`.
2018-01-26 07:25:17 +08:00
*Parameters:*
2018-08-06 20:30:44 +08:00
- `{JSON} json`
2018-01-26 07:25:17 +08:00
2018-08-06 20:30:44 +08:00
JSON data to be displayed in the JSONEditor.
2018-01-26 07:25:17 +08:00
2018-08-06 20:30:44 +08:00
#### `JSONEditor.setMode(mode)`
2018-01-26 07:25:17 +08:00
2018-08-06 20:30:44 +08:00
Switch mode. Mode `code` requires the [Ace editor](http://ace.ajax.org/).
2018-01-26 07:25:17 +08:00
2018-08-06 20:30:44 +08:00
*Parameters:*
2018-01-26 07:25:17 +08:00
2018-08-06 20:30:44 +08:00
- `{String} mode`
2018-01-26 07:25:17 +08:00
2018-08-06 20:30:44 +08:00
Available values: `tree`, `view`, `form`, `code`, `text`.
2018-01-26 07:25:17 +08:00
2018-08-06 20:30:44 +08:00
#### `JSONEditor.setName(name)`
Set a field name for the root node.
*Parameters:*
- `{String | undefined} name`
Field name of the root node. If undefined, the current name will be removed.
#### `JSONEditor.setSchema(schema [,schemaRefs])`
Set a JSON schema for validation of the JSON object. See also option `schema`.
See [http://json-schema.org/](http://json-schema.org/) for more information on the JSON schema definition.
*Parameters:*
- `{Object} schema`
A JSON schema.
- `{Object} schemaRefs`
Optional, Schemas that are referenced using the `$ref` property from the JSON schema, the object structure in the form of `{reference_key: schemaObject}`
2018-01-26 07:25:17 +08:00
#### `JSONEditor.setSelection(start, end)`
2018-01-26 07:25:17 +08:00
Set selection for a range of nodes, Only applicable for mode 'tree'.
- If no parameters sent - the current selection will be removed, if exists.
2018-04-02 16:18:32 +08:00
- For single node selecion send only the `start` parameter.
2018-01-26 07:25:17 +08:00
- If the nodes are not from the same level the first common parent will be selected
*Parameters:*
2018-04-22 15:02:17 +08:00
- `{path: Array.<String>} start`
2018-01-26 07:25:17 +08:00
Path for the start node
2018-01-26 07:25:17 +08:00
2018-04-22 15:02:17 +08:00
- `{path: Array.<String>} end`
2018-01-26 07:25:17 +08:00
Path for the end node
2013-05-04 17:54:03 +08:00
2018-08-06 20:30:44 +08:00
#### `JSONEditor.setText(jsonString)`
2018-04-02 07:01:22 +08:00
2018-08-06 20:30:44 +08:00
Set text data in the editor.
2018-04-02 07:01:22 +08:00
2018-08-06 20:30:44 +08:00
This method throws an exception when the provided jsonString does not contain
valid JSON and the editor is in mode `tree`, `view`, or `form`.
2018-04-02 07:01:22 +08:00
2018-08-06 20:30:44 +08:00
*Parameters:*
- `{String} jsonString`
Contents of the editor as string.
#### `JSONEditor.setTextSelection(startPos, endPos)`
Set text selection for a range, Only applicable for mode 'text' and 'code'.
2018-04-02 07:01:22 +08:00
*Parameters:*
2018-08-06 20:30:44 +08:00
- `{row:Number, column:Number} startPos`
2018-04-02 07:01:22 +08:00
2018-08-06 20:30:44 +08:00
Position for selection start
2018-04-02 07:01:22 +08:00
2018-08-06 20:30:44 +08:00
- `{row:Number, column:Number} endPos`
2018-04-02 07:01:22 +08:00
2018-08-06 20:30:44 +08:00
Position for selection end
2013-05-04 17:54:03 +08:00
#### `JSONEditor.update(json)`
Replace JSON data when the new data contains changes.
In modes `tree`, `form`, and `view`, the state of the editor will be maintained (expanded nodes, search, selection).
See also `JSONEditor.set(json)`.
*Parameters:*
- `{JSON} json`
JSON data to be displayed in the JSONEditor.
#### `JSONEditor.updateText (json)`
Replace text data when the new data contains changes.
In modes `tree`, `form`, and `view`, the state of the editor will be maintained (expanded nodes, search, selection).
See also `JSONEditor.setText(jsonString)`.
This method throws an exception when the provided jsonString does not contain
valid JSON and the editor is in mode `tree`, `view`, or `form`.
*Parameters:*
- `{String} jsonString`
Contents of the editor as string.
2018-08-06 23:10:07 +08:00
### Constants
- `{string[]} JSONEditor.VALID_OPTIONS`
An array with the names of all known options.
2013-05-04 17:54:03 +08:00
### Examples
A tree editor:
```js
var options = {
"mode": "tree",
"search": true
};
2014-05-30 16:33:11 +08:00
var editor = new JSONEditor(container, options);
2013-05-04 17:54:03 +08:00
var json = {
"Array": [1, 2, 3],
"Boolean": true,
"Null": null,
"Number": 123,
"Object": {"a": "b", "c": "d"},
"String": "Hello World"
};
editor.set(json);
editor.expandAll();
var json = editor.get(json);
```
A text editor:
```js
var options = {
"mode": "text",
"indentation": 2
};
2014-05-30 16:33:11 +08:00
var editor = new JSONEditor(container, options);
2013-05-04 17:54:03 +08:00
var json = {
"Array": [1, 2, 3],
"Boolean": true,
"Null": null,
"Number": 123,
"Object": {"a": "b", "c": "d"},
"String": "Hello World"
};
editor.set(json);
2015-11-02 15:53:13 +08:00
var json = editor.get();
2013-05-04 17:54:03 +08:00
```
## JSON parsing and stringification
2014-07-28 14:45:31 +08:00
In general to parse or stringify JSON data, the browsers built in JSON parser can be used. To create a formatted string from a JSON object, use:
2013-05-04 17:54:03 +08:00
```js
var formattedString = JSON.stringify(json, null, 2);
2013-05-04 17:54:03 +08:00
```
to create a compacted string from a JSON object, use:
```js
var compactString = JSON.stringify(json);
2013-05-04 17:54:03 +08:00
```
To parse a String to a JSON object, use:
```js
var json = JSON.parse(string);
```