From 3942789dc62d6a0e7fcfb0a935bfe5c8d372245b Mon Sep 17 00:00:00 2001 From: Jo-Philipp Wich Date: Tue, 5 Nov 2019 09:33:40 +0100 Subject: documentation: add JS api docs Signed-off-by: Jo-Philipp Wich (cherry picked from commit d9452d1157aef6b8752fac0f4ed1e0b9221abb31) --- documentation/jsapi/LuCI.html | 4436 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 4436 insertions(+) create mode 100644 documentation/jsapi/LuCI.html (limited to 'documentation/jsapi/LuCI.html') diff --git a/documentation/jsapi/LuCI.html b/documentation/jsapi/LuCI.html new file mode 100644 index 0000000000..44f899b352 --- /dev/null +++ b/documentation/jsapi/LuCI.html @@ -0,0 +1,4436 @@ + + + + + JSDoc: Class: LuCI + + + + + + + + + + +
+ +

Class: LuCI

+ + + + + + +
+ +
+ +

LuCI(env)

+ +

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

+ + +
+ +
+
+ + + + +

Constructor

+ + + +

new LuCI(env)

+ + + + + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
env + + +Object + + + +

The environment settings to use for the LuCI runtime.

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + +
+ + + + + + +

Classes

+ +
+
Class
+
+ +
dom
+
+ +
fs
+
+ +
Headers
+
+ +
Network
+
+ +
Poll
+
+ +
Request
+
+ +
Response
+
+ +
rpc
+
+ +
uci
+
+ +
view
+
+ +
XHR
+
+
+ + + + + + + + + +

Members

+ + + +

env

+ + + + +
+

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

+
+ + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
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
fn + + +function + + + + + + + + + +

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 loaed +or directly into the view body.

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDefaultDescription
type + + +Error +| + +string + + + + + + <optional>
+ + + + + + 		+ + Error + +

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

fmt + + +string + + + + + + <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 + + +
+
+
+
+
+ + + + + + + + + + + + + + + + +

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
url + + +string + + + + + + + + + +

The URL to request.

args + + +Object.<string, string> + + + + + + <optional>
+ + + + + +

Additional query string arguments to append to the URL.

cb + + +LuCI.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
feature + + +string + + + + + + + + + +

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

subfeature + + +string + + + + + + <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 + + +
+
+ + + + + + + + + + + + + +

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 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 + + +
+
+ + + + + + + + + + + + + +

path(prefixopt, partsopt) → {string}

+ + + + + + +
+

Construct a relative URL path from the given prefix and parts. +The resulting URL is guaranteed to only contain the characters +a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well +as / for the path separator.

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
prefix + + +string + + + + + + <optional>
+ + + + + +

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

parts + + +Array.<string> + + + + + + <optional>
+ + + + + +

An array of parts to join into an 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
interval + + +number + + + + + + + + + + + +

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.

url + + +string + + + + + + + + + + + +

The URL to request.

args + + +Object.<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.

cb + + +LuCI.requestCallbackFn + + + + + + + + + + + +

The callback function to invoke whenever a request finishes.

post + + +boolean + + + + + + <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 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
url + + +string + + + + + + + + + +

The URL to request.

args + + +Object.<string, string> + + + + + + <optional>
+ + + + + +

Additional post arguments to append to the request body.

cb + + +LuCI.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 +error to the debug console if it is available.

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDefaultDescription
type + + +Error +| + +string + + + + + + <optional>
+ + + + + + 		+ + Error + +

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

fmt + + +string + + + + + + <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) → {Promise.<LuCI#Class>}

+ + + + + + +
+

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:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
name + + +string + + + +

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.

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
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#Class> + + +
+
+ + + + + + + + + + + + + +

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

+ + + + + + +
+

Returns a promise resolving with either the given value or 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 an URL path relative to the global static resource path +of the LuCI ui (usually /luci-static/resources).

+

The resulting URL is guaranteed to only contain the characters +a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well +as / for the path separator.

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
parts + + +Array.<string> + + + + + + <optional>
+ + + + + +

An array of parts to join into an 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 + + +
+
+ + + + + + + + + + + + + +

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
obj + + +object + + + + + + + + + +

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

key + + +string + + + + + + <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 + + +string + + + + + + <optional>
+ + + + + +

May 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
entry + + +function + + + +

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 type object are +returned as one-element array containing the object, empty +strings and null values are returned as empty array, all other +values are converted using String(), trimmed, split on white +space and returned as array.

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
val + + +* + + + +

The value to convert into an array.

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Returns:
+ + +
+

Returns the resulting array.

+
+ + + +
+
+ Type +
+
+ +Array.<*> + + +
+
+ + + + + + + + + + + + + +

url(partsopt) → {string}

+ + + + + + +
+

Construct an URL pathrelative to the script path of the server +side LuCI application (usually /cgi-bin/luci).

+

The resulting URL is guaranteed to only contain the characters +a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well +as / for the path separator.

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
parts + + +Array.<string> + + + + + + <optional>
+ + + + + +

An array of parts to join into an 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
xhr + + +XMLHTTPRequest + + + +

The XMLHTTPRequest instance used to make the request.

data + + +* + + + +

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

duration + + +number + + + +

The total duration of the request in milliseconds.

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + + +
+ +
+ Documentation generated by JSDoc 3.6.3 on Tue Nov 05 2019 09:33:05 GMT+0100 (Central European Standard Time) +
+ + + + + \ No newline at end of file -- cgit v1.2.3