Luup plugins: Static JSON file

From MiOS
(Difference between revisions)
Jump to: navigation, search
(Corrections for UI5)
m (Formatting edit.)
Line 1: Line 1:
−
<p><br />
+
 
−
Starting in UI4, Luup plugins can specify a <i>static JSON</i> file.  This file describes how the plugin appears in the web interface.
+
 
−
</p>
+
 
−
<h1>What the static JSON file controls</h1>
+
[[Category:Development]]
−
<ul><li> The icon used by the plugin in the dashboard.
+
 
−
</li><li> The text that displays in the one-to-two-row status message in the dashboard.
+
Starting in UI4, Luup plugins can specify a ''static JSON'' file.  This file describes how the plugin appears in the web interface.
−
</li><li> 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).
+
 
−
</li><li> The tabs that appear in the device's detail dialog (when you click the wrench/spanner).
+
=What the static JSON file controls=
−
</li><li> The content of these tabs.
+
 
−
</li><li> The triggers or events that are available for the device in the "Triggers" or "Events" tag of a scene.
+
* The icon used by the plugin in the dashboard.
−
</li></ul>
+
* The text that displays in the one-to-two-row status message in the dashboard.
−
<h1>Referencing the static JSON file from the Device XML file</h1>
+
* 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).
−
<p>The device XML file (customarly <b>D_PluginName.xml</b>) contains a reference to the static JSON file, in the <b>staticJson</b> element.  Place the element as a child of the <b>device</b> element:
+
* The tabs that appear in the device's detail dialog (when you click the wrench/spanner).
−
</p>
+
* The content of these tabs.
−
<pre>
+
* The triggers or events that are available for the device in the "Triggers" or "Events" tag of a scene.
−
   &lt;?xml version=&quot;1.0&quot;?&gt;
+
 
−
   &lt;root xmlns=&quot;urn:schemas-upnp-org:device-1-0&quot;&gt;
+
=Referencing the static JSON file from the Device XML file=
−
     &lt;specVersion&gt;&lt;!-- ... --&gt;&lt;/specVersion&gt;
+
 
−
     &lt;device&gt;
+
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:
−
       &lt;deviceType&gt;urn:schemas-futzle-com:device:holidayvirtualswitch:1&lt;/deviceType&gt;
+
 
−
       &lt;staticJson&gt;D_HolidayVirtualSwitch1.json&lt;/staticJson&gt;
+
<pre><nowiki>
−
       &lt;!-- ... --&gt;
+
   <?xml version="1.0"?>
−
</pre>
+
   <root xmlns="urn:schemas-upnp-org:device-1-0">
−
<p>Capitalization is important, as with all XML.
+
     <specVersion><!-- ... --></specVersion>
−
</p><p>The static JSON file is customarily called <b>D_PluginName.json</b>.
+
     <device>
−
</p>
+
       <deviceType>urn:schemas-futzle-com:device:holidayvirtualswitch:1</deviceType>
−
<h1>The static JSON file</h1>
+
       <staticJson>D_HolidayVirtualSwitch1.json</staticJson>
−
<p>The static JSON file is a single JSON object (associative array).
+
       <!-- ... -->
−
</p>
+
</nowiki></pre>
−
<h2>Root keys</h2>
+
 
−
<p>These keys have been seen at the top level in static JSON files in the wild:
+
Capitalization is important, as with all XML.
−
</p>
+
 
−
<p><dl><dt> flashicon
+
The static JSON file is customarily called '''D_PluginName.json'''.
−
&lt;/dt&gt;<dd> The device's icon, as a string.  Despite the name, the icon is no longer related to Adobe Flash in UI4 and UI5. See &lt;a _fcknotitle="true" href="Luup plugin icons"&gt;Luup plugin icons&lt;/a&gt;.
+
 
−
&lt;/dd&gt;<dt> imgIconBody
+
=The static JSON file=
−
&lt;/dt&gt;<dd> Ignored in UI5.
+
 
−
&lt;/dd&gt;<dt> imgIconDimmable
+
The static JSON file is a single JSON object (associative array).
−
&lt;/dt&gt;<dd> Ignored in UI5.
+
 
−
&lt;/dd&gt;<dt> imgIconTurnable
+
==Root keys==
−
&lt;/dt&gt;<dd> Ignored in UI5.
+
 
−
&lt;/dd&gt;<dt> imgIconMin
+
These keys have been seen at the top level in static JSON files in the wild:
−
&lt;/dt&gt;<dd> Ignored in UI5.
+
 
−
&lt;/dd&gt;<dt> imgIconMax
+
; flashicon
−
&lt;/dt&gt;<dd> Ignored in UI5.
+
: 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]].
−
&lt;/dd&gt;<dt> halloIconsDir
+
; imgIconBody
−
&lt;/dt&gt;<dd> Ignored in UI5.
+
: Ignored in UI5.
−
&lt;/dd&gt;<dt> inScene
+
; imgIconDimmable
−
&lt;/dt&gt;<dd> When included and set equal to 1, 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.
+
: Ignored in UI5.
−
&lt;/dd&gt;<dt> DisplayStatus
+
; imgIconTurnable
−
&lt;/dt&gt;<dd> 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 &lt;a _fcknotitle="true" href="Luup plugin icons"&gt;Luup plugin icons&lt;/a&gt;.
+
: Ignored in UI5.
−
&lt;/dd&gt;<dt> state_icons
+
; imgIconMin
−
&lt;/dt&gt;<dd> A JSON array.  For devices where the icon changes based on a variable's value, describes which icon files exist.  See &lt;a _fcknotitle="true" href="Luup plugin icons"&gt;Luup plugin icons&lt;/a&gt;. Used only in firmware 1.5.401 or later.
+
: Ignored in UI5.
−
&lt;/dd&gt;<dt> doc_url
+
; imgIconMax
−
&lt;/dt&gt;<dd> A JSON object (associative array). In UI4, 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.
+
: Ignored in UI5.
−
&lt;/dd&gt;<dt> Tabs
+
; halloIconsDir
−
&lt;/dt&gt;<dd> A JSON array.  Describes the tabs in the detail dialog, and what subset of the first tab appears in the dashboard.  See &lt;a _fcknotitle="true" href="Luup plugin tabs"&gt;Luup plugin tabs&lt;/a&gt;.
+
: Ignored in UI5.
−
&lt;/dd&gt;<dt> DeviceType
+
; inScene
−
&lt;/dt&gt;<dd> A JSON string.  Must match the <b>deviceType</b> element in the corresponding device XML (<b>D_PluginName.xml</b>) file.
+
: 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.
−
&lt;/dd&gt;<dt> eventList
+
; DisplayStatus
−
&lt;/dt&gt;<dd> 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 &lt;a _fcknotitle="true" href="UI4 UI5 Migration"&gt;UI4 UI5 Migration&lt;/a&gt; for more information.
+
: 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]].
−
&lt;/dd&gt;<dt> eventList2
+
; state_icons
−
&lt;/dt&gt;<dd> see eventList, above.
+
: 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.
−
&lt;/dd&gt;<dt> sceneList
+
; doc_url
−
&lt;/dt&gt;<dd> 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 &lt;a _fcknotitle="true" href="UI4 UI5 Migration"&gt;UI4 UI5 Migration&lt;/a&gt; for more information about its format.
+
: 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.
−
&lt;/dd&gt;</dl>
+
; Tabs
−
&lt;a _fcknotitle="true" href="Category:Development"&gt;Development&lt;/a&gt;
+
: 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]].
−
</p>
+
; 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.

Revision as of 16:57, 9 June 2013


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.
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.
Retrieved from "http://wiki.mios.com/index.php?title=Luup_plugins:_Static_JSON_file&oldid=6334"
Personal tools