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

Classes

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

Methods

addNotification(title, children, classes){Node}

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 available 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 appearance 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.

children *

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}

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)

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}

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}

Remove a 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()

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 is suitable to be used as event handler as-is without the need to bind it first.

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

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 caught 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}

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 appended 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, ipaddr){Promise.<Event>}

Perform a device connectivity test.

Attempt to fetch a well known resource 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.

ipaddr 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}

Display or update a 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 "active" | "inactive" 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, children, classes){Node}

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 appearance 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.

children *

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, progressStatusNode){Promise.<LuCI.ui.FileUploadReply>}

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.

progressStatusNode 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