JavaScript API

Usage

"Tabs": [
       {
           "Label": {
               "lang_tag": "users",
               "text": "Users" 
           },
           "Position": "0",
           "TabType": "javascript",
           "ScriptName": "I_HomeCare.js",
           "Function": "showUsers"
       }, 

To generate a tab using your JavaScript functions you need to specify this by setting TabType to javascript. Then, you need to specify the script file's name and which function in this file will be used to draw the tab's content. That function will have one argument, which is the device number.

<functionName> (deviceNumber)

This is the tab rendering function. The set_panel_html function must be called at the end.

Input:

• deviceNumber (number)
  

Output:

• nothing

Variables

jsonp.ud

This is the user data.

• Type: object
• Members:
  • devices (array)
  • scenes (array)
  • users (array)
  • rooms (array)
  • eventList (array)
  • etc.

jsonp.ud.devices

• Type: array
• Members:
  • id (number)
  • device_type (string)
  • room (number)
  • name (string)
  • category_num (number)
  • etc.

jsonp.ud.scenes

• Type: array
• Members:
  • id (number)
  • name (string)
  • room (number)
  • Timer_ids (array)
  • Timer (object)
  • etc.

Functions

get_device_state (deviceId, serviceId, variable, dynamic)

Input:

• deviceId (number)
• serviceId (string)
• variable (string)
• dynamic (number): if 1, the variable's value is taken from lu_status, else, the variable's value is taken from user_data. user_data is read at Luup startup, so for variables that change their value frequently (like Watts, Temperature, etc.) dynamic should be 1.

Output:

• variable value (string or undefined)

set_device_state (deviceId, serviceId, variable, value, dynamic)

Input:

• deviceId (number)
• serviceId (string)
• variable (string)
• value (string)
• dynamic (number): if 1, the variable's value is saved to lu_status (the value is lost after Luup is restarted), else, the variable's value is saved to a copy of user_data; the real user_data is updated when LuaUPnP is restarted.

Output:

• true if the operation succeeded, false otherwise

_console (str)

Input:

• str (string): text to be written in the console. You need to have FireBug installed in order to have a console.

Output:

• nothing

set_panel_html (html)

Used in the tab rendering functions.

Input:

• html (string): The html to be used for generating the tab content.

Output:

• nothing

JavaScript API for UI7

Introduction

One of the new features of UI7 is the Javascript API for writing plugins. This is a free programming interface which is robust, well documented and comes with a guarantee that it will be compatible with the following UI releases.

What is this “API” ?

Simply said: it is a layer between the UI and the plugin developer. This way, the developer can use the features available in the UI by interacting only with the API. By using the new features available in the API, the overall user experience can be visibly improved.

How does it work ?

The API comes in the form of a library which exposes to the developer the objects and methods/functions needed to implement functionality in their plugins.

How is this different from the previous way of writing plugins ?

The developers were writing Javascript code and they had full access to the core of the application. There were a couple of objects and functions written by the UI team which were easing the work for the developer. By using the new API, the developer can write code without interfering with the core of the application.

What is new ?

• The developer can write the plugin without interfering with any other code except the API. This means there are a great bundle of methods like setters and getters which help writing good code.
• UI team can make any changes to the core of the application, but as long as the API stays the same, the plugins will work. This way, the application can be improved and the developer won’t have to fix the code in order for it to work. New versions of the UI can be launched and the plugins will be compatible.
• Event handling - the application will notify the plugin (via the API) about the events that happen inside. Consider, for example, the addition of a new device to the unit. The developer will know, by simply listening to an event, that a device was added and so, (s)he will write the code in such a way that it will take into account the event. The user experience will be greatly improved.
• Asynchronous getters and setters - because most of the actions that happen inside the UI is asynchronous, so are the API’s method written. Most of them have a signature like this: function getXXX(obj, onSuccess, onFailure), where ‘onSuccess’ and ‘onFailure’ are callback functions which are called based on the result of the call.
• No more global variables to manipulate. Everything is handled through getters/setters via API.
• An API reference documentation: every method and its parameters is carefully documented so that the developer would know what the function does, how to call it and what it will return.
• A couple of guidelines will be given to help developers write better code in such a way that two different plugins won’t “harm” each other. The module pattern will be used as a design pattern in order to put a plugin code inside a namespace. Also, this module helps in writing code which is easier to read and use.
• It will be easier for the developers to write the code by using a new feature in the UI which generates the skeleton for the plugin.

What is the API reference documentation ?

This is the part which makes the API usable. Every aspect of the API, no matter how trivial, will be stated explicitly. It contains:

• a description of all the data structures it depends upon
• a description of all the function signatures:
  • function names
  • function parameters (names and types)
  • return type of the function
  • if it throws any exceptions or not

Where is the list of functions which were replaced ?

In the API reference documentation the developer can find out if a function replaces an old one.

Why should a developer write plugins using the API when it can do some “reverse engineering” and directly access any object/functionality of the application ?

It is not mandatory to write the code for the plugin this way. Probably the plugin will work as long as changes are not made in the core of the application, but the API comes also with a guarantee that after application changes, the plugins will continue to work. The UI team and plugin developers have the same goal: to deliver the best experience to the user. This is where the API comes into place - an interface between the two.

Will the API be rewritten with each new UI release ?

No. It will be improved. The goal of the API is to provide a stable interface to the developer so that when changing the core of the application it won’t be necessary to rewrite the plugins.

Is this API going to change in the near future ?

It can be changed. There will be parts of it which are going to be marked as ‘deprecated’. This means that the parts will be candidates for being removed, or modified in a backward incompatible way. The developers will be advised on how are they to change their code in order to use the features which replace the deprecated parts.

Is the API complete ?

Almost. Most of the functionality is there, but developers are encouraged to request new features from the API which will be added in future releases.

Guidelines on writing Javascript code for plugins in UI7

• Use the module pattern to organize your code inside a namespace. Choose a well defined name for your namespace.
• Generate an UUID for your plugin. This way you can use the events engine.
• Use the provided API plugins to perform most of your stuff. If you can’t find an implemented method inside the API you can ASK for an implementation to it.
• NEVER USE variables/functions which are not accessible through API ! They can be changed or removed at any time.
• If you need to do a background job (ex: start a timer), use the events engine and register a ‘cleanup’ function in which you finish the job (clear the timer).
• We encourage the use of try { … } catch { … } blocks everywhere in your functions so that errors don’t get propagated to the top of the application.
• Start from the skeleton provided and expand it:

var MyPlugin = (function (api) {
// example of unique identifier for this plugin...
var uuid = 'B971F6C4-F315-4E2E-AD08-F029A9777517';
 
var myModule = {};
 
function doSomething() {
        // register to event ‘on_ui_cpanel_before_close’...
        api.registerEventHandler('on_ui_cpanel_before_close', myModule, ‘cleanUp’);
        // and do something... 
    }
 
    function cleanUp() {
        // perform clean up...
    }
 
    myModule = {
        uuid: uuid,
        doSomething: doSomething,
        cleanUp: cleanUp
    };
    return myModule;
})(api);

Your plugin functions will be accessible via MyPlugin.doSomething() construction. When the user will leave the cpanel, your plugin will be noticed via event ‘on_ui_cpanel_before_close’; this way you can perform the necessary cleanup.

JavaScript API

Defined in: api.js

Class Summary

---

API(config, application, ui)

- API class for plugins

Parameters:

• {object} config - holds configuration data
• {object} application - application layer
• {object} ui - interface

Method Summary

---

{Object} cloneObject(obj)

- Clones a given object

- Replaces: cloneObject()

Parameters:

• {object} obj - object to be cloned

Returns:

• {Object}

{string} getCpanelContent()

- Retrieves cpanel content

- Replaces: get_panel_html()

Returns:

• {string} HTML code set in cpanel

{number} getCpanelDeviceId()

- Returns device id for current opened cpanel or 0 if not found

Returns:

• {number} - device ID

getCurrentHouseMode(onSuccess, onFailure, context)

- Performs a data request to retrieve the current house mode

Parameters:

• {*} onSuccess Optional - function to be called if the call is successfull
• {*} onFailure Optional - function to be called if the call fails
• {object} context Optional - context in which to execute the functions of success and/or failure

{number} getDeviceIndex(deviceId)

- Retrieves device index for given device id

- Replaces: get_device_index()

Parameters:

• {number} deviceId - id of the device

Returns:

• {number}

{*} getDeviceObject(deviceId)

- Retrieves device object given its id

- Replaces: get_device_obj()

Parameters:

• {number} deviceId - id of the device

Returns:

• {number}

{object} getDeviceState(deviceId, service, variable, options)

- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)

Parameters:

• {number} deviceId - id of the device
• {string} service - name of the service
• {string} variable - name of the variable
• {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)

Returns:

• {object} value for a given variable

{Object|Boolean} getDeviceTemplate(deviceId)

- Returns device template for a given device id

Parameters:

• {number} deviceId - id of the device

Returns:

• {Object|Boolean}

{*} getDisplayedDeviceName(deviceId)

- Retrieves displayed device name or 'unnamed device' if device doesn't have a name or undefined if device not found

Parameters:

• {number} deviceId - id of the device

Returns:

• {*} if device is found a string which contains the device name or 'Unnamed device' if device name is not set, or undefined if device wasn't found

{*} getEventDefinition(deviceType)

- Retrieves event list for a given device type

- Replaces: get_event_definition()

Parameters:

• {string} deviceType - type of device

Returns:

• {*}

{*} getListOfDevices()

- Returns the list of devices from userdata

Returns:

• {*}

getLuSdata(onSuccess, onFailure, context)

- Performs a data request to retrieve lu_sdata

Parameters:

• {*} onSuccess Optional - function to be called if the call is successfull
• {*} onFailure Optional - function to be called if the call fails
• {object} context Optional - context in which to execute the functions of success and/or failure

{*|Object} getRoomObject(roomId)

- Returns room object given a room id

- Replaces: get_room_by_id()

Parameters:

• {number} roomId - id of the room

Returns:

• {*|Object}

{*} getUserData()

- Retrieves userData or null if error

- Replaces: jsonp.ud

Returns:

• {*} object containing userdata

registerEventHandler(eventName, object, functionName)

- Register an event handler.

Parameters:

• {string} eventName - name of the event to register to
• {object} object - the object which registers to the event
• {string} functionName - the name of the function to be executed if event triggers

runUpnpCode(code, options, onSuccess, onFailure, context)

- Runs given Upnp code

Parameters:

• {string} code - code to execute
• {object} options Optional - optionally options to be supplied (will be documented later)
• {*} onSuccess Optional - function to be called if the call is successfull
• {*} onFailure Optional - function to be called if the call fails
• {object} context Optional - context in which to execute the functions of success and/or failure

setCpanelContent(html)

- Sets content for the cpanel

- Replaces: set_panel_html()

Parameters:

• {string} html - the new content of the cpanel

setCurrentHouseMode(modeValue, onSuccess, onFailure, context)

- Sets current house mode

Parameters:

• {number} modeValue - new value for the house mode
• {*} onSuccess Optional - function to be called if the call is successfull
• {*} onFailure Optional - function to be called if the call fails
• {object} context Optional - context in which to execute the functions of success and/or failure

setDeviceStateVariable(deviceId, service, variable, value, onSuccess, onFailure, context)

- Sets state for a device variable using variableset request.

- Replaces: set_device_state()

Parameters:

• {number} deviceId - id of the device
• {string} service - name of the service
• {string} variable - name of the variable
• {*} value - new value for the variable
• {*} onSuccess Optional - function to be called if the call is successfull
• {*} onFailure Optional - function to be called if the call fails
• {object} context Optional - context in which to execute the functions of success and/or failure

Events

The list of available events can be obtained with the following command:

api.getListOfSupportedEvents()