diff options
| -rw-r--r-- | modules/luci-base/htdocs/luci-static/resources/form.js | 2130 |
1 files changed, 2109 insertions, 21 deletions
diff --git a/modules/luci-base/htdocs/luci-static/resources/form.js b/modules/luci-base/htdocs/luci-static/resources/form.js index 69793ee554..2b02066a40 100644 --- a/modules/luci-base/htdocs/luci-static/resources/form.js +++ b/modules/luci-base/htdocs/luci-static/resources/form.js @@ -173,17 +173,50 @@ var CBIJSONConfig = baseclass.extend({ } }); -var CBINode = baseclass.extend({ +/** + * @class AbstractElement + * @memberof LuCI.form + * @hideconstructor + * @classdesc + * + * The `AbstractElement` class serves as abstract base for the different form + * elements implemented by `LuCI.form`. It provides the common logic for + * loading and rendering values, for nesting elements and for defining common + * properties. + * + * This class is private and not directly accessible by user code. + */ +var CBIAbstractElement = baseclass.extend(/** @lends LuCI.form.AbstractElement.prototype */ { __init__: function(title, description) { this.title = title || ''; this.description = description || ''; this.children = []; }, + /** + * Add another form element as children to this element. + * + * @param {AbstractElement} element + * The form element to add. + */ append: function(obj) { this.children.push(obj); }, + /** + * Parse this elements form input. + * + * The `parse()` function recursively walks the form element tree and + * triggers input value reading and validation for each encountered element. + * + * Elements which are hidden due to unsatisified dependencies are skipped. + * + * @returns {Promise<void>} + * Returns a promise resolving once this element's value and the values of + * all child elements have been parsed. The returned promise is rejected + * if any parsed values are not meeting the validation constraints of their + * respective elements. + */ parse: function() { var args = arguments; this.children.forEach(function(child) { @@ -191,10 +224,22 @@ var CBINode = baseclass.extend({ }); }, + /** + * Render the form element. + * + * The `render()` function recursively walks the form element tree and + * renders the markup for each element, returning the assembled DOM tree. + * + * @abstract + * @returns {Node|Promise<Node>} + * May return a DOM Node or a promise resolving to a DOM node containing + * the form element's markup, including the markup of any child elements. + */ render: function() { L.error('InternalError', 'Not implemented'); }, + /** @private */ loadChildren: function(/* ... */) { var tasks = []; @@ -206,6 +251,7 @@ var CBINode = baseclass.extend({ return Promise.all(tasks); }, + /** @private */ renderChildren: function(tab_name /*, ... */) { var tasks = [], index = 0; @@ -220,6 +266,15 @@ var CBINode = baseclass.extend({ return Promise.all(tasks); }, + /** + * Strip any HTML tags from the given input string. + * + * @param {string} input + * The input string to clean. + * + * @returns {string} + * The cleaned input string with HTML removes removed. + */ stripTags: function(s) { if (typeof(s) == 'string' && !s.match(/[<>]/)) return s; @@ -228,6 +283,32 @@ var CBINode = baseclass.extend({ return x.textContent || x.innerText || ''; }, + /** + * Format the given named property as title string. + * + * This function looks up the given named property and formats its value + * suitable for use as element caption or description string. It also + * strips any HTML tags from the result. + * + * If the property value is a string, it is passed to `String.format()` + * along with any additional parameters passed to `titleFn()`. + * + * If the property value is a function, it is invoked with any additional + * `titleFn()` parameters as arguments and the obtained return value is + * converted to a string. + * + * In all other cases, `null` is returned. + * + * @param {string} property + * The name of the element property to use. + * + * @param {...*} fmt_args + * Extra values to format the title string with. + * + * @returns {string|null} + * The formatted title string or `null` if the property did not exist or + * was neither a string nor a function. + */ titleFn: function(attr /*, ... */) { var s = null; @@ -246,7 +327,34 @@ var CBINode = baseclass.extend({ } }); -var CBIMap = CBINode.extend({ +/** + * @constructor Map + * @memberof LuCI.form + * @augments LuCI.form.AbstractElement + * + * @classdesc + * + * The `Map` class represents one complete form. A form usually maps one UCI + * configuraton file and is divided into multiple sections containing multiple + * fields each. + * + * It serves as main entry point into the `LuCI.form` for typical view code. + * + * @param {string} config + * The UCI configuration to map. It is automatically loaded along when the + * resulting map instance. + * + * @param {string} [title] + * The title caption of the form. A form title is usually rendered as separate + * headline element before the actual form contents. If omitted, the + * corresponding headline element will not be rendered. + * + * @param {string} [description] + * The description text of the form which is usually rendered as text + * paragraph below the form title and before the actual form conents. + * If omitted, the corresponding paragraph element will not be rendered. + */ +var CBIMap = CBIAbstractElement.extend(/** @lends LuCI.form.Map.prototype */ { __init__: function(config /*, ... */) { this.super('__init__', this.varargs(arguments, 1)); @@ -255,6 +363,36 @@ var CBIMap = CBINode.extend({ this.data = uci; }, + /** + * Find all DOM nodes within this Map which match the given search + * parameters. This function is essentially a convenience wrapper around + * `querySelectorAll()`. + * + * This function is sensitive to the amount of arguments passed to it; + * if only one argument is specified, it is used as selector-expression + * as-is. When two arguments are passed, the first argument is treated + * as attribute name, the second one as attribute value to match. + * + * As an example, `map.findElements('input')` would find all `<input>` + * nodes while `map.findElements('type', 'text')` would find any DOM node + * with a `type="text"` attribute. + * + * @param {string} selector_or_attrname + * If invoked with only one parameter, this argument is a + * `querySelectorAll()` compatible selector expression. If invoked with + * two parameters, this argument is the attribute name to filter for. + * + * @param {string} [attrvalue] + * In case the function is invoked with two parameters, this argument + * specifies the attribute value to match. + * + * @throws {InternalError} + * Throws an `InternalError` if more than two function parameters are + * passed. + * + * @returns {NodeList} + * Returns a (possibly empty) DOM `NodeList` containing the found DOM nodes. + */ findElements: function(/* ... */) { var q = null; @@ -268,16 +406,86 @@ var CBIMap = CBINode.extend({ return this.root.querySelectorAll(q); }, + /** + * Find the first DOM node within this Map which matches the given search + * parameters. This function is essentially a convenience wrapper around + * `findElements()` which only returns the first found node. + * + * This function is sensitive to the amount of arguments passed to it; + * if only one argument is specified, it is used as selector-expression + * as-is. When two arguments are passed, the first argument is treated + * as attribute name, the second one as attribute value to match. + * + * As an example, `map.findElement('input')` would find the first `<input>` + * node while `map.findElement('type', 'text')` would find the first DOM + * node with a `type="text"` attribute. + * + * @param {string} selector_or_attrname + * If invoked with only one parameter, this argument is a `querySelector()` + * compatible selector expression. If invoked with two parameters, this + * argument is the attribute name to filter for. + * + * @param {string} [attrvalue] + * In case the function is invoked with two parameters, this argument + * specifies the attribute value to match. + * + * @throws {InternalError} + * Throws an `InternalError` if more than two function parameters are + * passed. + * + * @returns {Node|null} + * Returns the first found DOM node or `null` if no element matched. + */ findElement: function(/* ... */) { var res = this.findElements.apply(this, arguments); return res.length ? res[0] : null; }, + /** + * Tie another UCI configuration to the map. + * + * By default, a map instance will only load the UCI configuration file + * specified in the constructor but sometimes access to values from + * further configuration files is required. This function allows for such + * use cases by registering further UCI configuration files which are + * needed by the map. + * + * @param {string} config + * The additional UCI configuration file to tie to the map. If the given + * config already is in the list of required files, it will be ignored. + */ chain: function(config) { if (this.parsechain.indexOf(config) == -1) this.parsechain.push(config); }, + /** + * Add a configuration section to the map. + * + * LuCI forms follow the structure of the underlying UCI configurations, + * means that a map, which represents a single UCI configuration, is + * divided into multiple sections which in turn contain an arbitrary + * number of options. + * + * While UCI itself only knows two kinds of sections - named and anonymous + * ones - the form class offers various flavors of form section elements + * to present configuration sections in different ways. Refer to the + * documentation of the different section classes for details. + * + * @param {LuCI.form.AbstractSection} sectionclass + * The section class to use for rendering the configuration section. + * Note that this value must be the class itself, not a class instance + * obtained from calling `new`. It must also be a class dervied from + * `LuCI.form.AbstractSection`. + * + * @param {...string} classargs + * Additional arguments which are passed as-is to the contructor of the + * given section class. Refer to the class specific constructor + * documentation for details. + * + * @returns {LuCI.form.AbstractSection} + * Returns the instantiated section class instance. + */ section: function(cbiClass /*, ... */) { if (!CBIAbstractSection.isSubclass(cbiClass)) L.error('TypeError', 'Class must be a descendent of CBIAbstractSection'); @@ -287,11 +495,37 @@ var CBIMap = CBINode.extend({ return obj; }, + /** + * Load the configuration covered by this map. + * + * The `load()` function first loads all referenced UCI configurations, + * then it recursively walks the form element tree and invokes the + * load function of each child element. + * + * @returns {Promise<void>} + * Returns a promise resolving once the entire form completed loading all + * data. The promise may reject with an error if any configuration failed + * to load or if any of the child elements load functions rejected with + * an error. + */ load: function() { return this.data.load(this.parsechain || [ this.config ]) .then(this.loadChildren.bind(this)); }, + /** + * Parse the form input values. + * + * The `parse()` function recursively walks the form element tree and + * triggers input value reading and validation for each child element. + * + * Elements which are hidden due to unsatisified dependencies are skipped. + * + * @returns {Promise<void>} + * Returns a promise resolving once the entire form completed parsing all + * input values. The returned promise is rejected if any parsed values are + * not meeting the validation constraints of their respective elements. + */ parse: function() { var tasks = []; @@ -302,6 +536,26 @@ var CBIMap = CBINode.extend({ return Promise.all(tasks); }, + /** + * Save the form input values. + * + * This function parses the current form, saves the resulting UCI changes, + * reloads the UCI configuration data and redraws the form elements. + * + * @param {function} [cb] + * An optional callback function that is invoked after the form is parsed + * but before the changed UCI data is saved. This is useful to perform + * additional data manipulation steps before saving the changes. + * + * @param {boolean} [silent=false] + * If set to `true`, trigger an alert message to the user in case saving + * the form data failes. Otherwise fail silently. + * + * @returns {Promise<void>} + * Returns a promise resolving once the entire save operation is complete. + * The returned promise is rejected if any step of the save operation + * failed. + */ save: function(cb, silent) { this.checkDepends(); @@ -317,14 +571,30 @@ var CBIMap = CBINode.extend({ }).finally(this.renderContents.bind(this)); }, + /** + * Reset the form by re-rendering its contents. This will revert all + * unsaved user inputs to their initial form state. + * + * @returns {Promise<Node>} + * Returns a promise resolving to the toplevel form DOM node once the + * re-rendering is complete. + */ reset: function() { return this.renderContents(); }, + /** + * Render the form markup. + * + * @returns {Promise<Node>} + * Returns a promise resolving to the toplevel form DOM node once the + * rendering is complete. + */ render: function() { return this.load().then(this.renderContents.bind(this)); }, + /** @private */ renderContents: function() { var mapEl = this.root || (this.root = E('div', { 'id': 'cbi-%s'.format(this.config), @@ -369,6 +639,25 @@ var CBIMap = CBINode.extend({ }, this)); }, + /** + * Find a form option element instance. + * + * @param {string} name_or_id + * The name or the full ID of the option element to look up. + * + * @param {string} [section_id] + * The ID of the UCI section containing the option to look up. May be + * omitted if a full ID is passed as first argument. + * + * @param {string} [config] + * The name of the UCI configuration the option instance is belonging to. + * Defaults to the main UCI configuration of the map if omitted. + * + * @returns {Array<LuCI.form.AbstractValue,string>|null} + * Returns a two-element array containing the form option instance as + * first item and the corresponding UCI section ID as second item. + * Returns `null` if the option could not be found. + */ lookupOption: function(name, section_id, config_name) { var id, elem, sid, inst; @@ -384,6 +673,7 @@ var CBIMap = CBINode.extend({ return (inst instanceof CBIAbstractValue) ? [ inst, sid ] : null; }, + /** @private */ checkDepends: function(ev, n) { var changed = false; @@ -397,6 +687,7 @@ var CBIMap = CBINode.extend({ ui.tabs.updateTabs(ev, this.root); }, + /** @private */ isDependencySatisfied: function(depends, config_name, section_id) { var def = false; @@ -436,7 +727,34 @@ var CBIMap = CBINode.extend({ } }); -var CBIJSONMap = CBIMap.extend({ +/** + * @constructor JSONMap + * @memberof LuCI.form + * @augments LuCI.form.Map + * + * @classdesc + * + * A `JSONMap` class functions similar to [LuCI.form.Map]{@link LuCI.form.Map} + * but uses a multidimensional JavaScript object instead of UCI configuration + * as data source. + * + * @param {Object<string, Object<string, *>|Array<Object<string, *>>>} data + * The JavaScript object to use as data source. Internally, the object is + * converted into an UCI-like format. Its toplevel keys are treated like UCI + * section types while the object or array-of-object values are treated as + * section contents. + * + * @param {string} [title] + * The title caption of the form. A form title is usually rendered as separate + * headline element before the actual form contents. If omitted, the + * corresponding headline element will not be rendered. + * + * @param {string} [description] + * The description text of the form which is usually rendered as text + * paragraph below the form title and before the actual form conents. + * If omitted, the corresponding paragraph element will not be rendered. + */ +var CBIJSONMap = CBIMap.extend(/** @lends LuCI.form.JSONMap.prototype */ { __init__: function(data /*, ... */) { this.super('__init__', this.varargs(arguments, 1, 'json')); @@ -446,7 +764,21 @@ var CBIJSONMap = CBIMap.extend({ } }); -var CBIAbstractSection = CBINode.extend({ +/** + * @class AbstractSection + * @memberof LuCI.form + * @augments LuCI.form.AbstractElement + * @hideconstructor + * @classdesc + * + * The `AbstractSection` class serves as abstract base for the different form + * section styles implemented by `LuCI.form`. It provides the common logic for + * enumerating underlying configuration section instances, for registering + * form options and for handling tabs to segment child options. + * + * This class is private and not directly accessible by user code. + */ +var CBIAbstractSection = CBIAbstractElement.extend(/** @lends LuCI.form.AbstractSection.prototype */ { __init__: function(map, sectionType /*, ... */) { this.super('__init__', this.varargs(arguments, 2)); @@ -459,14 +791,68 @@ var CBIAbstractSection = CBINode.extend({ this.dynamic = false; }, + /** + * Access the parent option container instance. + * + * In case this section is nested within an option element container, + * this property will hold a reference to the parent option instance. + * + * If this section is not nested, the property is `null`. + * + * @name LuCI.form.AbstractSection.prototype#parentoption + * @type LuCI.form.AbstractValue + * @readonly + */ + + /** + * Enumerate the UCI section IDs covered by this form section element. + * + * @abstract + * @throws {InternalError} + * Throws an `InternalError` exception if the function is not implemented. + * + * @returns {string[]} + * Returns an array of UCI section IDs covered by this form element. + * The sections will be rendered in the same order as the returned array. + */ cfgsections: function() { L.error('InternalError', 'Not implemented'); }, + /** + * Filter UCI section IDs to render. + * + * The filter function is invoked for each UCI section ID of a given type + * and controls whether the given UCI section is rendered or ignored by + * the form section element. + * + * The default implementation always returns `true`. User code or + * classes extending `AbstractSection` may overwrite this function with + * custom implementations. + * + * @abstract + * @param {string} section_id + * The UCI section ID to test. + * + * @returns {boolean} + * Returns `true` when the given UCI section ID should be handled and + * `false` when it should be ignored. + */ filter: function(section_id) { return true; }, + /** + * Load the configuration covered by this section. + * + * The `load()` function recursively walks the section element tree and + * invokes the load function of each child option element. + * + * @returns {Promise<void>} + * Returns a promise resolving once the values of all child elements have + * been loaded. The promise may reject with an error if any of the child + * elements load functions rejected with an error. + */ load: function() { var section_ids = this.cfgsections(), tasks = []; @@ -482,6 +868,20 @@ var CBIAbstractSection = CBINode.extend({ return Promise.all(tasks); }, + /** + * Parse this sections form input. + * + * The `parse()` function recursively walks the section element tree and + * triggers input value reading and validation for each encountered child + * option element. + * + * Options which are hidden due to unsatisified dependencies are skipped. + * + * @returns {Promise<void>} + * Returns a promise resolving once the values of all child elements have + * been parsed. The returned promise is rejected if any parsed values are + * not meeting the validation constraints of their respective elements. + */ parse: function() { var section_ids = this.cfgsections(), tasks = []; @@ -494,6 +894,35 @@ var CBIAbstractSection = CBINode.extend({ return Promise.all(tasks); }, + /** + * Add an option tab to the section. + * + * The child option elements of a section may be divided into multiple + * tabs to provide a better overview to the user. + * + * Before options can be moved into a tab pane, the corresponding tab + * has to be defined first, which is done by calling this function. + * + * Note that once tabs are defined, user code must use the `taboption()` + * method to add options to specific tabs. Option elements added by + * `option()` will not be assigned to any tab and not be rendered in this + * case. + * + * @param {string} name + * The name of the tab to register. It may be freely chosen and just serves + * as an identifier to differentiate tabs. + * + * @param {string} title + * The human readable caption of the tab. + * + * @param {string} [description] + * An additional description text for the corresponding tab pane. It is + * displayed as text paragraph below the tab but before the tab pane + * contents. If omitted, no description will be rendered. + * + * @throws {Error} + * Throws an exeption if a tab with the same `name` already exists. + */ tab: function(name, title, description) { if (this.tabs && this.tabs[name]) throw 'Tab already declared'; @@ -513,6 +942,30 @@ var CBIAbstractSection = CBINode.extend({ this.tab_names.push(name); }, + /** + * Add a configuration option widget to the section. + * + * Note that [taboption()]{@link LuCI.form.AbstractSection#taboption} + * should be used instead if this form section element uses tabs. + * + * @param {LuCI.form.AbstractValue} optionclass + * The option class to use for rendering the configuration option. Note + * that this value must be the class itself, not a class instance obtained + * from calling `new`. It must also be a class dervied from + * [LuCI.form.AbstractSection]{@link LuCI.form.AbstractSection}. + * + * @param {...*} classargs + * Additional arguments which are passed as-is to the contructor of the + * given option class. Refer to the class specific constructor + * documentation for details. + * + * @throws {TypeError} + * Throws a `TypeError` exception in case the passed class value is not a + * descendent of `AbstractValue`. + * + * @returns {LuCI.form.AbstractValue} + * Returns the instantiated option class instance. + */ option: function(cbiClass /*, ... */) { if (!CBIAbstractValue.isSubclass(cbiClass)) throw L.error('TypeError', 'Class must be a descendent of CBIAbstractValue'); @@ -522,6 +975,34 @@ var CBIAbstractSection = CBINode.extend({ return obj; }, + /** + * Add a configuration option widget to a tab of the section. + * + * @param {string} tabname + * The name of the section tab to add the option element to. + * + * @param {LuCI.form.AbstractValue} optionclass + * The option class to use for rendering the configuration option. Note + * that this value must be the class itself, not a class instance obtained + * from calling `new`. It must also be a class dervied from + * [LuCI.form.AbstractSection]{@link LuCI.form.AbstractSection}. + * + * @param {...*} classargs + * Additional arguments which are passed as-is to the contructor of the + * given option class. Refer to the class specific constructor + * documentation for details. + * + * @throws {ReferenceError} + * Throws a `ReferenceError` exception when the given tab name does not + * exist. + * + * @throws {TypeError} + * Throws a `TypeError` exception in case the passed class value is not a + * descendent of `AbstractValue`. + * + * @returns {LuCI.form.AbstractValue} + * Returns the instantiated option class instance. + */ taboption: function(tabName /*, ... */) { if (!this.tabs || !this.tabs[tabName]) throw L.error('ReferenceError', 'Associated tab not declared'); @@ -532,6 +1013,7 @@ var CBIAbstractSection = CBINode.extend({ return obj; }, + /** @private */ renderUCISection: function(section_id) { var renderTasks = []; @@ -545,6 +1027,7 @@ var CBIAbstractSection = CBINode.extend({ .then(this.renderTabContainers.bind(this, section_id)); }, + /** @private */ renderTabContainers: function(section_id, nodes) { var config_name = this.uciconfig || this.map.config, containerEls = E([]); @@ -570,6 +1053,7 @@ var CBIAbstractSection = CBINode.extend({ return containerEls; }, + /** @private */ renderOptions: function(tab_name, section_id) { var in_table = (this instanceof CBITableSection); return this.renderChildren(tab_name, section_id, in_table).then(function(nodes) { @@ -580,6 +1064,7 @@ var CBIAbstractSection = CBINode.extend({ }); }, + /** @private */ checkDepends: function(ev, n) { var changed = false, sids = this.cfgsections(); @@ -657,7 +1142,21 @@ var isContained = function(x, y) { return false; }; -var CBIAbstractValue = CBINode.extend({ +/** + * @class AbstractValue + * @memberof LuCI.form + * @augments LuCI.form.AbstractElement + * @hideconstructor + * @classdesc + * + * The `AbstractValue` class serves as abstract base for the different form + * option styles implemented by `LuCI.form`. It provides the common logic for + * handling option input values, for dependencies among options and for + * validation constraints that should be applied to entered values. + * + * This class is private and not directly accessible by user code. + */ +var CBIAbstractValue = CBIAbstractElement.extend(/** @lends LuCI.form.AbstractValue.prototype */ { __init__: function(map, section, option /*, ... */) { this.super('__init__', this.varargs(arguments, 3)); @@ -674,6 +1173,237 @@ var CBIAbstractValue = CBINode.extend({ this.optional = false; }, + /** + * If set to `false`, the underlying option value is retained upon saving + * the form when the option element is disabled due to unsatisfied + * dependency constraints. + * + * @name LuCI.form.AbstractValue.prototype#rmempty + * @type boolean + * @default true + */ + + /** + * If set to `true`, the underlying ui input widget is allowed to be empty, + * otherwise the option element is marked invalid when no value is entered + * or selected by the user. + * + * @name LuCI.form.AbstractValue.prototype#optional + * @type boolean + * @default false + */ + + /** + * Sets a default value to use when the underlying UCI option is not set. + * + * @name LuCI.form.AbstractValue.prototype#default + * @type * + * @default null + */ + + /** + * Specifies a datatype constraint expression to validate input values + * against. Refer to {@link LuCI.validation} for details on the format. + * + * If the user entered input does not match the datatype validation, the + * option element is marked as invalid. + * + * @name LuCI.form.AbstractValue.prototype#datatype + * @type string + * @default null + */ + + /** + * Specifies a custom validation function to test the user input for + * validity. The validation function must return `true` to accept the + * value. Any other return value type is converted to a string and + * displayed to the user as validation error message. + * + * If the user entered input does not pass the validation function, the + * option element is marked as invalid. + * + * @name LuCI.form.AbstractValue.prototype#validate + * @type function + * @default null + */ + + /** + * Override the UCI configuration name to read the option value from. + * + * By default, the configuration name is inherited from the parent Map. + * By setting this property, a deviating configuration may be specified. + * + * The default is null, means inheriting from the parent form. + * + * @name LuCI.form.AbstractValue.prototype#uciconfig + * @type string + * @default null + */ + + /** + * Override the UCI section name to read the option value from. + * + * By default, the section ID is inherited from the parent section element. + * By setting this property, a deviating section may be specified. + * + * The default is null, means inheriting from the parent section. + * + * @name LuCI.form.AbstractValue.prototype#ucisection + * @type string + * @default null + */ + + /** + * Override the UCI option name to read the value from. + * + * By default, the elements name, which is passed as third argument to + * the constructor, is used as UCI option name. By setting this property, + * a deviating UCI option may be specified. + * + * The default is null, means using the option element name. + * + * @name LuCI.form.AbstractValue.prototype#ucioption + * @type string + * @default null + */ + + /** + * Mark grid section option element as editable. + * + * Options which are displayed in the table portion of a `GridSection` + * instance are rendered as readonly text by default. By setting the + * `editable` property of a child option element to `true`, that element + * is rendered as full input widget within its cell instead of a text only + * preview. + * + * This property has no effect on options that are not children of grid + * section elements. + * + * @name LuCI.form.AbstractValue.prototype#editable + * @type boolean + * @default false + */ + + /** + * Move grid section option element into the table, the modal popup or both. + * + * If this property is `null` (the default), the option element is + * displayed in both the table preview area and the per-section instance + * modal popup of a grid section. When it is set to `false` the option + * is only shown in the table but not the modal popup. When set to `true`, + * the option is only visible in the modal popup but not the table. + * + * This property has no effect on options that are not children of grid + * section elements. + * + * @name LuCI.form.AbstractValue.prototype#modalonly + * @type boolean + * @default null + */ + + /** + * Override the cell width of a table or grid section child option. + * + * If the property is set to a numeric value, it is treated as pixel width + * which is set on the containing cell element of the option, essentially + * forcing a certain column width. When the property is set to a string + * value, it is applied as-is to the CSS `width` property. + * + * This property has no effect on options that are not children of grid or + * table section elements. + * + * @name LuCI.form.AbstractValue.prototype#width + * @type number|string + * @default null + */ + + /** + * Add a dependency contraint to the option. + * + * Dependency constraints allow making the presence of option elements + * dependant on the current values of certain other options within the + * same form. An option element with unsatisfied dependencies will be + * hidden from the view and its current value is omitted when saving. + * + * Multiple constraints (that is, multiple calls to `depends()`) are + * treated as alternatives, forming a logical "or" expression. + * + * By passing an object of name => value pairs as first argument, it is + * possible to depend on multiple options simultaneously, allowing to form + * a logical "and" expression. + * + * Option names may be given in "dot notation" which allows to reference + * option elements outside of the current form section. If a name without + * dot is specified, it refers to an option within the same configuration + * section. If specified as <code>configname.sectionid.optionname</code>, + * options anywhere within the same form may be specified. + * + * The object notation also allows for a number of special keys which are + * not treated as option names but as modifiers to influence the dependency + * constraint evaluation. The associated value of these special "tag" keys + * is ignored. The recognized tags are: + * + * <ul> + * <li> + * <code>!reverse</code><br> + * Invert the dependency, instead of requiring another option to be + * equal to the dependency value, that option should <em>not</em> be + * equal. + * </li> + * <li> + * <code>!contains</code><br> + * Instead of requiring an exact match, the dependency is considered + * satisfied when the dependency value is contained within the option + * value. + * </li> + * <li> + * <code>!default</code><br> + * The dependency is always satisfied + * </li> + * </ul> + * + * Examples: + * + * <ul> + * <li> + * <code>opt.depends("foo", "test")</code><br> + * Require the value of `foo` to be `test`. + * </li> + * <li> + * <code>opt.depends({ foo: "test" })</code><br> + * Equivalent to the previous example. + * </li> + * <li> + * <code>opt.depends({ foo: "test", bar: "qrx" })</code><br> + * Require the value of `foo` to be `test` and the value of `bar` to be + * `qrx`. + * </li> + * <li> + * <code>opt.depends({ foo: "test" })<br> + * opt.depends({ bar: "qrx" })</code><br> + * Require either <code>foo</code> to be set to <code>test</code>, + * <em>or</em> the <code>bar</code> option to be <code>qrx</code>. + * </li> + * <li> + * <code>opt.depends("test.section1.foo", "bar")</code><br> + * Require the "foo" form option within the "section1" section to be + * set to "bar". + * </li> + * <li> + * <code>opt.depends({ foo: "test", "!contains": true })</code><br> + * Require the "foo" option value to contain the substring "test". + * </li> + * </ul> + * + * @param {string|Object<string, string|boolean>} optionname_or_depends + * The name of the option to depend on or an object describing multiple + * dependencies which must be satified (a logical "and" expression). + * + * @param {string} optionvalue + * When invoked with a plain option name as first argument, this parameter + * specifies the expected value. In case an object is passed as first + * argument, this parameter is ignored. + */ depends: function(field, value) { var deps; @@ -685,6 +1415,7 @@ var CBIAbstractValue = CBINode.extend({ this.deps.push(deps); }, + /** @private */ transformDepList: function(section_id, deplist) { var list = deplist || this.deps, deps = []; @@ -720,6 +1451,7 @@ var CBIAbstractValue = CBINode.extend({ return deps; }, + /** @private */ transformChoices: function() { if (!Array.isArray(this.keylist) || this.keylist.length == 0) return null; @@ -732,6 +1464,7 @@ var CBIAbstractValue = CBINode.extend({ return choices; }, + /** @private */ checkDepends: function(section_id) { var config_name = this.uciconfig || this.section.uciconfig || this.map.config, active = this.map.isDependencySatisfied(this.deps, config_name, section_id); @@ -742,6 +1475,7 @@ var CBIAbstractValue = CBINode.extend({ return active; }, + /** @private */ updateDefaultValue: function(section_id) { if (!L.isObject(this.defaults)) return; @@ -771,6 +1505,23 @@ var CBIAbstractValue = CBINode.extend({ this.default = satisified_defval; }, + /** + * Obtain the internal ID ("cbid") of the element instance. + * + * Since each form section element may map multiple underlying + * configuration sections, the configuration section ID is required to + * form a fully qualified ID pointing to the specific element instance + * within the given specific section. + * + * @param {string} section_id + * The configuration section ID + * + * @throws {TypeError} + * Throws a `TypeError` exception when no `section_id` was specified. + * + * @returns {string} + * Returns the element ID. + */ cbid: function(section_id) { if (section_id == null) L.error('TypeError', 'Section ID required'); @@ -780,6 +1531,25 @@ var CBIAbstractValue = CBINode.extend({ section_id, this.option); }, + /** + * Load the underlying configuration value. + * + * The default implementation of this method reads and returns the + * underlying UCI option value (or the related JavaScript property for + * `JSONMap` instances). It may be overwritten by user code to load data + * from nonstandard sources. + * + * @param {string} section_id + * The configuration section ID + * + * @throws {TypeError} + * Throws a `TypeError` exception when no `section_id` was specified. + * + * @returns {*|Promise<*>} + * Returns the configuration value to initialize the option element with. + * The return value of this function is filtered through `Promise.resolve()` + * so it may return promises if overridden by user code. + */ load: function(section_id) { if (section_id == null) L.error('TypeError', 'Section ID required'); @@ -790,12 +1560,42 @@ var CBIAbstractValue = CBINode.extend({ this.ucioption || this.option); }, + /** + * Obtain the underlying `LuCI.ui` element instance. + * + * @param {string} section_id + * The configuration section ID + * + * @throws {TypeError} + * Throws a `TypeError` exception when no `section_id` was specified. + * + * @return {LuCI.ui.AbstractElement|null} + * Returns the `LuCI.ui` element instance or `null` in case the form + * option implementation does not use `LuCI.ui` widgets. + */ getUIElement: function(section_id) { var node = this.map.findElement('id', this.cbid(section_id)), inst = node ? dom.findClassInstance(node) : null; return (inst instanceof ui.AbstractElement) ? inst : null; }, + /** + * Query the underlying configuration value. + * + * The default implementation of this method returns the cached return + * value of [load()]{@link LuCI.form.AbstractValue#load}. It may be + * overwritten by user code to obtain the configuration value in a + * different way. + * + * @param {string} section_id + * The configuration section ID + * + * @throws {TypeError} + * Throws a `TypeError` exception when no `section_id` was specified. + * + * @returns {*} + * Returns the configuration value. + */ cfgvalue: function(section_id, set_value) { if (section_id == null) L.error('TypeError', 'Section ID required'); @@ -808,11 +1608,46 @@ var CBIAbstractValue = CBINode.extend({ return this.data ? this.data[section_id] : null; }, + /** + * Query the current form input value. + * + * The default implementation of this method returns the current input + * value of the underlying [LuCI.ui]{@link LuCI.ui.AbstractElement} widget. + * It may be overwritten by user code to handle input values differently. + * + * @param {string} section_id + * The configuration section ID + * + * @throws {TypeError} + * Throws a `TypeError` exception when no `section_id` was specified. + * + * @returns {*} + * Returns the current input value. + */ formvalue: function(section_id) { var elem = this.getUIElement(section_id); return elem ? elem.getValue() : null; }, + /** + * Obtain a textual input representation. + * + * The default implementation of this method returns the HTML escaped + * current input value of the underlying + * [LuCI.ui]{@link LuCI.ui.AbstractElement} widget. User code or specific + * option element implementations may overwrite this function to apply a + * different logic, e.g. to return `Yes` or `No` depending on the checked + * state of checkbox elements. + * + * @param {string} section_id + * The configuration section ID + * + * @throws {TypeError} + * Throws a `TypeError` exception when no `section_id` was specified. + * + * @returns {string} + * Returns the text representation of the current input value. + */ textvalue: function(section_id) { var cval = this.cfgvalue(section_id); @@ -822,20 +1657,67 @@ var CBIAbstractValue = CBINode.extend({ return (cval != null) ? '%h'.format(cval) : null; }, + /** + * Apply custom validation logic. + * + * This method is invoked whenever incremental validation is performed on + * the user input, e.g. on keyup or blur events. + * + * The default implementation of this method does nothing and always + * returns `true`. User code may overwrite this method to provide + * additional validation logic which is not covered by data type + * constraints. + * + * @abstract + * @param {string} section_id + * The configuration section ID + * + * @param {*} value + * The value to validate + * + * @returns {*} + * The method shall return `true` to accept the given value. Any other + * return value is treated as failure, converted to a string and displayed + * as error message to the user. + */ validate: function(section_id, value) { return true; }, + /** + * Test whether the input value is currently valid. + * + * @param {string} section_id + * The configuration section ID + * + * @returns {boolean} + * Returns `true` if the input value currently is valid, otherwise it + * returns `false`. + */ isValid: function(section_id) { var elem = this.getUIElement(section_id); return elem ? elem.isValid() : true; }, + /** + * Test whether the option element is currently active. + * + * An element is active when it is not hidden due to unsatisfied dependency + * constraints. + * + * @param {string} section_id + * The configuration section ID + * + * @returns {boolean} + * Returns `true` if the option element currently is active, otherwise it + * returns `false`. + */ isActive: function(section_id) { var field = this.map.findElement('data-field', this.cbid(section_id)); return (field != null && !field.classList.contains('hidden')); }, + /** @private */ setActive: function(section_id, active) { var field = this.map.findElement('data-field', this.cbid(section_id)); @@ -847,11 +1729,26 @@ var CBIAbstractValue = CBINode.extend({ return false; }, + /** @private */ triggerValidation: function(section_id) { var elem = this.getUIElement(section_id); return elem ? elem.triggerValidation() : true; }, + /** + * Parse the option element input. + * + * The function is invoked when the `parse()` method has been invoked on + * the parent form and triggers input value reading and validation. + * + * @param {string} section_id + * The configuration section ID + * + * @returns {Promise<void>} + * Returns a promise resolving once the input value has been read and + * validated or rejecting in case the input value does not meet the + * validation constraints. + */ parse: function(section_id) { var active = this.isActive(section_id), cval = this.cfgvalue(section_id), @@ -877,6 +1774,26 @@ var CBIAbstractValue = CBINode.extend({ return Promise.resolve(); }, + /** + * Write the current input value into the configuration. + * + * This function is invoked upon saving the parent form when the option + * element is valid and when its input value has been changed compared to + * the initial value returned by + * [cfgvalue()]{@link LuCI.form.AbstractValue#cfgvalue}. + * + * The default implementation simply sets the given input value in the + * UCI configuration (or the associated JavaScript object property in + * case of `JSONMap` forms). It may be overwritten by user code to + * implement alternative save logic, e.g. to transform the input value + * before it is written. + * + * @param {string} section_id + * The configuration section ID + * + * @param {string|string[]} formvalue + * The input value to write. + */ write: function(section_id, formvalue) { return this.map.data.set( this.uciconfig || this.section.uciconfig || this.map.config, @@ -885,6 +1802,21 @@ var CBIAbstractValue = CBINode.extend({ formvalue); }, + /** + * Remove the corresponding value from the configuration. + * + * This function is invoked upon saving the parent form when the option + * element has been hidden due to unsatisfied dependencies or when the + * user cleared the input value and the option is marked optional. + * + * The default implementation simply removes the associated option from the + * UCI configuration (or the associated JavaScript object property in + * case of `JSONMap` forms). It may be overwritten by user code to + * implement alternative removal logic, e.g. to retain the original value. + * + * @param {string} section_id + * The configuration section ID + */ remove: function(section_id) { return this.map.data.unset( this.uciconfig || this.section.uciconfig || this.map.config, @@ -893,15 +1825,101 @@ var CBIAbstractValue = CBINode.extend({ } }); -var CBITypedSection = CBIAbstractSection.extend({ +/** + * @class TypedSection + * @memberof LuCI.form + * @augments LuCI.form.AbstractSection + * @hideconstructor + * @classdesc + * + * The `TypedSection` class maps all or - if `filter()` is overwritten - a + * subset of the underlying UCI configuration sections of a given type. + * + * Layout wise, the configuration section instances mapped by the section + * element (sometimes referred to as "section nodes") are stacked beneath + * each other in a single column, with an optional section remove button next + * to each section node and a section add button at the end, depending on the + * value of the `addremove` property. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [section()]{@link LuCI.form.Map#section}. + * + * @param {string} section_type + * The type of the UCI section to map. + * + * @param {string} [title] + * The title caption of the form section element. + * + * @param {string} [description] + * The description text of the form section element. + */ +var CBITypedSection = CBIAbstractSection.extend(/** @lends LuCI.form.TypedSection.prototype */ { __name__: 'CBI.TypedSection', + /** + * If set to `true`, the user may add or remove instances from the form + * section widget, otherwise only preexisting sections may be edited. + * The default is `false`. + * + * @name LuCI.form.TypedSection.prototype#addremove + * @type boolean + * @default false + */ + + /** + * If set to `true`, mapped section instances are treated as anonymous + * UCI sections, which means that section instance elements will be + * rendered without title element and that no name is required when adding + * new sections. The default is `false`. + * + * @name LuCI.form.TypedSection.prototype#anonymous + * @type boolean + * @default false + */ + + /** + * When set to `true`, instead of rendering section instances one below + * another, treat each instance as separate tab pane and render a tab menu + * at the top of the form section element, allowing the user to switch + * among instances. The default is `false`. + * + * @name LuCI.form.TypedSection.prototype#tabbed + * @type boolean + * @default false + */ + + /** + * Override the caption used for the section add button at the bottom of + * the section form element. If set to a string, it will be used as-is, + * if set to a function, the function will be invoked and its return value + * is used as caption, after converting it to a string. If this property + * is not set, the default is `Add`. + * + * @name LuCI.form.TypedSection.prototype#addbtntitle + * @type string|function + * @default null + */ + + /** + * Override the UCI configuration name to read the section IDs from. By + * default, the configuration name is inherited from the parent `Map`. + * By setting this property, a deviating configuration may be specified. + * The default is `null`, means inheriting from the parent form. + * + * @name LuCI.form.TypedSection.prototype#uciconfig + * @type string + * @default null + */ + + /** @override */ cfgsections: function() { return this.map.data.sections(this.uciconfig || this.map.config, this.sectiontype) .map(function(s) { return s['.name'] }) .filter(L.bind(this.filter, this)); }, + /** @private */ handleAdd: function(ev, name) { var config_name = this.uciconfig || this.map.config; @@ -909,6 +1927,7 @@ var CBITypedSection = CBIAbstractSection.extend({ return this.map.save(null, true); }, + /** @private */ handleRemove: function(section_id, ev) { var config_name = this.uciconfig || this.map.config; @@ -916,6 +1935,7 @@ var CBITypedSection = CBIAbstractSection.extend({ return this.map.save(null, true); }, + /** @private */ renderSectionAdd: function(extra_class) { if (!this.addremove) return E([]); @@ -962,6 +1982,7 @@ var CBITypedSection = CBIAbstractSection.extend({ return createEl; }, + /** @private */ renderSectionPlaceholder: function() { return E([ E('em', _('This section contains no values yet')), @@ -969,6 +1990,7 @@ var CBITypedSection = CBIAbstractSection.extend({ ]); }, + /** @private */ renderContents: function(cfgsections, nodes) { var section_id = null, config_name = this.uciconfig || this.map.config, @@ -1018,6 +2040,7 @@ var CBITypedSection = CBIAbstractSection.extend({ return sectionEl; }, + /** @override */ render: function() { var cfgsections = this.cfgsections(), renderTasks = []; @@ -1029,13 +2052,175 @@ var CBITypedSection = CBIAbstractSection.extend({ } }); -var CBITableSection = CBITypedSection.extend({ +/** + * @class TableSection + * @memberof LuCI.form + * @augments LuCI.form.TypedSection + * @hideconstructor + * @classdesc + * + * The `TableSection` class maps all or - if `filter()` is overwritten - a + * subset of the underlying UCI configuration sections of a given type. + * + * Layout wise, the configuration section instances mapped by the section + * element (sometimes referred to as "section nodes") are rendered as rows + * within an HTML table element, with an optional section remove button in the + * last column and a section add button below the table, depending on the + * value of the `addremove` property. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [section()]{@link LuCI.form.Map#section}. + * + * @param {string} section_type + * The type of the UCI section to map. + * + * @param {string} [title] + * The title caption of the form section element. + * + * @param {string} [description] + * The description text of the form section element. + */ +var CBITableSection = CBITypedSection.extend(/** @lends LuCI.form.TableSection.prototype */ { __name__: 'CBI.TableSection', + /** + * If set to `true`, the user may add or remove instances from the form + * section widget, otherwise only preexisting sections may be edited. + * The default is `false`. + * + * @name LuCI.form.TableSection.prototype#addremove + * @type boolean + * @default false + */ + + /** + * If set to `true`, mapped section instances are treated as anonymous + * UCI sections, which means that section instance elements will be + * rendered without title element and that no name is required when adding + * new sections. The default is `false`. + * + * @name LuCI.form.TableSection.prototype#anonymous + * @type boolean + * @default false + */ + + /** + * Override the caption used for the section add button at the bottom of + * the section form element. If set to a string, it will be used as-is, + * if set to a function, the function will be invoked and its return value + * is used as caption, after converting it to a string. If this property + * is not set, the default is `Add`. + * + * @name LuCI.form.TableSection.prototype#addbtntitle + * @type string|function + * @default null + */ + + /** + * Override the per-section instance title caption shown in the first + * column of the table unless `anonymous` is set to true. If set to a + * string, it will be used as `String.format()` pattern with the name of + * the underlying UCI section as first argument, if set to a function, the + * function will be invoked with the section name as first argument and + * its return value is used as caption, after converting it to a string. + * If this property is not set, the default is the name of the underlying + * UCI configuration section. + * + * @name LuCI.form.TableSection.prototype#sectiontitle + * @type string|function + * @default null + */ + + /** + * Override the per-section instance modal popup title caption shown when + * clicking the `More…` button in a section specifying `max_cols`. If set + * to a string, it will be used as `String.format()` pattern with the name + * of the underlying UCI section as first argument, if set to a function, + * the function will be invoked with the section name as first argument and + * its return value is used as caption, after converting it to a string. + * If this property is not set, the default is the name of the underlying + * UCI configuration section. + * + * @name LuCI.form.TableSection.prototype#modaltitle + * @type string|function + * @default null + */ + + /** + * Override the UCI configuration name to read the section IDs from. By + * default, the configuration name is inherited from the parent `Map`. + * By setting this property, a deviating configuration may be specified. + * The default is `null`, means inheriting from the parent form. + * + * @name LuCI.form.TableSection.prototype#uciconfig + * @type string + * @default null + */ + + /** + * Specify a maximum amount of columns to display. By default, one table + * column is rendered for each child option of the form section element. + * When this option is set to a positive number, then no more columns than + * the given amount are rendered. When the number of child options exceeds + * the specified amount, a `More…` button is rendered in the last column, + * opening a modal dialog presenting all options elements in `NamedSection` + * style when clicked. + * + * @name LuCI.form.TableSection.prototype#max_cols + * @type number + * @default null + */ + + /** + * If set to `true`, alternating `cbi-rowstyle-1` and `cbi-rowstyle-2` CSS + * classes are added to the table row elements. Not all LuCI themes + * implement these row style classes. The default is `false`. + * + * @name LuCI.form.TableSection.prototype#rowcolors + * @type boolean + * @default false + */ + + /** + * Enables a per-section instance row `Edit` button which triggers a certain + * action when clicked. If set to a string, the string value is used + * as `String.format()` pattern with the name of the underlying UCI section + * as first format argument. The result is then interpreted as URL which + * LuCI will navigate to when the user clicks the edit button. + * + * If set to a function, this function will be registered as click event + * handler on the rendered edit button, receiving the section instance + * name as first and the DOM click event as second argument. + * + * @name LuCI.form.TableSection.prototype#extedit + * @type string|function + * @default null + */ + + /** + * If set to `true`, a sort button is added to the last column, allowing + * the user to reorder the section instances mapped by the section form + * element. + * + * @name LuCI.form.TableSection.prototype#sortable + * @type boolean + * @default false + */ + + /** + * The `TableSection` implementation does not support option tabbing, so + * its implementation of `tab()` will always throw an exception when + * invoked. + * + * @override + * @throws Throws an exception when invoked. + */ tab: function() { throw 'Tabs are not supported by TableSection'; }, + /** @private */ renderContents: function(cfgsections, nodes) { var section_id = null, config_name = this.uciconfig || this.map.config, @@ -1106,6 +2291,7 @@ var CBITableSection = CBITypedSection.extend({ return sectionEl; }, + /** @private */ renderHeaderRows: function(max_cols, has_action) { var has_titles = false, has_descriptions = false, @@ -1189,6 +2375,7 @@ var CBITableSection = CBITypedSection.extend({ return trEls; }, + /** @private */ renderRowActions: function(section_id, more_label) { var config_name = this.uciconfig || this.map.config; @@ -1253,10 +2440,12 @@ var CBITableSection = CBITypedSection.extend({ return tdEl; }, + /** @private */ handleDragInit: function(ev) { scope.dragState = { node: ev.target }; }, + /** @private */ handleDragStart: function(ev) { if (!scope.dragState || !scope.dragState.node.classList.contains('drag-handle')) { scope.dragState = null; @@ -1269,6 +2458,7 @@ var CBITableSection = CBITypedSection.extend({ ev.target.style.opacity = 0.4; }, + /** @private */ handleDragOver: function(ev) { var n = scope.dragState.targetNode, r = scope.dragState.rect, @@ -1288,16 +2478,19 @@ var CBITableSection = CBITypedSection.extend({ return false; }, + /** @private */ handleDragEnter: function(ev) { scope.dragState.rect = ev.currentTarget.getBoundingClientRect(); scope.dragState.targetNode = ev.currentTarget; }, + /** @private */ handleDragLeave: function(ev) { ev.currentTarget.classList.remove('drag-over-above'); ev.currentTarget.classList.remove('drag-over-below'); }, + /** @private */ handleDragEnd: function(ev) { var n = ev.target; @@ -1310,6 +2503,7 @@ var CBITableSection = CBITypedSection.extend({ }); }, + /** @private */ handleDrop: function(ev) { var s = scope.dragState; @@ -1337,10 +2531,12 @@ var CBITableSection = CBITypedSection.extend({ return false; }, + /** @private */ handleModalCancel: function(modalMap, ev) { return Promise.resolve(ui.hideModal()); }, + /** @private */ handleModalSave: function(modalMap, ev) { return modalMap.save() .then(L.bind(this.map.load, this.map)) @@ -1349,10 +2545,36 @@ var CBITableSection = CBITypedSection.extend({ .catch(function() {}); }, + /** + * Add further options to the per-section instanced modal popup. + * + * This function may be overwritten by user code to perform additional + * setup steps before displaying the more options modal which is useful to + * e.g. query additional data or to inject further option elements. + * + * The default implementation of this function does nothing. + * + * @abstract + * @param {LuCI.form.NamedSection} modalSection + * The `NamedSection` instance about to be rendered in the modal popup. + * + * @param {string} section_id + * The ID of the underlying UCI section the modal popup belongs to. + * + * @param {Event} ev + * The DOM event emitted by clicking the `More…` button. + * + * @returns {*|Promise<*>} + * Return values of this function are ignored but if a promise is returned, + * it is run to completion before the rendering is continued, allowing + * custom logic to perform asynchroneous work before the modal dialog + * is shown. + */ addModalOptions: function(modalSection, section_id, ev) { }, + /** @private */ renderMoreOptionsModal: function(section_id, ev) { var parent = this.map, title = parent.title, @@ -1416,11 +2638,80 @@ var CBITableSection = CBITypedSection.extend({ } }); -var CBIGridSection = CBITableSection.extend({ +/** + * @class GridSection + * @memberof LuCI.form + * @augments LuCI.form.TableSection + * @hideconstructor + * @classdesc + * + * The `GridSection` class maps all or - if `filter()` is overwritten - a + * subset of the underlying UCI configuration sections of a given type. + * + * A grid section functions similar to a {@link LuCI.form.TableSection} but + * supports tabbing in the modal overlay. Option elements added with + * [option()]{@link LuCI.form.GridSection#option} are shown in the table while + * elements added with [taboption()]{@link LuCI.form.GridSection#taboption} + * are displayed in the modal popup. + * + * Another important difference is that the table cells show a readonly text + * preview of the corresponding option elements by default, unless the child + * option element is explicitely made writable by setting the `editable` + * property to `true`. + * + * Additionally, the grid section honours a `modalonly` property of child + * option elements. Refer to the [AbstractValue]{@link LuCI.form.AbstractValue} + * documentation for details. + * + * Layout wise, a grid section looks mostly identical to table sections. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [section()]{@link LuCI.form.Map#section}. + * + * @param {string} section_type + * The type of the UCI section to map. + * + * @param {string} [title] + * The title caption of the form section element. + * + * @param {string} [description] + * The description text of the form section element. + */ +var CBIGridSection = CBITableSection.extend(/** @lends LuCI.form.GridSection.prototype */ { + /** + * Add an option tab to the section. + * + * The modal option elements of a grid section may be divided into multiple + * tabs to provide a better overview to the user. + * + * Before options can be moved into a tab pane, the corresponding tab + * has to be defined first, which is done by calling this function. + * + * Note that tabs are only effective in modal popups, options added with + * `option()` will not be assigned to a specific tab and are rendered in + * the table view only. + * + * @param {string} name + * The name of the tab to register. It may be freely chosen and just serves + * as an identifier to differentiate tabs. + * + * @param {string} title + * The human readable caption of the tab. + * + * @param {string} [description] + * An additional description text for the corresponding tab pane. It is + * displayed as text paragraph below the tab but before the tab pane + * contents. If omitted, no description will be rendered. + * + * @throws {Error} + * Throws an exeption if a tab with the same `name` already exists. + */ tab: function(name, title, description) { CBIAbstractSection.prototype.tab.call(this, name, title, description); }, + /** @private */ handleAdd: function(ev, name) { var config_name = this.uciconfig || this.map.config, section_id = this.map.data.add(config_name, this.sectiontype, name); @@ -1429,11 +2720,13 @@ var CBIGridSection = CBITableSection.extend({ return this.renderMoreOptionsModal(section_id); }, + /** @private */ handleModalSave: function(/* ... */) { return this.super('handleModalSave', arguments) .then(L.bind(function() { this.addedSection = null }, this)); }, + /** @private */ handleModalCancel: function(/* ... */) { var config_name = this.uciconfig || this.map.config; @@ -1445,10 +2738,12 @@ var CBIGridSection = CBITableSection.extend({ return this.super('handleModalCancel', arguments); }, + /** @private */ renderUCISection: function(section_id) { return this.renderOptions(null, section_id); }, + /** @private */ renderChildren: function(tab_name, section_id, in_table) { var tasks = [], index = 0; @@ -1465,6 +2760,7 @@ var CBIGridSection = CBITableSection.extend({ return Promise.all(tasks); }, + /** @private */ renderTextValue: function(section_id, opt) { var title = this.stripTags(opt.title).trim(), descr = this.stripTags(opt.description).trim(), @@ -1479,14 +2775,17 @@ var CBIGridSection = CBITableSection.extend({ }, (value != null) ? value : E('em', _('none'))); }, + /** @private */ renderHeaderRows: function(section_id) { return this.super('renderHeaderRows', [ NaN, true ]); }, + /** @private */ renderRowActions: function(section_id) { return this.super('renderRowActions', [ section_id, _('Edit') ]); }, + /** @override */ parse: function() { var section_ids = this.cfgsections(), tasks = []; @@ -1506,7 +2805,36 @@ var CBIGridSection = CBITableSection.extend({ } }); -var CBINamedSection = CBIAbstractSection.extend({ +/** + * @class NamedSection + * @memberof LuCI.form + * @augments LuCI.form.AbstractSection + * @hideconstructor + * @classdesc + * + * The `NamedSection` class maps exactly one UCI section instance which is + * specified when constructing the class instance. + * + * Layout and functionality wise, a named section is essentially a + * `TypedSection` which allows exactly one section node. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [section()]{@link LuCI.form.Map#section}. + * + * @param {string} section_id + * The name (ID) of the UCI section to map. + * + * @param {string} section_type + * The type of the UCI section to map. + * + * @param {string} [title] + * The title caption of the form section element. + * + * @param {string} [description] + * The description text of the form section element. + */ +var CBINamedSection = CBIAbstractSection.extend(/** @lends LuCI.form.NamedSection.prototype */ { __name__: 'CBI.NamedSection', __init__: function(map, section_id /*, ... */) { this.super('__init__', this.varargs(arguments, 2, map)); @@ -1514,10 +2842,40 @@ var CBINamedSection = CBIAbstractSection.extend({ this.section = section_id; }, + /** + * If set to `true`, the user may remove or recreate the sole mapped + * configuration instance from the form section widget, otherwise only a + * preexisting section may be edited. The default is `false`. + * + * @name LuCI.form.NamedSection.prototype#addremove + * @type boolean + * @default false + */ + + /** + * Override the UCI configuration name to read the section IDs from. By + * default, the configuration name is inherited from the parent `Map`. + * By setting this property, a deviating configuration may be specified. + * The default is `null`, means inheriting from the parent form. + * + * @name LuCI.form.NamedSection.prototype#uciconfig + * @type string + * @default null + */ + + /** + * The `NamedSection` class overwrites the generic `cfgsections()` + * implementation to return a one-element array containing the mapped + * section ID as sole element. User code should not normally change this. + * + * @returns {string[]} + * Returns a one-element array containing the mapped section ID. + */ cfgsections: function() { return [ this.section ]; }, + /** @private */ handleAdd: function(ev) { var section_id = this.section, config_name = this.uciconfig || this.map.config; @@ -1526,6 +2884,7 @@ var CBINamedSection = CBIAbstractSection.extend({ return this.map.save(null, true); }, + /** @private */ handleRemove: function(ev) { var section_id = this.section, config_name = this.uciconfig || this.map.config; @@ -1534,6 +2893,7 @@ var CBINamedSection = CBIAbstractSection.extend({ return this.map.save(null, true); }, + /** @private */ renderContents: function(data) { var ucidata = data[0], nodes = data[1], section_id = this.section, @@ -1581,6 +2941,7 @@ var CBINamedSection = CBIAbstractSection.extend({ return sectionEl; }, + /** @override */ render: function() { var config_name = this.uciconfig || this.map.config, section_id = this.section; @@ -1592,9 +2953,71 @@ var CBINamedSection = CBIAbstractSection.extend({ } }); -var CBIValue = CBIAbstractValue.extend({ +/** + * @class Value + * @memberof LuCI.form + * @augments LuCI.form.AbstractValue + * @hideconstructor + * @classdesc + * + * The `Value` class represents a simple one-line form input using the + * {@link LuCI.ui.Textfield} or - in case choices are added - the + * {@link LuCI.ui.Combobox} class as underlying widget. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {LuCI.form.AbstractSection} section + * The configuration section this option is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {string} option + * The name of the UCI option to map. + * + * @param {string} [title] + * The title caption of the option element. + * + * @param {string} [description] + * The description text of the option element. + */ +var CBIValue = CBIAbstractValue.extend(/** @lends LuCI.form.Value.prototype */ { __name__: 'CBI.Value', + /** + * If set to `true`, the field is rendered as password input, otherwise + * as plain text input. + * + * @name LuCI.form.Value.prototype#password + * @type boolean + * @default false + */ + + /** + * Set a placeholder string to use when the input field is empty. + * + * @name LuCI.form.Value.prototype#placeholder + * @type string + * @default null + */ + + /** + * Add a predefined choice to the form option. By adding one or more + * choices, the plain text input field is turned into a combobox widget + * which prompts the user to select a predefined choice, or to enter a + * custom value. + * + * @param {string} key + * The choice value to add. + * + * @param {Node|string} value + * The caption for the choice value. May be a DOM node, a document fragment + * or a plain text string. If omitted, the `key` value is used as caption. + */ value: function(key, val) { this.keylist = this.keylist || []; this.keylist.push(String(key)); @@ -1603,12 +3026,14 @@ var CBIValue = CBIAbstractValue.extend({ this.vallist.push(dom.elem(val) ? val : String(val != null ? val : key)); }, + /** @override */ render: function(option_index, section_id, in_table) { return Promise.resolve(this.cfgvalue(section_id)) .then(this.renderWidget.bind(this, section_id, option_index)) .then(this.renderFrame.bind(this, section_id, in_table, option_index)); }, + /** @private */ renderFrame: function(section_id, in_table, option_index, nodes) { var config_name = this.uciconfig || this.section.uciconfig || this.map.config, depend_list = this.transformDepList(section_id), @@ -1685,6 +3110,7 @@ var CBIValue = CBIAbstractValue.extend({ return optionEl; }, + /** @private */ renderWidget: function(section_id, option_index, cfgvalue) { var value = (cfgvalue != null) ? cfgvalue : this.default, choices = this.transformChoices(), @@ -1718,9 +3144,42 @@ var CBIValue = CBIAbstractValue.extend({ } }); -var CBIDynamicList = CBIValue.extend({ +/** + * @class DynamicList + * @memberof LuCI.form + * @augments LuCI.form.Value + * @hideconstructor + * @classdesc + * + * The `DynamicList` class represents a multi value widget allowing the user + * to enter multiple unique values, optionally selected from a set of + * predefined choices. It builds upon the {@link LuCI.ui.DynamicList} widget. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {LuCI.form.AbstractSection} section + * The configuration section this option is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {string} option + * The name of the UCI option to map. + * + * @param {string} [title] + * The title caption of the option element. + * + * @param {string} [description] + * The description text of the option element. + */ +var CBIDynamicList = CBIValue.extend(/** @lends LuCI.form.DynamicList.prototype */ { __name__: 'CBI.DynamicList', + /** @private */ renderWidget: function(section_id, option_index, cfgvalue) { var value = (cfgvalue != null) ? cfgvalue : this.default, choices = this.transformChoices(), @@ -1739,7 +3198,39 @@ var CBIDynamicList = CBIValue.extend({ }, }); -var CBIListValue = CBIValue.extend({ +/** + * @class ListValue + * @memberof LuCI.form + * @augments LuCI.form.Value + * @hideconstructor + * @classdesc + * + * The `ListValue` class implements a simple static HTML select element + * allowing the user to chose a single value from a set of predefined choices. + * It builds upon the {@link LuCI.ui.Select} widget. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {LuCI.form.AbstractSection} section + * The configuration section this option is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {string} option + * The name of the UCI option to map. + * + * @param {string} [title] + * The title caption of the option element. + * + * @param {string} [description] + * The description text of the option element. + */ +var CBIListValue = CBIValue.extend(/** @lends LuCI.form.ListValue.prototype */ { __name__: 'CBI.ListValue', __init__: function() { @@ -1748,6 +3239,15 @@ var CBIListValue = CBIValue.extend({ this.deplist = []; }, + /** + * Set the size attribute of the underlying HTML select element. + * + * @name LuCI.form.ListValue.prototype#size + * @type number + * @default null + */ + + /** @private */ renderWidget: function(section_id, option_index, cfgvalue) { var choices = this.transformChoices(); var widget = new ui.Select((cfgvalue != null) ? cfgvalue : this.default, choices, { @@ -1763,7 +3263,38 @@ var CBIListValue = CBIValue.extend({ }, }); -var CBIFlagValue = CBIValue.extend({ +/** + * @class FlagValue + * @memberof LuCI.form + * @augments LuCI.form.Value + * @hideconstructor + * @classdesc + * + * The `FlagValue` element builds upon the {@link LuCI.ui.Checkbox} widget to + * implement a simple checkbox element. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {LuCI.form.AbstractSection} section + * The configuration section this option is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {string} option + * The name of the UCI option to map. + * + * @param {string} [title] + * The title caption of the option element. + * + * @param {string} [description] + * The description text of the option element. + */ +var CBIFlagValue = CBIValue.extend(/** @lends LuCI.form.FlagValue.prototype */ { __name__: 'CBI.FlagValue', __init__: function() { @@ -1774,6 +3305,23 @@ var CBIFlagValue = CBIValue.extend({ this.default = this.disabled; }, + /** + * Sets the input value to use for the checkbox checked state. + * + * @name LuCI.form.FlagValue.prototype#enabled + * @type number + * @default 1 + */ + + /** + * Sets the input value to use for the checkbox unchecked state. + * + * @name LuCI.form.FlagValue.prototype#disabled + * @type number + * @default 0 + */ + + /** @private */ renderWidget: function(section_id, option_index, cfgvalue) { var widget = new ui.Checkbox((cfgvalue != null) ? cfgvalue : this.default, { id: this.cbid(section_id), @@ -1785,12 +3333,25 @@ var CBIFlagValue = CBIValue.extend({ return widget.render(); }, + /** + * Query the checked state of the underlying checkbox widget and return + * either the `enabled` or the `disabled` property value, depending on + * the checked state. + * + * @override + */ formvalue: function(section_id) { var elem = this.getUIElement(section_id), checked = elem ? elem.isChecked() : false; return checked ? this.enabled : this.disabled; }, + /** + * Query the checked state of the underlying checkbox widget and return + * either a localized `Yes` or `No` string, depending on the checked state. + * + * @override + */ textvalue: function(section_id) { var cval = this.cfgvalue(section_id); @@ -1800,6 +3361,7 @@ var CBIFlagValue = CBIValue.extend({ return (cval == this.enabled) ? _('Yes') : _('No'); }, + /** @override */ parse: function(section_id) { if (this.isActive(section_id)) { var fval = this.formvalue(section_id); @@ -1818,7 +3380,39 @@ var CBIFlagValue = CBIValue.extend({ }, }); -var CBIMultiValue = CBIDynamicList.extend({ +/** + * @class MultiValue + * @memberof LuCI.form + * @augments LuCI.form.DynamicList + * @hideconstructor + * @classdesc + * + * The `MultiValue` class is a modified variant of the `DynamicList` element + * which leverages the {@link LuCI.ui.Dropdown} widget to implement a multi + * select dropdown element. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {LuCI.form.AbstractSection} section + * The configuration section this option is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {string} option + * The name of the UCI option to map. + * + * @param {string} [title] + * The title caption of the option element. + * + * @param {string} [description] + * The description text of the option element. + */ +var CBIMultiValue = CBIDynamicList.extend(/** @lends LuCI.form.MultiValue.prototype */ { __name__: 'CBI.MultiValue', __init__: function() { @@ -1826,6 +3420,27 @@ var CBIMultiValue = CBIDynamicList.extend({ this.placeholder = _('-- Please choose --'); }, + /** + * Allows to specify the [display_items]{@link LuCI.ui.Dropdown.InitOptions} + * property of the underlying dropdown widget. If omitted, the value of + * the `size` property is used or `3` when `size` is unspecified as well. + * + * @name LuCI.form.MultiValue.prototype#display_size + * @type number + * @default null + */ + + /** + * Allows to specify the [dropdown_items]{@link LuCI.ui.Dropdown.InitOptions} + * property of the underlying dropdown widget. If omitted, the value of + * the `size` property is used or `-1` when `size` is unspecified as well. + * + * @name LuCI.form.MultiValue.prototype#dropdown_size + * @type number + * @default null + */ + + /** @private */ renderWidget: function(section_id, option_index, cfgvalue) { var value = (cfgvalue != null) ? cfgvalue : this.default, choices = this.transformChoices(); @@ -1845,11 +3460,80 @@ var CBIMultiValue = CBIDynamicList.extend({ }, }); -var CBITextValue = CBIValue.extend({ +/** + * @class TextValue + * @memberof LuCI.form + * @augments LuCI.form.Value + * @hideconstructor + * @classdesc + * + * The `TextValue` class implements a multi-line textarea input using + * {@link LuCI.ui.Textarea}. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {LuCI.form.AbstractSection} section + * The configuration section this option is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {string} option + * The name of the UCI option to map. + * + * @param {string} [title] + * The title caption of the option element. + * + * @param {string} [description] + * The description text of the option element. + */ +var CBITextValue = CBIValue.extend(/** @lends LuCI.form.TextValue.prototype */ { __name__: 'CBI.TextValue', + /** @ignore */ value: null, + /** + * Enforces the use of a monospace font for the textarea contents when set + * to `true`. + * + * @name LuCI.form.TextValue.prototype#monospace + * @type boolean + * @default false + */ + + /** + * Allows to specify the [cols]{@link LuCI.ui.Textarea.InitOptions} + * property of the underlying textarea widget. + * + * @name LuCI.form.TextValue.prototype#cols + * @type number + * @default null + */ + + /** + * Allows to specify the [rows]{@link LuCI.ui.Textarea.InitOptions} + * property of the underlying textarea widget. + * + * @name LuCI.form.TextValue.prototype#rows + * @type number + * @default null + */ + + /** + * Allows to specify the [wrap]{@link LuCI.ui.Textarea.InitOptions} + * property of the underlying textarea widget. + * + * @name LuCI.form.TextValue.prototype#wrap + * @type number + * @default null + */ + + /** @private */ renderWidget: function(section_id, option_index, cfgvalue) { var value = (cfgvalue != null) ? cfgvalue : this.default; @@ -1868,9 +3552,64 @@ var CBITextValue = CBIValue.extend({ } }); -var CBIDummyValue = CBIValue.extend({ +/** + * @class DummyValue + * @memberof LuCI.form + * @augments LuCI.form.Value + * @hideconstructor + * @classdesc + * + * The `DummyValue` element wraps an {@link LuCI.ui.Hiddenfield} widget and + * renders the underlying UCI option or default value as readonly text. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {LuCI.form.AbstractSection} section + * The configuration section this option is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {string} option + * The name of the UCI option to map. + * + * @param {string} [title] + * The title caption of the option element. + * + * @param {string} [description] + * The description text of the option element. + */ +var CBIDummyValue = CBIValue.extend(/** @lends LuCI.form.DummyValue.prototype */ { __name__: 'CBI.DummyValue', + /** + * Set an URL which is opened when clicking on the dummy value text. + * + * By setting this property, the dummy value text is wrapped in an `<a>` + * element with the property value used as `href` attribute. + * + * @name LuCI.form.DummyValue.prototype#href + * @type string + * @default null + */ + + /** + * Treat the UCI option value (or the `default` property value) as HTML. + * + * By default, the value text is HTML escaped before being rendered as + * text. In some cases it may be needed to actually interpret and render + * HTML contents as-is. When set to `true`, HTML escaping is disabled. + * + * @name LuCI.form.DummyValue.prototype#rawhtml + * @type boolean + * @default null + */ + + /** @private */ renderWidget: function(section_id, option_index, cfgvalue) { var value = (cfgvalue != null) ? cfgvalue : this.default, hiddenEl = new ui.Hiddenfield(value, { id: this.cbid(section_id) }), @@ -1888,13 +3627,99 @@ var CBIDummyValue = CBIValue.extend({ ]); }, + /** @override */ remove: function() {}, + + /** @override */ write: function() {} }); -var CBIButtonValue = CBIValue.extend({ +/** + * @class ButtonValue + * @memberof LuCI.form + * @augments LuCI.form.Value + * @hideconstructor + * @classdesc + * + * The `DummyValue` element wraps an {@link LuCI.ui.Hiddenfield} widget and + * renders the underlying UCI option or default value as readonly text. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {LuCI.form.AbstractSection} section + * The configuration section this option is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {string} option + * The name of the UCI option to map. + * + * @param {string} [title] + * The title caption of the option element. + * + * @param {string} [description] + * The description text of the option element. + */ +var CBIButtonValue = CBIValue.extend(/** @lends LuCI.form.ButtonValue.prototype */ { __name__: 'CBI.ButtonValue', + /** + * Override the rendered button caption. + * + * By default, the option title - which is passed as fourth argument to the + * constructor - is used as caption for the button element. When setting + * this property to a string, it is used as `String.format()` pattern with + * the underlying UCI section name passed as first format argument. When + * set to a function, it is invoked passing the section ID as sole argument + * and the resulting return value is converted to a string before being + * used as button caption. + * + * The default is `null`, means the option title is used as caption. + * + * @name LuCI.form.ButtonValue.prototype#inputtitle + * @type string|function + * @default null + */ + + /** + * Override the button style class. + * + * By setting this property, a specific `cbi-button-*` CSS class can be + * selected to influence the style of the resulting button. + * + * Suitable values which are implemented by most themes are `positive`, + * `negative` and `primary`. + * + * The default is `null`, means a neutral button styling is used. + * + * @name LuCI.form.ButtonValue.prototype#inputstyle + * @type string + * @default null + */ + + /** + * Override the button click action. + * + * By default, the underlying UCI option (or default property) value is + * copied into a hidden field tied to the button element and the save + * action is triggered on the parent form element. + * + * When this property is set to a function, it is invoked instead of + * performing the default actions. The handler function will receive the + * DOM click element as first and the underlying configuration section ID + * as second argument. + * + * @name LuCI.form.ButtonValue.prototype#onclick + * @type function + * @default null + */ + + /** @private */ renderWidget: function(section_id, option_index, cfgvalue) { var value = (cfgvalue != null) ? cfgvalue : this.default, hiddenEl = new ui.Hiddenfield(value, { id: this.cbid(section_id) }), @@ -1924,9 +3749,48 @@ var CBIButtonValue = CBIValue.extend({ } }); -var CBIHiddenValue = CBIValue.extend({ +/** + * @class HiddenValue + * @memberof LuCI.form + * @augments LuCI.form.Value + * @hideconstructor + * @classdesc + * + * The `HiddenValue` element wraps an {@link LuCI.ui.Hiddenfield} widget. + * + * Hidden value widgets used to be necessary in legacy code which actually + * submitted the underlying HTML form the server. With client side handling of + * forms, there are more efficient ways to store hidden state data. + * + * Since this widget has no visible content, the title and description values + * of this form element should be set to `null` as well to avoid a broken or + * distorted form layout when rendering the option element. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {LuCI.form.AbstractSection} section + * The configuration section this option is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {string} option + * The name of the UCI option to map. + * + * @param {string} [title] + * The title caption of the option element. + * + * @param {string} [description] + * The description text of the option element. + */ +var CBIHiddenValue = CBIValue.extend(/** @lends LuCI.form.HiddenValue.prototype */ { __name__: 'CBI.HiddenValue', + /** @private */ renderWidget: function(section_id, option_index, cfgvalue) { var widget = new ui.Hiddenfield((cfgvalue != null) ? cfgvalue : this.default, { id: this.cbid(section_id) @@ -1936,7 +3800,38 @@ var CBIHiddenValue = CBIValue.extend({ } }); -var CBIFileUpload = CBIValue.extend({ +/** + * @class FileUpload + * @memberof LuCI.form + * @augments LuCI.form.Value + * @hideconstructor + * @classdesc + * + * The `FileUpload` element wraps an {@link LuCI.ui.FileUpload} widget and + * offers the ability to browse, upload and select remote files. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {LuCI.form.AbstractSection} section + * The configuration section this option is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {string} option + * The name of the UCI option to map. + * + * @param {string} [title] + * The title caption of the option element. + * + * @param {string} [description] + * The description text of the option element. + */ +var CBIFileUpload = CBIValue.extend(/** @lends LuCI.form.FileUpload.prototype */ { __name__: 'CBI.FileSelect', __init__: function(/* ... */) { @@ -1948,6 +3843,67 @@ var CBIFileUpload = CBIValue.extend({ this.root_directory = '/etc/luci-uploads'; }, + /** + * Toggle display of hidden files. + * + * Display hidden files when rendering the remote directory listing. + * Note that this is merely a cosmetic feature, hidden files are always + * included in received remote file listings. + * + * The default is `false`, means hidden files are not displayed. + * + * @name LuCI.form.FileUpload.prototype#show_hidden + * @type boolean + * @default false + */ + + /** + * Toggle file upload functionality. + * + * When set to `true`, the underlying widget provides a button which lets + * the user select and upload local files to the remote system. + * Note that this is merely a cosmetic feature, remote upload access is + * controlled by the session ACL rules. + * + * The default is `true`, means file upload functionality is displayed. + * + * @name LuCI.form.FileUpload.prototype#enable_upload + * @type boolean + * @default true + */ + + /** + * Toggle remote file delete functionality. + * + * When set to `true`, the underlying widget provides a buttons which let + * the user delete files from remote directories. Note that this is merely + * a cosmetic feature, remote delete permissions are controlled by the + * session ACL rules. + * + * The default is `true`, means file removal buttons are displayed. + * + * @name LuCI.form.FileUpload.prototype#enable_remove + * @type boolean + * @default true + */ + + /** + * Specify the root directory for file browsing. + * + * This property defines the topmost directory the file browser widget may + * navigate to, the UI will not allow browsing directories outside this + * prefix. Note that this is merely a cosmetic feature, remote file access + * and directory listing permissions are controlled by the session ACL + * rules. + * + * The default is `/etc/luci-uploads`. + * + * @name LuCI.form.FileUpload.prototype#root_directory + * @type string + * @default /etc/luci-uploads + */ + + /** @private */ renderWidget: function(section_id, option_index, cfgvalue) { var browserEl = new ui.FileUpload((cfgvalue != null) ? cfgvalue : this.default, { id: this.cbid(section_id), @@ -1962,7 +3918,45 @@ var CBIFileUpload = CBIValue.extend({ } }); -var CBISectionValue = CBIValue.extend({ +/** + * @class SectionValue + * @memberof LuCI.form + * @augments LuCI.form.Value + * @hideconstructor + * @classdesc + * + * The `SectionValue` widget embeds a form section element within an option + * element container, allowing to nest form sections into other sections. + * + * @param {LuCI.form.Map|LuCI.form.JSONMap} form + * The configuration form this section is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {LuCI.form.AbstractSection} section + * The configuration section this option is added to. It is automatically passed + * by [option()]{@link LuCI.form.AbstractSection#option} or + * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the + * option to the section. + * + * @param {string} option + * The internal name of the option element holding the section. Since a section + * container element does not read or write any configuration itself, the name + * is only used internally and does not need to relate to any underlying UCI + * option name. + * + * @param {LuCI.form.AbstractSection} subsection_class + * The class to use for instantiating the nested section element. Note that + * the class value itself is expected here, not a class instance obtained by + * calling `new`. The given class argument must be a subclass of the + * `AbstractSection` class. + * + * @param {...*} [class_args] + * All further arguments are passed as-is to the subclass constructor. Refer + * to the corresponding class constructor documentations for details. + */ +var CBISectionValue = CBIValue.extend(/** @lends LuCI.form.SectionValue.prototype */ { __name__: 'CBI.ContainerValue', __init__: function(map, section, option, cbiClass /*, ... */) { this.super('__init__', [map, section, option]); @@ -1974,30 +3968,124 @@ var CBISectionValue = CBIValue.extend({ this.subsection.parentoption = this; }, + /** + * Access the embedded section instance. + * + * This property holds a reference to the instantiated nested section. + * + * @name LuCI.form.SectionValue.prototype#subsection + * @type LuCI.form.AbstractSection + * @readonly + */ + + /** @override */ load: function(section_id) { return this.subsection.load(); }, + /** @override */ parse: function(section_id) { return this.subsection.parse(); }, + /** @private */ renderWidget: function(section_id, option_index, cfgvalue) { return this.subsection.render(); }, + /** @private */ checkDepends: function(section_id) { this.subsection.checkDepends(); return CBIValue.prototype.checkDepends.apply(this, [ section_id ]); }, + /** + * Since the section container is not rendering an own widget, + * its `value()` implementation is a no-op. + * + * @override + */ + value: function() {}, + + /** + * Since the section container is not tied to any UCI configuration, + * its `write()` implementation is a no-op. + * + * @override + */ write: function() {}, + + /** + * Since the section container is not tied to any UCI configuration, + * its `remove()` implementation is a no-op. + * + * @override + */ remove: function() {}, + + /** + * Since the section container is not tied to any UCI configuration, + * its `cfgvalue()` implementation will always return `null`. + * + * @override + * @returns {null} + */ cfgvalue: function() { return null }, + + /** + * Since the section container is not tied to any UCI configuration, + * its `formvalue()` implementation will always return `null`. + * + * @override + * @returns {null} + */ formvalue: function() { return null } }); -return baseclass.extend({ +/** + * @class form + * @memberof LuCI + * @hideconstructor + * @classdesc + * + * The LuCI form class provides high level abstractions for creating creating + * UCI- or JSON backed configurations forms. + * + * To import the class in views, use `'require form'`, to import it in + * external JavaScript, use `L.require("form").then(...)`. + * + * A typical form is created by first constructing a + * {@link LuCI.form.Map} or {@link LuCI.form.JSONMap} instance using `new` and + * by subsequently adding sections and options to it. Finally + * [render()]{@link LuCI.form.Map#render} is invoked on the instance to + * assemble the HTML markup and insert it into the DOM. + * + * Example: + * + * <pre> + * 'use strict'; + * 'require form'; + * + * var m, s, o; + * + * m = new form.Map('example', 'Example form', + * 'This is an example form mapping the contents of /etc/config/example'); + * + * s = m.section(form.NamedSection, 'first_section', 'example', 'The first section', + * 'This sections maps "config example first_section" of /etc/config/example'); + * + * o = s.option(form.Flag, 'some_bool', 'A checkbox option'); + * + * o = s.option(form.ListValue, 'some_choice', 'A select element'); + * o.value('choice1', 'The first choice'); + * o.value('choice2', 'The second choice'); + * + * m.render().then(function(node) { + * document.body.appendChild(node); + * }); + * </pre> + */ +return baseclass.extend(/** @lends LuCI.form.prototype */ { Map: CBIMap, JSONMap: CBIJSONMap, AbstractSection: CBIAbstractSection, |