# Class: Map

## LuCI .form. Map

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.

#### new LuCI.form.Map(config, title, description)

form.js, line 338

  Name | Type | Description
  --- | --- | ---
  `config` | string | The UCI configuration to map. It is automatically loaded along when the resulting map instance.
  `title` | string | optional 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.
  `description` | string | optional 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.

### Extends

- LuCI.form.AbstractElement

### Members

#### readonlyboolean

  Toggle readonly state of the form.

  If set to `true`, the Map instance is marked readonly and any form option elements added to it will inherit the readonly state.

  If left unset, the Map will test the access permission of the primary uci configuration upon loading and mark the form readonly if no write permissions are granted.

### Methods

#### inherited append(element)

form.js, line 210

  Add another form element as children to this element.

  Name | Type | Description
  --- | --- | ---
  `element` | AbstractElement | The form element to add.

#### chain(config)

form.js, line 479

  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.

  Name | Type | Description
  --- | --- | ---
  `config` | string | 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.

#### findElement(selector_or_attrname, attrvalue){Node|null}

form.js, line 461

  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.

  Name | Type | Description
  --- | --- | ---
  `selector_or_attrname` | string | 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.
  `attrvalue` | string | optional In case the function is invoked with two parameters, this argument specifies the attribute value to match.

  ##### Throws:

  Throws an `InternalError` if more than two function parameters are passed.

  Type
    InternalError

  ##### Returns:

  Type | Description
  --- | ---
  Node | null | Returns the first found DOM node or `null` if no element matched.

#### findElements(selector_or_attrname, attrvalue){NodeList}

form.js, line 418

  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.

  Name | Type | Description
  --- | --- | ---
  `selector_or_attrname` | string | 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.
  `attrvalue` | string | optional In case the function is invoked with two parameters, this argument specifies the attribute value to match.

  ##### Throws:

  Throws an `InternalError` if more than two function parameters are passed.

  Type
    InternalError

  ##### Returns:

  Type | Description
  --- | ---
  NodeList | Returns a (possibly empty) DOM `NodeList` containing the found DOM nodes.

#### load(){Promise.<void>}

form.js, line 533

  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:

  Type | Description
  --- | ---
  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.

#### lookupOption(name_or_id, section_id, config){Array.<LuCI.form.AbstractValue, string>|null}

form.js, line 702

  Find a form option element instance.

  Name | Type | Description
  --- | --- | ---
  `name_or_id` | string | The name or the full ID of the option element to look up.
  `section_id` | string | optional The ID of the UCI section containing the option to look up. May be omitted if a full ID is passed as first argument.
  `config` | string | optional The name of the UCI configuration the option instance is belonging to. Defaults to the main UCI configuration of the map if omitted.

  ##### Returns:

  Type | Description
  --- | ---
  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.

#### parse(){Promise.<void>}

form.js, line 563

  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:

  Type | Description
  --- | ---
  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.

#### render(){Promise.<Node>}

form.js, line 634

  Render the form markup.

  ##### Returns:

  Type | Description
  --- | ---
  Promise.<Node> | Returns a promise resolving to the toplevel form DOM node once the rendering is complete.

#### reset(){Promise.<Node>}

form.js, line 623

  Reset the form by re-rendering its contents. This will revert all unsaved user inputs to their initial form state.

  ##### Returns:

  Type | Description
  --- | ---
  Promise.<Node> | Returns a promise resolving to the toplevel form DOM node once the re-rendering is complete.

#### save(cb, silent){Promise.<void>}

form.js, line 593

  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.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `cb` | function |  | optional 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.
  `silent` | boolean | false | optional If set to `true`, trigger an alert message to the user in case saving the form data failes. Otherwise fail silently.

  ##### Returns:

  Type | Description
  --- | ---
  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.

#### section(sectionclass, classargs){LuCI.form.AbstractSection}

form.js, line 511

  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.

  Name | Type | Description
  --- | --- | ---
  `sectionclass` | LuCI.form.AbstractSection | 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`.
  `classargs` | string | repeatable 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:

  Type | Description
  --- | ---
  LuCI.form.AbstractSection | Returns the instantiated section class instance.

#### inherited stripTags(input){string}

form.js, line 286

  Strip any HTML tags from the given input string.

  Name | Type | Description
  --- | --- | ---
  `input` | string | The input string to clean.

  ##### Returns:

  Type | Description
  --- | ---
  string | The cleaned input string with HTML removes removed.

#### inherited titleFn(property, fmt_args){string|null}

form.js, line 320

  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.

  Name | Type | Description
  --- | --- | ---
  `property` | string | The name of the element property to use.
  `fmt_args` | * | repeatable Extra values to format the title string with.

  ##### Returns:

  Type | Description
  --- | ---
  string | null | The formatted title string or `null` if the property did not exist or was neither a string nor a function.