LuCI.form. NamedSection

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.

Source

Extends

Members

(readonly) parentoption :LuCI.form.AbstractValue

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.

Type:
Inherited From
Source

(static) addremove :boolean

Set to true, the user may remove or recreate the sole mapped configuration instance from the form section widget, otherwise only a pre-existing section may be edited. The default is false.

Type:
  • boolean
Default Value
  • false
Source

(static) hidetitle :boolean

If set to true, the title caption of the form section element which is normally rendered before the start of the section content will not be rendered in the UI. The default is false, meaning that the title is rendered.

Type:
  • boolean
Default Value
  • false
Source

(static) uciconfig :string

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

Type:
  • string
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cfgsections() → {Array.<string>}

The NamedSection class overrides the generic cfgsections() implementation to return a one-element array containing the mapped section ID as a sole element. User code should not normally change this.

Overrides
Source
Returns:

Returns a one-element array containing the mapped section ID.

Type: 
Array.<string>

cfgvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query underlying option configuration values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the configuration values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the configuration value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding configuration values or just a single configuration value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

(abstract) filter(section_id) → {boolean}

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 override this function with custom implementations.

Parameters:
NameTypeDescription
section_idstring

The UCI section ID to test.

Inherited From
Source
Returns:

Returns true when the given UCI section ID should be handled and false when it should be ignored.

Type: 
boolean

formvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query the underlying option widget input values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the widget input values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the widget input value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

getOption(optionopt) → {null|LuCI.form.AbstractValue|Object.<string, LuCI.form.AbstractValue>}

Obtain underlying option objects.

This function is sensitive to the amount of arguments passed to it; if no option name is specified, all options within this section are returned as a dictionary.

If an option name is supplied, this function returns the matching LuCI.form.AbstractValue instance only.

Parameters:
NameTypeAttributesDescription
optionstring<optional>

The name of the option object to obtain

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding option instance objects or just a single object instance value, depending on the amount of passed arguments.

Type: 
null | LuCI.form.AbstractValue | Object.<string, LuCI.form.AbstractValue>

getUIElement(section_id, optionopt) → {null|LuCI.ui.AbstractElement|Object.<string, (null|LuCI.ui.AbstractElement)>}

Obtain underlying option LuCI.ui widget instances.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the LuCI.ui widget instances of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the LuCI.ui widget instance value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | LuCI.ui.AbstractElement | Object.<string, (null|LuCI.ui.AbstractElement)>

load() → {Promise.<void>}

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.

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

option(optionclass, cbiClass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to the section.

Note that taboption() should be used instead if this form section element uses tabs.

Parameters:
NameTypeAttributesDescription
optionclassLuCI.form.AbstractValue

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 derived from AbstractSection.

cbiClassobject

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

args*<repeatable>

argument array

Inherited From
Source
Throws:

Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

Type
TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

parse() → {Promise.<void>}

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 unsatisfied dependencies are skipped.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been parsed. The returned promise is rejected if any parsed values do not meet the validation constraints of their respective elements.

Type: 
Promise.<void>

render() → {Node|Promise.<Node>}

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.

Overrides
Source
Returns:

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.

Type: 
Node | Promise.<Node>

stripTags(s) → {string}

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

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

tab(name, title, descriptionopt)

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.

Parameters:
NameTypeAttributesDescription
namestring

The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs.

titlestring

The human readable caption of the tab.

descriptionstring<optional>

An additional description text for the corresponding tab pane. It is displayed as a text paragraph below the tab but before the tab pane contents. If omitted, no description will be rendered.

Inherited From
Source
Throws:

Throws an exception if a tab with the same name already exists.

Type
Error

taboption(tabName, optionclass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to a tab of the section.

Parameters:
NameTypeAttributesDescription
tabNamestring

The name of the section tab to add the option element to.

optionclassLuCI.form.AbstractValue

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 derived from AbstractSection.

args*<repeatable>

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

Inherited From
Source
Throws:

  • Throws a ReferenceError exception when the given tab name does not exist.

    Type
    ReferenceError

  • Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

    Type
    TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

titleFn(attr, …args) → {string|null}

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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

The formatted title string or null if the property did not exist or was neither a string nor a function.

Type: 
string | null