LuCI

new LuCI(window, document, undefined)

This is the LuCI base class. It is automatically instantiated and accessible using the global L variable.

Parameters:
NameTypeDescription
windowWindow

The browser global window object.

documentDocument

The DOM document root for the current page.

undefinedundefined

Local undefined slot (prevents shadowing and ensures undefined is the real undefined value).

Properties
NameTypeDescription
envobject

The environment settings to use for the LuCI runtime.

Source

Classes

baseclass
dom
form
fs
headers
network
poll
request
response
rpc
session
uci
ui
validation
view
xhr

Namespaces

validation

Members

Class

Legacy L.Class class alias. New view code should use 'require baseclass'; to request the LuCI.baseclass class.

Deprecated
  • Yes
Source

Poll

Legacy L.Poll class alias. New view code should use 'require poll'; to request the LuCI.poll class.

Deprecated
  • Yes
Source

Request

Legacy L.Request class alias. New view code should use 'require request'; to request the LuCI.request class.

Deprecated
  • Yes
Source

dom

Legacy L.dom class alias. New view code should use 'require dom'; to request the LuCI.dom class.

Deprecated
  • Yes
Source

env

The env object holds environment settings used by LuCI, such as request timeouts, base URLs, etc.

Source

naturalCompare :function

Compares two values numerically and returns -1, 0, or 1 depending on whether the first value is smaller, equal to, or larger than the second one respectively.

This function is meant to be used as a comparator function for Array.sort().

Type:
  • function
Source

view

Legacy L.view class alias. New view code should use 'require view'; to request the LuCI.view class.

Deprecated
  • Yes
Source

Methods

bind(fn, self, …argsopt) → {function}

Return a bound function using the given self as this context and any further arguments as parameters to the bound function.

Parameters:
NameTypeAttributesDescription
fnfunction

The function to bind.

self*

The value to bind as this context to the specified function.

args*<optional>
<repeatable>

Zero or more variable arguments which are bound to the function as parameters.

Source
Returns:

Returns the bound function.

Type: 
function

error(typeopt, fmtopt, …argsopt)

A wrapper around raise() which also renders the error either as modal overlay when ui.js is already loaded or directly into the view body.

Parameters:
NameTypeAttributesDefaultDescription
typeError | string<optional>
Error

Either a string specifying the type of the error to throw or an existing Error instance to copy.

fmtstring<optional>
Unspecified error

A format string which is used to form the error message, together with all subsequent optional arguments.

args*<optional>
<repeatable>

Zero or more variable arguments to the supplied format string.

Source
Throws:

Throws the created error object with the captured stack trace appended to the message and the type set to the given type argument or copied from the given error instance.

Type
Error

fspath(…partsopt) → {string}

Construct an absolute filesystem path relative to the server document root.

Parameters:
NameTypeAttributesDescription
partsstring<optional>
<repeatable>

An array of parts to join into a path.

Source
Returns:

Return the joined path.

Type: 
string

get(url, argsopt, cb) → {Promise.<null>}

Issues a GET request to the given url and invokes the specified callback function. The function is a wrapper around Request.request().

Parameters:
NameTypeAttributesDescription
urlstring

The URL to request.

argsObject.<string, string><optional>

Additional query string arguments to append to the URL.

cbLuCI.requestCallbackFn

The callback function to invoke when the request finishes.

Deprecated
  • Yes
Source
Returns:

Returns a promise resolving to null when concluded.

Type: 
Promise.<null>

halt() → {boolean}

Deprecated wrapper around Poll.stop().

Deprecated
  • Yes
Source
Returns:

Returns true when the polling loop has been stopped or false when it didn't run to begin with.

Type: 
boolean

hasSystemFeature(feature, subfeatureopt) → {boolean|null}

Test whether a particular system feature is available, such as hostapd SAE support or an installed firewall. The features are queried once at the beginning of the LuCI session and cached in SessionStorage throughout the lifetime of the associated tab or browser window.

Parameters:
NameTypeAttributesDescription
featurestring

The feature to test. For a detailed list of known feature flags, see /modules/luci-base/root/usr/share/rpcd/ucode/luci.

subfeaturestring<optional>

Some feature classes like hostapd provide sub-feature flags, such as sae or 11w support. The subfeature argument can be used to query these.

Source
Returns:

Return true if the queried feature (and sub-feature) is available or false if the requested feature isn't present or known. Return null when a sub-feature was queried for a feature which has no sub-features.

Type: 
boolean | null

hasViewPermission() → {boolean|null}

Check whether a view has sufficient permissions.

Source
Returns:

Returns null if the current session has no permission at all to load resources required by the view. Returns false if readonly permissions are granted or true if at least one required ACL group is granted with write permissions.

Type: 
boolean | null

isArguments(valopt) → {boolean}

Tests whether the passed argument is a function arguments object.

Parameters:
NameTypeAttributesDescription
val*<optional>

The value to test

Source
Returns:

Returns true if the given value is a function arguments object, else returns false.

Type: 
boolean

isObject(valopt) → {boolean}

Tests whether the passed argument is a JavaScript object. This function is meant to be an object counterpart to the standard Array.isArray() function.

Parameters:
NameTypeAttributesDescription
val*<optional>

The value to test

Source
Returns:

Returns true if the given value is of a type object and not null, else returns false.

Type: 
boolean

location() → {string}

Return the complete URL path to the current view.

Source
Returns:

Returns the URL path to the current view.

Type: 
string

media(…partsopt) → {string}

Construct a URL path relative to the media resource path of the LuCI ui (usually /luci-static/$theme_name).

The resulting URL is guaranteed to contain only the characters a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well as / for the path separator. Suffixing '?x=y&foo=bar' URI parameters also limited to the aforementioned characters is permissible.

Parameters:
NameTypeAttributesDescription
partsstring<optional>
<repeatable>

An array of parts to join into a URL path. Parts may contain slashes and any of the other characters mentioned above.

Source
Returns:

Returns the resulting URL path.

Type: 
string

path(prefixopt, …partsopt) → {string}

Construct a relative URL path from the given prefix and parts. The resulting URL is guaranteed to contain only the characters a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well as / for the path separator. Suffixing '?x=y&foo=bar' URI parameters also limited to the aforementioned characters is permissible.

Parameters:
NameTypeAttributesDescription
prefixstring<optional>

The prefix to join the given parts with. If the prefix is omitted, it defaults to an empty string.

partsstring<optional>
<repeatable>

An array of parts to join into a URL path. Parts may contain slashes and any of the other characters mentioned above.

Source
Returns:

Return the joined URL path.

Type: 
string

poll(interval, url, argsopt, cb, postopt) → {function}

Register a polling HTTP request that invokes the specified callback function. The function is a wrapper around Request.poll.add().

Parameters:
NameTypeAttributesDefaultDescription
intervalnumber

The poll interval to use. If set to a value less than or equal to 0, it will default to the global poll interval configured in LuCI.env.pollinterval.

urlstring

The URL to request.

argsObject.<string, string><optional>

Specifies additional arguments for the request. For GET requests, the arguments are appended to the URL as query string, for POST requests, they'll be added to the request body.

cbLuCI.requestCallbackFn

The callback function to invoke whenever a request finishes.

postboolean<optional>
false

When set to false or not specified, poll requests will be made using the GET method. When set to true, POST requests will be issued. In the case of POST requests, the request body will contain an argument token with the current value of LuCI.env.token by default, regardless of the parameters specified with args.

Deprecated
  • Yes
Source
Returns:

Returns the internally created function that has been passed to Request.poll.add(). This value can be passed to Poll.remove() to remove the polling request.

Type: 
function

post(url, argsopt, cb) → {Promise.<null>}

Issues a POST request to the given url and invokes the specified callback function. The function is a wrapper around Request.request(). The request is sent using application/x-www-form-urlencoded encoding and will contain a field token with the current value of LuCI.env.token by default.

Parameters:
NameTypeAttributesDescription
urlstring

The URL to request.

argsObject.<string, string><optional>

Additional post arguments to append to the request body.

cbLuCI.requestCallbackFn

The callback function to invoke when the request finishes.

Deprecated
  • Yes
Source
Returns:

Returns a promise resolving to null when concluded.

Type: 
Promise.<null>

raise(typeopt, fmtopt, …argsopt)

Captures the current stack trace and throws an error of the specified type as a new exception. Also logs the exception as an error to the debug console if it is available.

Parameters:
NameTypeAttributesDefaultDescription
typeError | string<optional>
Error

Either a string specifying the type of the error to throw or an existing Error instance to copy.

fmtstring<optional>
Unspecified error

A format string which is used to form the error message, together with all subsequent optional arguments.

args*<optional>
<repeatable>

Zero or more variable arguments to the supplied format string.

Source
Throws:

Throws the created error object with the captured stack trace appended to the message and the type set to the given type argument or copied from the given error instance.

Type
Error

require(name, fromopt) → {Promise.<LuCI.baseclass>}

Load an additional LuCI JavaScript class and its dependencies, instantiate it and return the resulting class instance. Each class is only loaded once. Subsequent attempts to load the same class will return the already instantiated class.

Parameters:
NameTypeAttributesDefaultDescription
namestring

The name of the class to load in dotted notation. Dots will be replaced by spaces and joined with the runtime-determined base URL of LuCI.js to form an absolute URL to load the class file from.

fromArray.<string><optional>
[]

Optional dependency chain used during dependency resolution. This array contains the sequence of class names already being resolved (the caller stack). It is used to detect circular dependencies — if name appears in from a DependencyError is thrown.

Source
Throws:

  • Throws a DependencyError when the class to load includes circular dependencies.

    Type
    DependencyError

  • Throws NetworkError when the underlying LuCI.request call failed.

    Type
    NetworkError

  • Throws SyntaxError when the loaded class file code cannot be interpreted by eval.

    Type
    SyntaxError

  • Throws TypeError when the class file could be loaded and interpreted, but when invoking its code did not yield a valid class instance.

    Type
    TypeError
Returns:

Returns the instantiated class.

Type: 
Promise.<LuCI.baseclass>

resolveDefault(value, defvalue) → {Promise.<*>}

Returns a promise resolving with either the given value or with the given default in case the input value is a rejecting promise.

Parameters:
NameTypeDescription
value*

The value to resolve the promise with.

defvalue*

The default value to resolve the promise with in case the given input value is a rejecting promise.

Source
Returns:

Returns a new promise resolving either to the given input value or to the given default value on error.

Type: 
Promise.<*>

resource(…partsopt) → {string}

Construct a URL path relative to the global static resource path of the LuCI ui (usually /luci-static/resources).

The resulting URL is guaranteed to contain only the characters a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well as / for the path separator. Suffixing '?x=y&foo=bar' URI parameters also limited to the aforementioned characters is permissible.

Parameters:
NameTypeAttributesDescription
partsstring<optional>
<repeatable>

An array of parts to join into a URL path. Parts may contain slashes and any of the other characters mentioned above.

Source
Returns:

Returns the resulting URL path.

Type: 
string

run() → {boolean}

Deprecated wrapper around Poll.start().

Deprecated
  • Yes
Source
Returns:

Returns true when the polling loop has been started or false when it was already running.

Type: 
boolean

sortedArray(val) → {Array.<*>}

Converts the given value to an array using toArray() if needed, performs a numerical sort using naturalCompare() and returns the result. If the input already is an array, no copy is being made and the sorting is performed in-place.

Parameters:
NameTypeDescription
val*

The input value to sort (and convert to an array if needed).

Source
See
  • toArray
  • naturalCompare
Returns:

Returns the resulting, numerically sorted array.

Type: 
Array.<*>

sortedKeys(obj, keyopt, sortmodeopt) → {Array.<string>}

Return an array of sorted object keys, optionally sorted by a different key or a different sorting mode.

Parameters:
NameTypeAttributesDescription
objobject

The object to extract the keys from. If the given value is not an object, the function will return an empty array.

keystring | null<optional>

Specifies the key to order by. This is mainly useful for nested objects of objects or objects of arrays when sorting shall not be performed by the primary object keys but by some other key pointing to a value within the nested values.

sortmode"addr" | "num"<optional>

Can be either addr or num to override the natural lexicographic sorting with a sorting suitable for IP/MAC style addresses or numeric values respectively.

Source
Returns:

Returns an array containing the sorted keys of the given object.

Type: 
Array.<string>

stop(entry) → {boolean}

Deprecated wrapper around Poll.remove().

Parameters:
NameTypeDescription
entryfunction

The polling function to remove.

Deprecated
  • Yes
Source
Returns:

Returns true when the function has been removed or false if it could not be found.

Type: 
boolean

toArray(val) → {Array.<*>}

Converts the given value to an array. If the given value is of type array, it is returned as-is, values of a type object are returned as one-element array containing the object, empty strings and null values are returned as an empty array, all other values are converted using String(), trimmed, split on white space and returned as an array.

Parameters:
NameTypeDescription
val*

The value to convert into an array.

Source
Returns:

Returns the resulting array.

Type: 
Array.<*>

url(…partsopt) → {string}

Construct a URL with a path relative to the script path of the server side LuCI application (usually /cgi-bin/luci).

The resulting URL is guaranteed to contain only the characters a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well as / for the path separator. Suffixing '?x=y&foo=bar' URI parameters also limited to the aforementioned characters is permissible.

Parameters:
NameTypeAttributesDescription
partsstring<optional>
<repeatable>

An array of parts to join into a URL path. Parts may contain slashes and any of the other characters mentioned above.

Source
Returns:

Returns the resulting URL path.

Type: 
string

Type Definitions

requestCallbackFn(xhr, data, duration)

The request callback function is invoked whenever an HTTP reply to a request made using the L.get(), L.post() or L.poll() function is timed out or received successfully.

Parameters:
NameTypeDescription
xhrXMLHTTPRequest

The XMLHTTPRequest instance used to make the request.

data*

The response JSON if the response could be parsed as such, else null.

durationnumber

The total duration of the request in milliseconds.

Source