Luup plugins: Static JSON file

From MiOS
Revision as of 04:38, 11 February 2015 by A-lurker (Talk | contribs)

Jump to: navigation, search


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

Contents

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.
  • The triggers or events that are available for the device in the "Triggers" or "Events" tag of a scene.

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 no longer related to Adobe Flash in UI4 or UI5. See Luup plugin icons.
imgIconBody
Ignored in UI5.
imgIconDimmable
Ignored in UI5.
imgIconTurnable
Ignored in UI5.
imgIconMin
Ignored in UI5.
imgIconMax
Ignored in UI5.
halloIconsDir
Ignored in UI5.
inScene
When included and set equal to one, it enables any buttons, etc located on the "dashboard box", so they can be selected in the scene editor for use in scenes, rather than being grayed out.
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.
state_icons
A JSON array. For devices where the icon changes based on a variable's value, describes which icon files exist. See Luup plugin icons. Used only in firmware 1.5.401 or later.
doc_url
A JSON object (associative array). In UI5, the only item in this object which is used is doc_page. It controls which page in docs5.mios.com is brought up when you click on the help (?) icon in the device control panel.
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.
ToggleButton
 ?????
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. This key is required for UI4, and obsoleted in UI5. For UI5, use the eventList2 tag, which has a different format. For compatibility with both UI4 and UI5 you need the same information in both keys. See UI4 UI5 Migration for more information.
eventList2
see eventList, above.
sceneList
A JSON object (associative array). Describes the actions that this plugin can perform (for instance, as the action in a scene). This key is not required and is ignored in UI5, however it is needed for UI4 compatibility. See UI4 UI5 Migration for more information about its format.

UI7 Updates

  • default_icon
replace the old "flashicon" from UI5. See Luup plugin icons
  • state_icons
state_icons mechanism has changed in UI7. Please see Luup plugin icons
  • TopNavigationTab = top_navigation_tab

In device cpanel, tabs can be placed either in the top part or in the bottom. By default they are put in the bottom part. You can mark your tabs with a special flag so that they can be placed in top navigation bar of the cpanel. If two or more tabs are marked with ‘TabType=”flash”’, only the first one found will be placed in top navigation bar. If you want all of them to be placed there, you have to add ‘top_navigation_tab’ to each one. Let’s assume you have a plugin named ‘MyPlugin’ and you want to put a button in the top navigation bar, which, when clicked, will display a message in the cpanel.

  • Add the following lines to the .json device file (D_MyPlugin.json), in the Tabs section: 
{
          "Label": {
                "lang_tag": "About",
                "text": "About"
          },
              "TopNavigationTab": "1",
          "Position": "4",
          "TabType": "javascript",
          "ScriptName": "J_MyPlugin.js",
          "Function": "MyPlugin.about"
}

Notice the property ‘TopNavigationTab’ set to the value of ‘1’. This is the line that specifies where to place the tab in cpanel. If you set a value different than 1, the tab will be placed in the bottom part of the cpanel, so always use ‘1’ if you want the tab in the top bar. You can also use ‘top_navigation_tab’.

  • Add the following lines of code to your .js file (J_MyPlugin.js): 
var MyPlugin = (function(api){
    return {
        about: function() {
            try {              
                var html = '<div>This is all about me !</div>';
             api.setCpanelContent(html);
            } catch (e) {
                Utils.logError('Error in MyPlugin.about(): ' + e);
            }
        }
    };
})(api);
  • Perform a lu reload, enter device cpanel and click on ‘About’ button (which is in the top navigation bar of the cpanel) and the result will be something like this:
image
Retrieved from "http://wiki.mios.com/index.php?title=Luup_plugins:_Static_JSON_file&oldid=8049"
Personal tools