# Class: MultiValue

## LuCI .form. MultiValue

The `MultiValue` class is a modified variant of the `DynamicList` element which leverages the `LuCI.ui.Dropdown` widget to implement a multi select dropdown element.

#### new LuCI.form.MultiValue(form, section, option, title, description)

form.js, line 4808

  Name | Type | Description
  --- | --- | ---
  `form` | LuCI.form.Map | LuCI.form.JSONMap | The configuration form to which this section is added. It is automatically passed by `option()` or `taboption()` when adding the option to the section.
  `section` | LuCI.form.AbstractSection | The configuration section to which this option is added. It is automatically passed by `option()` or `taboption()` when adding the option to the section.
  `option` | string | The name of the UCI option to map.
  `title` | string | optional The title caption of the option element.
  `description` | string | optional The description text of the option element.

### Extends

- LuCI.form.DynamicList

### Members

#### createboolean

  Allows custom value entry in addition to those already specified.

  Default Value:
    - null

#### display_sizenumber

  Allows specifying the `display_items` property of the underlying dropdown widget. If omitted, the value of the `size` property is used or `3` when `size` is also unspecified.

  Default Value:
    - null

#### dropdown_sizenumber

  Allows specifying the `dropdown_items` property of the underlying dropdown widget. If omitted, the value of the `size` property is used or `-1` when `size` is also unspecified.

  Default Value:
    - null

#### allowduplicatesboolean

  Allows the underlying form controls to have multiple identical values.

  Default is `null`. If `true`, the underlying form value will not be checked for duplication.

  Default Value:
    - null

#### datatypestring

  Specifies a datatype constraint expression to validate input values against. Refer to `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.

  Default Value:
    - null

#### default*

  Sets a default value to use when the underlying UCI option is not set.

  Default Value:
    - null

#### editableboolean

  Mark the 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 a 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.

  Default Value:
    - false

#### modalonlyboolean

  Move the 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.

  Default Value:
    - null

#### onchangefunction

  Register a custom value change handler.

  If this property is set to a function, it is invoked whenever the value of the underlying UI input element changes.

  The invoked handler function will receive the DOM click element as first and the underlying configuration section ID as well as the input value as second and third argument respectively.

  Default Value:
    - null

#### optionalboolean

  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.

  Default Value:
    - false

#### passwordboolean

  If set to `true`, the field is rendered as a password input, otherwise as a plain text input.

  Default Value:
    - false

#### placeholderstring

  Set a placeholder string to use when the input field is empty.

  Default Value:
    - null

#### readonlyboolean

  Make option element readonly.

  This property defaults to the readonly state of the parent form element. When set to `true`, the underlying widget is rendered in disabled state, meaning its contents cannot be changed and the widget cannot be interacted with.

  Default Value:
    - false

#### retainboolean

  If set to `true`, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

  Default Value:
    - false

#### rmemptyboolean

  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.

  Default Value:
    - true

#### uciconfigstring

  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 of null means inherit from the parent form.

  Default Value:
    - null

#### ucioptionstring

  Override the UCI option name to read the value from.

  By default, the elements name, which is passed as the third argument to the constructor, is used as the UCI option name. By setting this property, a deviating UCI option may be specified.

  The default of null means use the option element name.

  Default Value:
    - null

#### ucisectionstring

  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 of null means inherit from the parent section.

  Default Value:
    - null

#### validatefunction

  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 a validation error message.

  If the user entered input does not pass the validation function, the option element is marked as invalid.

  Default Value:
    - null

#### widthnumber string

  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.

  Default Value:
    - null

### Methods

#### inherited append(obj)

form.js, line 219

  Add another form element as children to this element.

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

#### inherited cbid(section_id){string}

form.js, line 1766

  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.

  Name | Type | Description
  --- | --- | ---
  `section_id` | string | The configuration section ID

  ##### Throws:

  Throws a `TypeError` exception when no `section_id` was specified.

  Type
    TypeError

  ##### Returns:

  Type | Description
  --- | ---
  string | Returns the element ID.

#### inherited cfgvalue(section_id){*}

form.js, line 1840

  Query the underlying configuration value.

  The default implementation of this method returns the cached return value of `load()`. It may be overridden by user code to obtain the configuration value in a different way.

  Name | Type | Description
  --- | --- | ---
  `section_id` | string | The configuration section ID

  ##### Throws:

  Throws a `TypeError` exception when no `section_id` was specified.

  Type
    TypeError

  ##### Returns:

  Type | Description
  --- | ---
  * | Returns the configuration value.

#### inherited depends(field, value)

form.js, line 1647

  Add a dependency constraint to the option.

  Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

  Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a dot is specified, it refers to an option within the same configuration section. If specified as `configname.sectionid.optionname`, 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:

  - `!reverse`
    Invert the dependency, instead of requiring another option to be equal to the dependency value, that option should not be equal.
  - `!contains`
    Instead of requiring an exact match, the dependency is considered satisfied when the dependency value is contained within the option value.
  - `!default`
    The dependency is always satisfied

  Examples:

  - `opt.depends("foo", "test")`
    Require the value of `foo` to be `test`.
  - `opt.depends({ foo: "test" })`
    Equivalent to the previous example.
  - `opt.depends({ foo: /test/ })`
    Require the value of `foo` to match the regular expression `/test/`.
  - `opt.depends({ foo: "test", bar: "qrx" })`
    Require the value of `foo` to be `test` and the value of `bar` to be `qrx`.
  - `opt.depends({ foo: "test" })
    opt.depends({ bar: "qrx" })`
    Require either `foo` to be set to `test`, or the `bar` option to be `qrx`.
  - `opt.depends("test.section1.foo", "bar")`
    Require the "foo" form option within the "section1" section to be set to "bar".
  - `opt.depends({ foo: "test", "!contains": true })`
    Require the "foo" option value to contain the substring "test".

  Name | Type | Description
  --- | --- | ---
  `field` | string | Object.<string, (string|RegExp)> | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).
  `value` | string | RegExp | optional When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

#### inherited formvalue(section_id){*}

form.js, line 1868

  Query the current form input value.

  The default implementation of this method returns the current input value of the underlying `LuCI.ui` widget. It may be overridden by user code to handle input values differently.

  Name | Type | Description
  --- | --- | ---
  `section_id` | string | The configuration section ID

  ##### Throws:

  Throws a `TypeError` exception when no `section_id` was specified.

  Type
    TypeError

  ##### Returns:

  Type | Description
  --- | ---
  * | Returns the current input value.

#### inherited getUIElement(section_id){LuCI.ui.AbstractElement|null}

form.js, line 1817

  Obtain the underlying `LuCI.ui` element instance.

  Name | Type | Description
  --- | --- | ---
  `section_id` | string | The configuration section ID

  ##### Throws:

  Throws a `TypeError` exception when no `section_id` was specified.

  Type
    TypeError

  ##### Returns:

  Type | Description
  --- | ---
  LuCI.ui.AbstractElement | null | Returns the `LuCI.ui` element instance or `null` in case the form option implementation does not use `LuCI.ui` widgets.

#### inherited getValidationError(section_id){string}

form.js, line 1986

  Returns the current validation error for this input.

  Name | Type | Description
  --- | --- | ---
  `section_id` | string | The configuration section ID

  ##### Returns:

  Type | Description
  --- | ---
  string | The validation error at this time

#### inherited isActive(section_id){boolean}

form.js, line 2004

  Test whether the option element is currently active.

  An element is active when it is not hidden due to unsatisfied dependency constraints.

  Name | Type | Description
  --- | --- | ---
  `section_id` | string | The configuration section ID

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns `true` if the option element currently is active, otherwise it returns `false`.

#### inherited isValid(section_id){boolean}

form.js, line 1972

  Test whether the input value is currently valid.

  Name | Type | Description
  --- | --- | ---
  `section_id` | string | The configuration section ID

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns `true` if the input value currently is valid, otherwise it returns `false`.

#### inherited load(section_id){*|Promise.<*>}

form.js, line 1794

  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 overridden by user code to load data from non-standard sources.

  Name | Type | Description
  --- | --- | ---
  `section_id` | string | The configuration section ID

  ##### Throws:

  Throws a `TypeError` exception when no `section_id` was specified.

  Type
    TypeError

  ##### Returns:

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

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

form.js, line 2045

  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.

  Name | Type | Description
  --- | --- | ---
  `section_id` | string | The configuration section ID

  ##### Returns:

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

#### inherited remove(section_id)

form.js, line 2125

  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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

  Name | Type | Description
  --- | --- | ---
  `section_id` | string | The configuration section ID

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

form.js, line 296

  Strip any HTML tags from the given input string, and decode HTML entities.

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

  ##### Returns:

  Type | Description
  --- | ---
  string | The cleaned input string with HTML tags removed, and HTML entities decoded.

#### inherited textvalue(section_id){string}

form.js, line 1892

  Obtain a textual input representation.

  The default implementation of this method returns the HTML-escaped current input value of the underlying `LuCI.ui` widget. User code or specific option element implementations may override this function to apply a different logic, e.g. to return `Yes` or `No` depending on the checked state of checkbox elements.

  Name | Type | Description
  --- | --- | ---
  `section_id` | string | The configuration section ID

  ##### Throws:

  Throws a `TypeError` exception when no `section_id` was specified.

  Type
    TypeError

  ##### Returns:

  Type | Description
  --- | ---
  string | Returns the text representation of the current input value.

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

form.js, line 335

  Format the given named property as a title string.

  This function looks up the given named property and formats its value suitable for use as an 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.

#### inherited value(key, val)

form.js, line 4086

  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.

  Name | Type | Description
  --- | --- | ---
  `key` | string | The choice value to add.
  `val` | Node | string | 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 a caption.

#### inherited write(section_id, formvalue)

form.js, line 2102

  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()`.

  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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

  Name | Type | Description
  --- | --- | ---
  `section_id` | string | The configuration section ID
  `formvalue` | string | Array.<string> | The input value to write.