# Class: ui

## LuCI. ui

Provides high level UI helper functionality. To import the class in views, use `'require ui'`, to import it in external JavaScript, use `L.require("ui").then(...)`.

#### new LuCI.ui()

ui.js, line 3108

### Classes

AbstractElement
changes
Checkbox
Combobox
ComboButton
Dropdown
DynamicList
FileUpload
Hiddenfield
menu
Select
tabs
Textarea
Textfield

### Methods

#### addNotification(title, contents, classes){Node}

ui.js, line 3289

  Add a notification banner at the top of the current view.

  A notification banner is an alert message usually displayed at the top of the current view, spanning the entire availibe width. Notification banners will stay in place until dismissed by the user. Multiple banners may be shown at the same time.

  Additional CSS class names may be passed to influence the appearence of the banner. Valid values for the classes depend on the underlying theme.

  Name | Type | Description
  --- | --- | ---
  `title` | string | optional The title of the notification banner. If `null`, no title element will be rendered.
  `contents` | * | The contents to add to the notification banner. This should be a DOM node or a document fragment in most cases. The value is passed as-is to the `dom.content()` function - refer to its documentation for applicable values.
  `classes` | string | optional repeatable A number of extra CSS class names which are set on the notification banner element.

  See:
    - LuCI.dom.content

  ##### Returns:

  Type | Description
  --- | ---
  Node | Returns a DOM Node representing the notification banner element.

#### addValidator(field, type, optional, vfunc, events){function}

ui.js, line 4366

  Add validation constraints to an input element.

  Compile the given type expression and optional validator function into a validation function and bind it to the specified input element events.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `field` | Node |  | The DOM input element node to bind the validation constraints to.
  `type` | string |  | The datatype specification to describe validation constraints. Refer to the `LuCI.validation` class documentation for details.
  `optional` | boolean | false | optional Specifies whether empty values are allowed (`true`) or not (`false`). If an input element is not marked optional it must not be empty, otherwise it will be marked as invalid.
  `vfunc` | function |  | optional Specifies a custom validation function which is invoked after the other validation constraints are applied. The validation must return `true` to accept the passed value. Any other return type is converted to a string and treated as validation error message.
  `events` | string | blur, keyup | optional repeatable The list of events to bind. Each received event will trigger a field validation. If omitted, the `keyup` and `blur` events are bound by default.

  See:
    - LuCI.validation

  ##### Returns:

  Type | Description
  --- | ---
  function | Returns the compiled validator function which can be used to manually trigger field validation or to bind it to further events.

#### awaitReconnect(hosts)

ui.js, line 3913

  Wait for device to come back online and reconnect to it.

  Poll each given hostname or IP address and navigate to it as soon as one of the addresses becomes reachable.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `hosts` | string | [window.location.host] | optional repeatable The list of IP addresses and host names to check for reachability. If omitted, the current value of `window.location.host` is used by default.

#### createHandlerFn(ctx, fn, extra_args){function|null}

ui.js, line 4417

  Create a pre-bound event handler function.

  Generate and bind a function suitable for use in event handlers. The generated function automatically disables the event source element and adds an active indication to it by adding appropriate CSS classes.

  It will also await any promises returned by the wrapped function and re-enable the source element after the promises ran to completion.

  Name | Type | Description
  --- | --- | ---
  `ctx` | * | The `this` context to use for the wrapped function.
  `fn` | function | string | Specifies the function to wrap. In case of a function value, the function is used as-is. If a string is specified instead, it is looked up in `ctx` to obtain the function to wrap. In both cases the bound function will be invoked with `ctx` as `this` context
  `extra_args` | * | repeatable Any further parameter as passed as-is to the bound event handler function in the same order as passed to `createHandlerFn()`.

  ##### Returns:

  Type | Description
  --- | ---
  function | null | Returns the pre-bound handler function which is suitable to be passed to `addEventListener()`. Returns `null` if the given `fn` argument is a string which could not be found in `ctx` or if `ctx[fn]` is not a valid function value.

#### hideIndicator(id){boolean}

ui.js, line 3409

  Remove an header area indicator.

  This function removes the given indicator label from the header indicator area. When the given indicator is not found, this function does nothing.

  Name | Type | Description
  --- | --- | ---
  `id` | string | The ID of the indicator to remove.

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns `true` when the indicator has been removed or `false` when the requested indicator was not found.

#### hideModal()

ui.js, line 3200

  Close the open modal overlay dialog.

  This function will close an open modal dialog and restore the normal view behaviour. It has no effect if no modal dialog is currently open.

  Note that this function is stand-alone, it does not rely on `this` and will not invoke other class functions so it suitable to be used as event handler as-is without the need to bind it first.

#### instantiateView(path){Promise.<LuCI.view>}

ui.js, line 4460

  Load specified view class path and set it up.

  Transforms the given view path into a class name, requires it using `LuCI.require()` and asserts that the resulting class instance is a descendant of `LuCI.view`.

  By instantiating the view class, its corresponding contents are rendered and included into the view area. Any runtime errors are catched and rendered using `LuCI.error()`.

  Name | Type | Description
  --- | --- | ---
  `path` | string | The view path to render.

  ##### Returns:

  Type | Description
  --- | ---
  Promise.<LuCI.view> | Returns a promise resolving to the loaded view instance.

#### itemlist(node, items, separators){Node}

ui.js, line 3452

  Formats a series of label/value pairs into list-like markup.

  This function transforms a flat array of alternating label and value elements into a list-like markup, using the values in `separators` as separators and appends the resulting nodes to the given parent DOM node.

  Each label is suffixed with `:` and wrapped into a `<strong>` tag, the `<strong>` element and the value corresponding to the label are subsequently wrapped into a `<span class="nowrap">` element.

  The resulting `<span>` element tuples are joined by the given separators to form the final markup which is appened to the given parent DOM node.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `node` | Node |  | The parent DOM node to append the markup to. Any previous child elements will be removed.
  `items` | Array.<*> |  | An alternating array of labels and values. The label values will be converted to plain strings, the values are used as-is and may be of any type accepted by `LuCI.dom.content()`.
  `separators` | * | Array.<*> | [E('br')] | optional A single value or an array of separator values to separate each label/value pair with. The function will cycle through the separators when joining the pairs. If omitted, the default separator is a sole HTML `<br>` element. Separator values are used as-is and may be of any type accepted by `LuCI.dom.content()`.

  ##### Returns:

  Type | Description
  --- | ---
  Node | Returns the parent DOM node the formatted markup has been added to.

#### pingDevice(proto, host){Promise.<Event>}

ui.js, line 3887

  Perform a device connectivity test.

  Attempt to fetch a well known ressource from the remote device via HTTP in order to test connectivity. This function is mainly useful to wait for the router to come back online after a reboot or reconfiguration.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `proto` | string | http | optional The protocol to use for fetching the resource. May be either `http` (the default) or `https`.
  `host` | string | window.location.host | optional Override the host address to probe. By default the current host as seen in the address bar is probed.

  ##### Returns:

  Type | Description
  --- | ---
  Promise.<Event> | Returns a promise resolving to a `load` event in case the device is reachable or rejecting with an `error` event in case it is not reachable or rejecting with `null` when the connectivity check timed out.

#### showIndicator(id, label, handler, style){boolean}

ui.js, line 3361

  Display or update an header area indicator.

  An indicator is a small label displayed in the header area of the screen providing few amounts of status information such as item counts or state toggle indicators.

  Multiple indicators may be shown at the same time and indicator labels may be made clickable to display extended information or to initiate further actions.

  Indicators can either use a default `active` or a less accented `inactive` style which is useful for indicators representing state toggles.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `id` | string |  | The ID of the indicator. If an indicator with the given ID already exists, it is updated with the given label and style.
  `label` | string |  | The text to display in the indicator label.
  `handler` | function |  | optional A handler function to invoke when the indicator label is clicked/touched by the user. If omitted, the indicator is not clickable/touchable. Note that this parameter only applies to new indicators, when updating existing labels it is ignored.
  `style` | string | active | optional The indicator style to use. May be either `active` or `inactive`.

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns `true` when the indicator has been updated or `false` when no changes were made.

#### showModal(title, contents, classes){Node}

ui.js, line 3173

  Display a modal overlay dialog with the specified contents.

  The modal overlay dialog covers the current view preventing interaction with the underlying view contents. Only one modal dialog instance can be opened. Invoking showModal() while a modal dialog is already open will replace the open dialog with a new one having the specified contents.

  Additional CSS class names may be passed to influence the appearence of the dialog. Valid values for the classes depend on the underlying theme.

  Name | Type | Description
  --- | --- | ---
  `title` | string | optional The title of the dialog. If `null`, no title element will be rendered.
  `contents` | * | The contents to add to the modal dialog. This should be a DOM node or a document fragment in most cases. The value is passed as-is to the `dom.content()` function - refer to its documentation for applicable values.
  `classes` | string | optional repeatable A number of extra CSS class names which are set on the modal dialog element.

  See:
    - LuCI.dom.content

  ##### Returns:

  Type | Description
  --- | ---
  Node | Returns a DOM Node representing the modal dialog element.

#### uploadFile(path, progessStatusNode){Promise.<LuCI.ui.FileUploadReply>}

ui.js, line 3765

  Display a modal file upload prompt.

  This function opens a modal dialog prompting the user to select and upload a file to a predefined remote destination path.

  Name | Type | Description
  --- | --- | ---
  `path` | string | The remote file path to upload the local file to.
  `progessStatusNode` | Node | optional An optional DOM text node whose content text is set to the progress percentage value during file upload.

  ##### Returns:

  Type | Description
  --- | ---
  Promise.<LuCI.ui.FileUploadReply> | Returns a promise resolving to a file upload status object on success or rejecting with an error in case the upload failed or has been cancelled by the user.

### Type Definitions

#### LuCI.ui.FileUploadReplyObject

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `name` | string | Name of the uploaded file without directory components
  `size` | number | Size of the uploaded file in bytes
  `checksum` | string | The MD5 checksum of the received file data
  `sha256sum` | string | The SHA256 checksum of the received file data