Revision as of 10:30, 25 June 2011

The Tabs key in the static JSON file performs two duties in the UI4 HTML interface:

• It controls how the device appears in the dashboard.
• It controls how each tab appears in the the device's detailed dialog.

The value of the Tabs key is a JSON array. Each array element is a JSON object (associative array).

Required tab fields

These fields must be present in each JSON object in the tab list:

Label

A JSON object containing two keys: lang_tag (a string) is not displayed in the HTML interface but may be used by localized UIs; text (a string) is displayed in the tab's handle at the top of the dialog.

Position

A string which contains a number matching the relative position of this tab in relation to the other tabs. The leftmost tab has value "0", the next tab "1", and so on.

TabType

A string which describes how the content of the tab is to be generated. The value may be one of javascript or flash. These are described in the following sections.

TabType javascript

The javascript tab type executes client-side JavaScript, producing an HTML fragment which forms the body of the tab. These additional keys are required in the tab JSON object:

ScriptName

The name of the JavaScript file. Conventionally, plugin JavaScript files are named J_PluginName.js.

Function

The function inside the JavaScript file which will be called to produce the HTML.

The JavaScript code has access to most Luup variables through the JavaScript API.

TabType flash

The flash tab type creates a tab body with a simple page-description language. Each component of the page is placed into the body at the position specified. These additional keys are required in the tab JSON object:

Control

A JSON array containing each item on the page. Described below.

ControlGroup

Required only if the first tab is also used to display elements on the dashboard. See Dashboard appearance below.

The Control array contains JSON objects (associative arrays), one per item in the tab body. An item is either a static text label, a variable, an input field, or a button or slider. This is handled by setting the ControlType key on the object.

ControlType label

With ControlType set to label, a fixed label is placed at the specified coordinates. The following additional keys must also be provided:

Label

A JSON object with two keys: lang_tag is not displayed but can be used by localizing interfaces to translate the label text. text is displayed as the content of the label.

Display

A JSON object with four keys: Top, Left, Width, Height (all strings containing numbers). This controls where the label is placed in the tab.

ControlType variable

With ControlType set to variable, the contents of a Luup variable are displayed at the specified coordinates. The following additional keys must also be provided:

Display

A JSON object with six keys: Top, Left, Width, Height (all strings containing numbers, controlling where the variable's value is placed in the tab), Service (a string containing the Service Id of the variable to be displayed), and Variable (a string containing the name of the variable to be displayed).

ControlType input

With ControlType set to input, a text box for the user to type a string is placed in the tab. The following additional keys must also be provided:

ID

A string which other controls (buttons) will use to refer to the string that the user has typed into this field.

Display

A JSON object with four keys: Top, Left, Width, Height (all strings containing numbers). This controls where the text box is placed in the tab.

ControlType button

With ControlType set to button, a clickable button is placed at the specified coordinates. The button will appear selected (depressed) or unselected based on the value of a variable, permitting sets of buttons to act as radio buttons. The following additional keys must also be provided:

Label

A JSON object with two keys: lang_tag is not displayed but can be used by localizing interfaces to translate the label text. text is displayed as the text inside the button.

Display

A JSON object with up to seven keys: Top, Left, Width, Height (all strings containing numbers, controlling where the button is placed in the tab), Service (a string containing the Service Id of a variable), and Variable (a string containing the name of a variable), and (optionally) Value (a string, "1" if omitted). The specified variable's value controls whether the button appears selected (if the variable matches Value) or not selected (if the variable doesn't match).

Command

A JSON object with three keys: Service (a string containing the service Id of an action that this device can perform), Action (a string containing the name of the action), and Parameters (a JSON array of JSON objects, forming the parameters to pass to the action). Each parameter object has a key Name for the parameter name, and either a key Value (for a fixed parameter value) or a key ID matching an input control on the page (for a user-entered parameter value).

ControlType slider

With ControlType set to slider, a draggable slider is placed at the specified coordinates. The following additional keys must also be provided:

Display

A JSON object with nine keys: Top, Left, Width, Height (all strings containing numbers, controlling where the button is placed in the tab), Service (a string containing the Service Id of a variable), and Variable (a string containing the name of a variable), MinValue and MaxValue (both strings containing numbers, controlling what range of values the slider takes) and ID (a string, used in the Command to refer to the position the user has dragged the slider to). The specified variable's value is used to display the slider's current position.

Command

A JSON object with three keys: Service (a string containing the service Id of an action that this device can perform), Action (a string containing the name of the action), and Parameters (a JSON array of JSON objects, forming the parameters to pass to the action). Each parameter object has a key Name for the parameter name, and either a key Value (for a fixed parameter value) or a key ID matching the slider's ID (for a value matching what the user has dragged the slider to).

ControlHeader

Optional. If present, must have string value "1". When set, the slider's label and value are displayed. Otherwise only the slider is shown. (TODO: This is from reverse-engineering the JavaScript code. Test this.)

Dashboard appearance

The first array element in the Tabs field is special. If it is of type flash then a subset of the controls on the tab can be chosen to display on the UI4 dashboard.

Control Groups

The dashboard box for a device has room for two rows of information and controls. These are called Control Groups.

The tab object must contain the key ControlGroup, which specifies how the dashboard's two available rows of information are to be handled. ControlGroup is a JSON array containing JSON objects (associative arrays). Each object has the following keys:

id

A string containing a number, "1" for the first object, "2" for the second, and so on.

isSingle

If this key is present and contains the value "1", then this control group is combined with other control groups that have isSingle similarly set onto the same row. For an example of this, see the On/Off buttons of the Binary Switch and Dimmable Switch static JSON files.

type

If this key is present and contains the value "info", then the controls displayed on this row are not clickable. If this key is absent, buttons may be used in the control group.

Making a control appear on the dashboard

All control types (label, variable, button, input, slider) can appear in the dashboard. However, by default, controls in the first tab's detail view do not appear in the dashboard. To make a control's text appear in the dashboard, add a ControlGroup to the control's JSON object. The value is a string containing a number, matching the id of one of the Tab's overall ControlGroup key. The dashboard will concatenate all of a control group's controls in the order they are presented in the Control array, and display them in a single row of text.

Keeping controls together

Some controls may not make sense if presented individually (for instance, an input for an alarm PIN and a "disarm" button). To keep these controls together, add a ControlPair key to all of the controls that have to appear together. Use the same value (a number in a string) for all of them.