Revision as of 16:57, 3 July 2011

Starting in UI4, Luup plugins can specify a static JSON file. This file describes how the plugin appears in the web interface.

What the static JSON file controls

• The icon used by the plugin in the dashboard.
• The text that displays in the one-to-two-row status message in the dashboard.
• Whether the icon changes depending on the value of a variable in the device (for example, a binary light's icon changes from lit to unlit).
• The tabs that appear in the device's detail dialog (when you click the wrench/spanner).
• The content of these tabs.

Referencing the static JSON file from the Device XML file

The device XML file (customarly D_PluginName.xml) contains a reference to the static JSON file, in the staticJson element. Place the element as a child of the device element:

  <?xml version="1.0"?>
  <root xmlns="urn:schemas-upnp-org:device-1-0">
    <specVersion><!-- ... --></specVersion>
    <device>
      <deviceType>urn:schemas-futzle-com:device:holidayvirtualswitch:1</deviceType>
      <staticJson>D_HolidayVirtualSwitch1.json</staticJson>
      <!-- ... -->

Capitalization is important, as with all XML.

The static JSON file is customarily called D_PluginName.json.

The static JSON file

The static JSON file is a single JSON object (associative array).

Root keys

These keys have been seen at the top level in static JSON files in the wild:

flashicon

The device's icon, as a string. Despite the name, the icon is not related to Flash in UI4. See Luup plugin icons.

imgIconBody

A string which appears to have no effect.

imgIconDimmable

A string which appears to have no effect.

imgIconTurnable

A string which appears to have no effect.

imgIconMin

A string which appears to have no effect.

imgIconMax

A string which appears to have no effect.

halloIconsDir

A string which appears to have no effect. Usually contains "pics\/hallo", for reasons unknown.

DisplayStatus

A JSON object (associative array). For devices where the icon changes based on a variable's value, describes which variable, and the range of values that produce different icon images. See Luup plugin icons.

doc_url

A JSON object (associative array). Appears to have no effect.

Tabs

A JSON array. Describes the tabs in the detail dialog, and what subset of the first tab appears in the dashboard. See Luup plugin tabs.

DeviceType

A JSON string. Must match the deviceType element in the corresponding device XML (D_PluginName.xml) file.

eventList

A JSON object (associative array). Describes the events that this plugin can produce. Events are triggers that can fire off actions in scenes. See Luup plugin event list.

sceneList

A JSON object (associative array). Describes the actions that this plugin can perform (for instance, as the action in a scene). See Luup plugin scenes.