Luup plugin icons - Revision history

Gengen at 08:04, 30 November 2014

2014-11-30T08:04:36Z

Gengen at 08:00, 30 November 2014

2014-11-30T08:00:44Z

Andreimios at 15:01, 30 September 2014

2014-09-30T15:01:44Z

Mcvflorin: /* state_icons */

2012-07-06T13:12:18Z

‎state_icons

Mcvflorin: /* state_icons */

2012-07-06T13:09:33Z

‎state_icons

Mcvflorin: /* Variable icons */

2012-07-06T13:08:49Z

‎Variable icons

Futzle: /* Variable icons */ state_icons

2012-06-23T12:38:56Z

‎Variable icons: state_icons

Futzle: /* Cheating to get finer-grained variable icons */ Yes, it is working in 1.5.401, just need the state_icons in the JSON file.

2012-06-23T12:34:50Z

‎Cheating to get finer-grained variable icons: Yes, it is working in 1.5.401, just need the state_icons in the JSON file.

Futzle: /* Cheating to get finer-grained variable icons */ Stops working in 1.5.401.

2012-06-20T10:28:27Z

‎Cheating to get finer-grained variable icons: Stops working in 1.5.401.

Henk at 16:57, 3 July 2011

2011-07-03T16:57:00Z

@@ Line 5: / Line 5: @@
 =Icon format=
-All of Vera's icons are 42x42 pixel PNGs with transparency.  Icons of other sizes will be resized to 42x42.
+All of Vera's icons in UI5 are 42x42 pixel PNGs with transparency. Icons of other sizes will be resized to 42x42. In UI7, icon size has grown to 50x50.
 =Configuration=
-The top-level key '''flashicon''' contains a string.  This string is the name of an image file.  The filename is either a relative path or a URL starting with "http".
+In UI5, the top-level key '''flashicon''' contains a string.  This string is the name of an image file.  The filename is either a relative path or a URL starting with "http".
 ==Relative paths==
-If the filename is a relative path, it is relative to the directory '''/www/cmh/skins/default''' on the Vera.  If the filename ends in the string ".swf", this extension is changed to ".png".  (This is presumably a holdover from UI3, which was flash-based.  In UI4, there is no reason to maintain this ruse, so just use the ".png" extension.)
+In UI5, If the filename is a relative path, it is relative to the directory '''/www/cmh/skins/default''' on the Vera.  If the filename ends in the string ".swf", this extension is changed to ".png".  (This is presumably a holdover from UI3, which was flash-based.  In UI4, there is no reason to maintain this ruse, so just use the ".png" extension.)
 Files installed in the "icons" directory are:
@@ Line 67: / Line 67: @@
 =Constant icons=
-For an icon that remains the same all the time, the '''flashicon''' key is all you need to provide.  Ensure that the static JSON file does not contain a '''DisplayStatus''' key, and you are done.
+For an icon that remains the same all the time in UI5, the '''flashicon''' key is all you need to provide.  Ensure that the static JSON file does not contain a '''DisplayStatus''' key, and you are done.
 = Variable icons  =

@@ Line 163: / Line 163: @@
 *'''<nowiki>"default_icon"</nowiki>'''
-"'''flashicon'''" - we don't use it any more, instead we will have "default_icon" as in the above example, which can be either the url from a image uploaded somewhere on the web or a image stored locally in skins/default/img/devices/device_sates/ . Please be sure if you choose the last method to not upload images with names identical to any of the existing device state icon files. Image resolution should be 50px x 50px.
+"'''flashicon'''" is not used any more, instead, UI7 uses "default_icon" as in the above example, which can be either the url from a image uploaded somewhere on the web or a image stored locally in /www/cmh/skins/default/img/devices/device_states/ . Please be sure if you choose the last method to not upload images with names identical to any of the existing device state icon files. Image resolution should be 50px x 50px.
 *'''<nowiki>"state_icons"</nowiki>'''
 If the device created by the plugin has states and we need to display them we will use this object. "img" is the state image, same as above, it's a url to a image uploaded on the web or the name of a image stored locally in skins/default/img/devices/device_sates/. "conditions" is an array of objects from which we build logical expressions and evaluate them to decide what icon to be used for what state. In the example above if in lu_status for a given binary light with "subcategory_num" = 0 ( this means indoor binary light , because we also have devices for outdoor use like the Jasco 45604) we find    service : "urn:upnp-org:serviceId:SwitchPower1", variable : "Status" and the value from this pair is equal ("operator") to the "value" (0) in the conditions object then we show the "binary_light_off.png" in the UI (light is off). A good example of usage for "subcategory_num" can be seen in the json definition of the motion sensor D_MotionSensor1.json - which serves as template for a number of types of sensors but I am not sure if this will be the case for plugins("subcategory_num" is not mandatory). As I said "conditions" is an array of objects,     this means that if we want to display a certain icon based on more than 1 condition we can do so by adding to it more objects defining different conditions.

← Older revision		Revision as of 15:01, 30 September 2014
Line 158:		Line 158:

	That this trick works is probably accidental, and its behaviour probably should not be relied on.		That this trick works is probably accidental, and its behaviour probably should not be relied on.
		+	= UI7 Icons=
		+
		+	To avoid adding extra code to treat plugin icons, all plugin developers should take into consideration the following:
		+
		+	*'''<nowiki>"default_icon"</nowiki>'''
		+	"'''flashicon'''" - we don't use it any more, instead we will have "default_icon" as in the above example, which can be either the url from a image uploaded somewhere on the web or a image stored locally in skins/default/img/devices/device_sates/ . Please be sure if you choose the last method to not upload images with names identical to any of the existing device state icon files. Image resolution should be 50px x 50px.
		+	*'''<nowiki>"state_icons"</nowiki>'''
		+	If the device created by the plugin has states and we need to display them we will use this object. "img" is the state image, same as above, it's a url to a image uploaded on the web or the name of a image stored locally in skins/default/img/devices/device_sates/. "conditions" is an array of objects from which we build logical expressions and evaluate them to decide what icon to be used for what state. In the example above if in lu_status for a given binary light with "subcategory_num" = 0 ( this means indoor binary light , because we also have devices for outdoor use like the Jasco 45604) we find service : "urn:upnp-org:serviceId:SwitchPower1", variable : "Status" and the value from this pair is equal ("operator") to the "value" (0) in the conditions object then we show the "binary_light_off.png" in the UI (light is off). A good example of usage for "subcategory_num" can be seen in the json definition of the motion sensor D_MotionSensor1.json - which serves as template for a number of types of sensors but I am not sure if this will be the case for plugins("subcategory_num" is not mandatory). As I said "conditions" is an array of objects, this means that if we want to display a certain icon based on more than 1 condition we can do so by adding to it more objects defining different conditions.
		+
		+	Example:
		+
		+	<source lang="javascript">
		+	{
		+	"default_icon": "binary_light_default.png",
		+	"state_icons": [
		+	{
		+	"img": "binary_light_off.png",
		+	"conditions": [
		+	{
		+	"service": "urn:upnp-org:serviceId:SwitchPower1",
		+	"variable": "Status",
		+	"operator": "==",
		+	"value": 0,
		+	"subcategory_num": 0
		+	}
		+	]
		+	},
		+	{
		+	"img": "binary_light_on.png",
		+	"conditions": [
		+	{
		+	"service": "urn:upnp-org:serviceId:SwitchPower1",
		+	"variable": "Status",
		+	"operator": "==",
		+	"value": 1,
		+	"subcategory_num": 0
		+	}
		+	]
		+	}
		+	],
		+	...
		+	}
		+	</source>

@@ Line 118: / Line 118: @@
 Currently each device can have a maximum of 5 icons. The formula for choosing the icon is this:
-<source lang="javascript">var val = ceil( Variable / (MaxValue - MinValue) );
+<source lang="javascript">
-var icon = baseIconName + "_" + (isNaN( val * 25 ) ? 0 : (val * 25)) + ".png";</source>
+var status = Variable / (MaxValue - MinValue);
 e.g. For the dimmable light, the formula would look like this:
-<source lang="javascript">var val = ceil( LoadLevelStatus / (100 - 0) );
+<source lang="javascript">
 var icon = "Dimmable_Light" + "_" + (isNaN( val * 25 ) ? 0 : (val * 25)) + ".png";</source>

@@ Line 124: / Line 124: @@
 e.g. For the dimmable light, the formula would look like this:
-<source lang="javascript">var val = ceil( LoadLevelStatus / (MaxValue - MinValue) );
+<source lang="javascript">var val = ceil( LoadLevelStatus / (100 - 0) );
 var icon = "Dimmable_Light" + "_" + (isNaN( val * 25 ) ? 0 : (val * 25)) + ".png";</source>

@@ Line 69: / Line 69: @@
 For an icon that remains the same all the time, the '''flashicon''' key is all you need to provide.  Ensure that the static JSON file does not contain a '''DisplayStatus''' key, and you are done.
-=Variable icons=
+= Variable icons  =
-For an icon that varies based on the value of a variable, place a '''DisplayStatus''' key at the top level of the static JSON file.  Its value is a JSON object (associative array) with four keys:
+For an icon that varies based on the value of a variable, place a '''DisplayStatus''' key at the top level of the static JSON file. Its value is a JSON object (associative array) with four keys:
-; Service
-: The Service ID of the variable that controls the icon.  This can be found in the matching device XML file, under the '''serviceId''' element.
-; Variable
-: The variable name of the variable that controls the icon.
-; MinValue
-: The value that this variable has when it is considered "off" or at "0%".  This can even be a string, if the variable is a string that takes two values.
-; MaxValue
-: The value that this variable has when it is considered "on" or at "100%".  This can even be a string, if the variable is a string that takes two values.
-Example for a binary switch:
+;Service
-<pre><nowiki>
+Example for a binary switch:
-  "DisplayStatus": {
+<pre>  "DisplayStatus": {
          "Service": "urn:upnp-org:serviceId:SwitchPower1",
          "Variable": "Status",
@@ Line 90: / Line 89: @@
          "MaxValue": "1"
+   }
-</nowiki></pre>
+</pre>
 Example for a variable which takes on a range of values.
-Example for a variable which takes on a range of values.
+<pre>  "DisplayStatus": {
-−
-<pre><nowiki>
-  "DisplayStatus": {
          "Service": "urn:upnp-org:serviceId:Dimming1",
          "Variable": "LoadLevelStatus",
@@ Line 101: / Line 97: @@
          "MaxValue": "100"
+   }
-</nowiki></pre>
+</pre>
-The filename in '''flashicon''' undergoes a special transformation for variable icons.  The extension ".png" is changed to "_0.png", "_25.png", "_50.png", "_75.png" or "_100.png" depending on the value of the service variable, linearly scaled from its range of 0:(MaxValue-MinValue) to 0:100.  Values round up; 1-25 produces the "_25" image; 26-50 produces the "_50" image, and so on.  For images which are not found (for instance, if the web server returns '''404 Not Found''') the default image is used.
+e.g. For the dimmable light, the formula would look like this:
-Consequently, at least three images, and as many as six, should be present for variable-icon plugins.  For example, if '''flashicon''' contains '''<nowiki>http://example.com/image.png</nowiki>''', the web server must be able to serve:
+<source lang="javascript">var val = ceil( LoadLevelStatus / (MaxValue - MinValue) );
-* '''<nowiki>http://example.com/image.png</nowiki>''' (for when the plugin is loading in the Luup engine)
+var icon = "Dimmable_Light" + "_" + (isNaN( val * 25 ) ? 0 : (val * 25)) + ".png";</source>
-* '''<nowiki>http://example.com/image_0.png</nowiki>'''
-* '''<nowiki>http://example.com/image_100.png</nowiki>'''
-and it should be able to serve (if the variable is a sliding scale):
-* '''<nowiki>http://example.com/image_25.png</nowiki>'''
-* '''<nowiki>http://example.com/image_50.png</nowiki>'''
-* '''<nowiki>http://example.com/image_75.png</nowiki>'''
-From firmware 1.5.401 onwards, you must also tell the Static JSON file which icon files exist, with the '''state_icons''' key at the top level. The corresponding value is a JSON array of strings, the filenames which should be displayed in the UI.  This key was added to prevent the plethora of 404 errors that would appear in the JavaScript console.
+The resulting intervals and icons are:
-==Cheating to get finer-grained variable icons==
+== Cheating to get finer-grained variable icons  ==
-The JavaScript code that inserts the strings "_0" to "_100" into the image filename does not check that the raw variable value is in the range '''MinValue''' to '''MaxValue'''.  By deliberately choosing a '''MaxValue''' less than the highest value that a variable can take, you can make the JavaScript load images with "_125", "_150", etc., effectively providing any number of images.  '''MinValue''' is similarly handled, though the results are odd with negative variables or MinValue not equal to zero: the string inserted into the filename is "_-25", "-50", etc.
+The JavaScript code that inserts the strings "_0" to "_100" into the image filename does not check that the raw variable value is in the range '''MinValue''' to '''MaxValue'''. By deliberately choosing a '''MaxValue''' less than the highest value that a variable can take, you can make the JavaScript load images with "_125", "_150", etc., effectively providing any number of images. '''MinValue''' is similarly handled, though the results are odd with negative variables or MinValue not equal to zero: the string inserted into the filename is "_-25", "-50", etc.
 That this trick works is probably accidental, and its behaviour probably should not be relied on.

← Older revision		Revision as of 16:57, 3 July 2011
Line 1:		Line 1:
		+	[[Category:Development]]
		+
	The [[Luup plugins: Static JSON file\|Luup plugin static JSON file]] describes the icon that appears in the dashboard of the UI4 web interface.		The [[Luup plugins: Static JSON file\|Luup plugin static JSON file]] describes the icon that appears in the dashboard of the UI4 web interface.