From 1671dc7da7002f17246f09f64f0e48d3ce53d204 Mon Sep 17 00:00:00 2001 From: jos Date: Mon, 28 Jul 2014 08:45:31 +0200 Subject: [PATCH] Documented `editable` option --- HISTORY.md | 4 ++- docs/api.md | 79 +++++++++++++++++++++------------------------- src/js/Node.js | 8 ++--- src/js/treemode.js | 11 ++----- 4 files changed, 45 insertions(+), 57 deletions(-) diff --git a/HISTORY.md b/HISTORY.md index 7ffc810..700d3cd 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -7,7 +7,9 @@ https://github.com/josdejong/jsoneditor - JSONEditor now accepts JavaScript objects as input, and can turn them into valid JSON. For example `{a:2,b:'str'}` can be turned into `{"a":2,"b":"str"}`. - +- Implemented an option `editable`, a callback function, which allows to set + individual nodes (their field and/or value) editable or read-only. + ## 2014-05-31, version 3.0.0 diff --git a/docs/api.md b/docs/api.md index e04b29b..f2a656b 100644 --- a/docs/api.md +++ b/docs/api.md @@ -10,49 +10,37 @@ Constructs a new JSONEditor. *Parameters:* -- `{Element} container` - An HTML DIV element. The JSONEditor will be created inside this container - element. -- `{Object} options` +- `{Element} container` + An HTML DIV element. The JSONEditor will be created inside this container element. +- `{Object} options` Optional object with options. Available options: - - `{function} change`. - Set a callback method triggered when the contents of the JSONEditor change. - Called without parameters. - - `{function} error`. - Set a callback method triggered when an error occurs. - Invoked with the error as first argument. The callback is only invoked + - `{function} change` + Set a callback method triggered when the contents of the JSONEditor change. Called without parameters. + - `{function} editable` + Set a callback method to determine whether individual nodes are editable or read-only. Only applicable when option `mode` is `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}`. + - `{function} error` + Set a callback method triggered when an error occurs. Invoked with the error as first argument. The callback is only invoked for errors triggered by a users action. - - `{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'. - - `{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'. + - `{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'. + - `{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'. -- `{JSON} json` +- `{JSON} json` 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:* -- `{JSONEditor} editor` +- `{JSONEditor} editor` New instance of a JSONEditor. @@ -81,7 +69,7 @@ Switch mode. Mode `code` requires the [Ace editor](http://ace.ajax.org/). *Parameters:* -- `{String} mode` +- `{String} mode` Available values: `tree`, 'view', `form`, `code`, `text`. #### `JSONEditor.setName(name)` @@ -90,7 +78,7 @@ Set a field name for the root node. *Parameters:* -- `{String | undefined} name` +- `{String | undefined} name` Field name of the root node. If undefined, the current name will be removed. #### `JSONEditor.setText(jsonString)` @@ -98,14 +86,18 @@ Set a field name for the root node. Set text data in the formatter. *Parameters:* -- `{String} jsonString` Contents of the JSONformatter as string. + +- `{String} jsonString` + Contents of the JSONformatter as string. #### `JSONEditor.get()` Get JSON data. *Returns:* -- `{JSON} json` JSON data from the JSONEditor. + +- `{JSON} json` + JSON data from the JSONEditor. #### `JSONEditor.getName()` @@ -113,7 +105,7 @@ Retrieve the current field name of the root node. *Returns:* -- `{String | undefined} name` +- `{String | undefined} name` Current field name of the root node, or undefined if not set. #### `JSONEditor.getText()` @@ -121,7 +113,9 @@ Retrieve the current field name of the root node. Get JSON data as string. *Returns:* -- `{String} jsonString` Contents of the JSONformatter as string. + +- `{String} jsonString` + Contents of the JSONformatter as string. ### Examples @@ -171,8 +165,7 @@ var json = editor.get(json); ## JSON parsing and stringification -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: +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: ```js var formattedString = JSON.stringify(json, null, 2); diff --git a/src/js/Node.js b/src/js/Node.js index bc7cdd3..0b1e19b 100644 --- a/src/js/Node.js +++ b/src/js/Node.js @@ -38,10 +38,10 @@ define(['./ContextMenu', './appendNodeFactory', './util'], function (ContextMenu }; if (this.editor) { - this.editable.field = this.editor.mode.edit; - this.editable.value = !this.editor.mode.view; + this.editable.field = this.editor.options.mode === 'tree'; + this.editable.value = this.editor.options.mode !== 'view'; - if (this.editor.mode.edit && (typeof this.editor.options.editable === 'function')) { + if (this.editor.options.mode === 'tree' && (typeof this.editor.options.editable === 'function')) { var editable = this.editor.options.editable({ field: this.field, value: this.value, @@ -1204,7 +1204,7 @@ define(['./ContextMenu', './appendNodeFactory', './util'], function (ContextMenu dom.tr = document.createElement('tr'); dom.tr.node = this; - if (this.editor.mode.edit) { // note: we take here the global setting! + if (this.editor.options.mode === 'tree') { // note: we take here the global setting! var tdDrag = document.createElement('td'); if (this.editable.field) { // create draggable area diff --git a/src/js/treemode.js b/src/js/treemode.js index 18dee7b..1467f14 100644 --- a/src/js/treemode.js +++ b/src/js/treemode.js @@ -31,7 +31,7 @@ define(['./Highlighter', './History', './SearchBox', './Node', './modeswitcher', this._setOptions(options); - if (this.options.history && !this.mode.view) { + if (this.options.history && this.options.mode !== 'view') { this.history = new History(this); } @@ -70,13 +70,6 @@ define(['./Highlighter', './History', './SearchBox', './Node', './modeswitcher', } } } - - // interpret the mode options - this.mode = { - edit: (this.options.mode != 'view' && this.options.mode != 'form'), - view: (this.options.mode == 'view'), - form: (this.options.mode == 'form') - }; }; // node currently being edited @@ -682,7 +675,7 @@ define(['./Highlighter', './History', './SearchBox', './Node', './modeswitcher', // width, and the edit columns do have a fixed width var col; this.colgroupContent = document.createElement('colgroup'); - if (this.mode.edit) { + if (this.options.mode === 'tree') { col = document.createElement('col'); col.width = "24px"; this.colgroupContent.appendChild(col);