Luup plugins: Static JSON file

From MiOS
(Difference between revisions)
Jump to: navigation, search
(Corrections for UI5)
Line 1: Line 1:
[[Category:Development]]
+
<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.
Starting in UI4, Luup plugins can specify a ''static JSON'' file.  This file describes how the plugin appears in the web interface.
+
</p>
 
+
<h1>What the static JSON file controls</h1>
=What the static JSON file controls=
+
<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.
* The icon used by the plugin in the dashboard.
+
</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).
* The text that displays in the one-to-two-row status message in the dashboard.
+
</li><li> The tabs that appear in the device's detail dialog (when you click the wrench/spanner).
* 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 content of these tabs.
* The tabs that appear in the device's detail dialog (when you click the wrench/spanner).
+
</li><li> The triggers or events that are available for the device in the "Triggers" or "Events" tag of a scene.
* The content of these tabs.
+
</li></ul>
* The triggers or events that are available for the device in the "Triggers" or "Events" tag of a scene.
+
<h1>Referencing the static JSON file from the Device XML file</h1>
 
+
<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:
=Referencing the static JSON file from the Device XML file=
+
</p>
 
+
<pre>
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;?xml version=&quot;1.0&quot;?&gt;
 
+
   &lt;root xmlns=&quot;urn:schemas-upnp-org:device-1-0&quot;&gt;
<pre><nowiki>
+
     &lt;specVersion&gt;&lt;!-- ... --&gt;&lt;/specVersion&gt;
   <?xml version="1.0"?>
+
     &lt;device&gt;
   <root xmlns="urn:schemas-upnp-org:device-1-0">
+
       &lt;deviceType&gt;urn:schemas-futzle-com:device:holidayvirtualswitch:1&lt;/deviceType&gt;
     <specVersion><!-- ... --></specVersion>
+
       &lt;staticJson&gt;D_HolidayVirtualSwitch1.json&lt;/staticJson&gt;
     <device>
+
       &lt;!-- ... --&gt;
       <deviceType>urn:schemas-futzle-com:device:holidayvirtualswitch:1</deviceType>
+
</pre>
       <staticJson>D_HolidayVirtualSwitch1.json</staticJson>
+
<p>Capitalization is important, as with all XML.
       <!-- ... -->
+
</p><p>The static JSON file is customarily called <b>D_PluginName.json</b>.
</nowiki></pre>
+
</p>
 
+
<h1>The static JSON file</h1>
Capitalization is important, as with all XML.
+
<p>The static JSON file is a single JSON object (associative array).
 
+
</p>
The static JSON file is customarily called '''D_PluginName.json'''.
+
<h2>Root keys</h2>
 
+
<p>These keys have been seen at the top level in static JSON files in the wild:
=The static JSON file=
+
</p>
 
+
<p><dl><dt> flashicon
The static JSON file is a single JSON object (associative array).
+
&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
==Root keys==
+
&lt;/dt&gt;<dd> Ignored in UI5.
 
+
&lt;/dd&gt;<dt> imgIconDimmable
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> imgIconTurnable
; flashicon
+
&lt;/dt&gt;<dd> Ignored in UI5.
: The device's icon, as a string.  Despite the name, the icon is not related to Flash in UI4. See [[Luup plugin icons]].
+
&lt;/dd&gt;<dt> imgIconMin
; imgIconBody
+
&lt;/dt&gt;<dd> Ignored in UI5.
: A string which appears to have no effect.
+
&lt;/dd&gt;<dt> imgIconMax
; imgIconDimmable
+
&lt;/dt&gt;<dd> Ignored in UI5.
: A string which appears to have no effect.
+
&lt;/dd&gt;<dt> halloIconsDir
; imgIconTurnable
+
&lt;/dt&gt;<dd> Ignored in UI5.
: A string which appears to have no effect.
+
&lt;/dd&gt;<dt> inScene
; imgIconMin
+
&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.
: A string which appears to have no effect.
+
&lt;/dd&gt;<dt> DisplayStatus
; imgIconMax
+
&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;.
: A string which appears to have no effect.
+
&lt;/dd&gt;<dt> state_icons
; halloIconsDir
+
&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.
: A string which appears to have no effect.  Usually contains "pics\/hallo", for reasons unknown.
+
&lt;/dd&gt;<dt> doc_url
; inScene
+
&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.
: 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> Tabs
; DisplayStatus
+
&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;.
: 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> DeviceType
; state_icons
+
&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.
: 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> eventList
; doc_url
+
&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). Appears to have no effect.
+
&lt;/dd&gt;<dt> eventList2
; Tabs
+
&lt;/dt&gt;<dd> see eventList, above.
: 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]].
+
&lt;/dd&gt;<dt> sceneList
; DeviceType
+
&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 string.  Must match the '''deviceType''' element in the corresponding device XML ('''D_PluginName.xml''') file.
+
&lt;/dd&gt;</dl>
; eventList
+
&lt;a _fcknotitle="true" href="Category:Development"&gt;Development&lt;/a&gt;
: 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.
+
</p>
; 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.
+
; sceneList2
+
: see sceneList, above.
+

Revision as of 16:41, 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 </dt>
The device's icon, as a string. Despite the name, the icon is no longer related to Adobe Flash in UI4 and UI5. See <a _fcknotitle="true" href="Luup plugin icons">Luup plugin icons</a>. </dd>
imgIconBody </dt>
Ignored in UI5. </dd>
imgIconDimmable </dt>
Ignored in UI5. </dd>
imgIconTurnable </dt>
Ignored in UI5. </dd>
imgIconMin </dt>
Ignored in UI5. </dd>
imgIconMax </dt>
Ignored in UI5. </dd>
halloIconsDir </dt>
Ignored in UI5. </dd>
inScene </dt>
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. </dd>
DisplayStatus </dt>
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 <a _fcknotitle="true" href="Luup plugin icons">Luup plugin icons</a>. </dd>
state_icons </dt>
A JSON array. For devices where the icon changes based on a variable's value, describes which icon files exist. See <a _fcknotitle="true" href="Luup plugin icons">Luup plugin icons</a>. Used only in firmware 1.5.401 or later. </dd>
doc_url </dt>
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. </dd>
Tabs </dt>
A JSON array. Describes the tabs in the detail dialog, and what subset of the first tab appears in the dashboard. See <a _fcknotitle="true" href="Luup plugin tabs">Luup plugin tabs</a>. </dd>
DeviceType </dt>
A JSON string. Must match the deviceType element in the corresponding device XML (D_PluginName.xml) file. </dd>
eventList </dt>
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 <a _fcknotitle="true" href="UI4 UI5 Migration">UI4 UI5 Migration</a> for more information. </dd>
eventList2 </dt>
see eventList, above. </dd>
sceneList </dt>
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 <a _fcknotitle="true" href="UI4 UI5 Migration">UI4 UI5 Migration</a> for more information about its format. </dd>
<a _fcknotitle="true" href="Category:Development">Development</a>

Personal tools