====== Variables ======
The variable class represents an Indigo variable.
==== Class Properties ====
^Property ^ Type ^Description ^
|//''id''//| integer |the unique id of the variable, assigned on creation by IndigoServer|
|//''folderId''//| integer |the unique id of the folder this variable is in (0 if it's not in a folder) - use //''moveToFolder()''// method to change|
|//''name''//| string |the name of the variable - no two variable can have the same name|
|//''readOnly''//| string |is the variable read only - currently only the //''isDaylight''// variable is read only|
|//''remoteDisplay''//| boolean |should this variable be displayed in remote clients (IWS, Indigo Touch, etc)|
|//''sharedProps''//| dictionary |**[[api_release_notes:2.3|API v2.3]]** : an //''indigo.Dict()''// representing the name/value pairs that are shared by all plugins. This is the property dictionary that you can edit via the Global Properties plugin, and your plugin may manage properties in this dictionary as well to add metadata to devices that your plugin can use for other purposes. Use ''var.replaceSharedPropsOnServer()'' to update them (as with pluginProps, you should get copy first, update the copy, then set them back to that copy so as to not accidentally remove some other plugin's props).|
|//''value''//| string |the unicode string value of the variable|
==== Class Method ====
The Variable class has a special method, ''**getValue(TYPE, default=VALUE)**'', that you can call which will retrieve the variable value as the specified Python class. There are a couple of advantages to using this method: first, it won't throw an exception but will always return a value; second, the Indigo server will do the conversion in the exact same way that it does type conversions when using variables in triggers and conditions. You can also optionally specify a default value if the value can't be successfully converted into the specified type. Here's a list of the valid types you can specify and what the default is if not specified:
^ Type Literal ^ Type Returned ^Default ^
| bool | Boolean |**''True''** will be returned if the value is one of these: "true", "on", "yes", and "1". ''**False**'' will be returned if the value is one of these: "false", "off", "no", and "0". If no default value is specified and the value can't be successfully converted, the method will return False. |
| int | Integer |An integer object will be returned if the value is an integer number or a float/decimal. In the latter case, the number will be rounded to the nearest integer. If no default value is specified and the value can't be converted, the method will return 0 |
| float | Float |A float object will be returned if the value is a float/decimal or an integer. If no default value is specified and the value can't be converted, the method will return 0.0 |
Remember that accessing the ''**value**'' property of a variable object (''//var.value//'') will return a unicode string object so you don't need a conversion for that.
=== Class Method Examples ===
# Get a variable
var = indigo.variables[123456]
# Getting the unicode string value (no conversion call necessary, just access the property)
unicodeValue = var.value
# Getting the boolean value
intValue = var.getValue(bool) # False if it can't be converted
intValue = var.getValue(int, default=True) # True if it can't be converted
# Getting the integer value
intValue = var.getValue(int) # 0 if it can't be converted
intValue = var.getValue(int, default=10) # 10 if it can't be converted
# Getting the float value
intValue = var.getValue(float) # 0 if it can't be converted
intValue = var.getValue(float, default=98.6) # 98.6 if it can't be converted
==== Commands (indigo.variable.*) ====
=== Create ===
Create a variable. This method returns a **copy** of the newly created variable.
^ Command Syntax Examples ^
|indigo.variable.create("VariableName", value="Var Value", folder=843920)|
^ Parameters ^^^^
^ Parameter ^ Required ^ Type ^ Description ^
|//''folder''//| No | integer |id or instance of the folder in which to put the newly created device - defaults to 0 (no folder)|
|//''name''//| Yes | string |the name of the variable|
|//''value''//| No | string |the value of the variable|
=== Delete ===
Delete the specified folder.
^ Command Syntax Examples ^
|indigo.variable.delete(123)|
^ Parameters ^^^^
^ Parameter ^ Required ^ Type ^ Description ^
|direct parameter| Yes | integer |id or instance of the variable to delete|
=== Duplicate ===
Duplicate the specified variable. This method returns a copy of the new variable.
^ Command Syntax Examples ^
|indigo.variable.duplicate(123, duplicateName="NewName")|
^ Parameters ^^^^
^ Parameter ^ Required ^ Type ^ Description ^
|direct parameter| Yes | integer |id or instance of the variable to duplicate|
|//''duplicateName''//| No | string |name for the newly duplicated variable|
=== Get Dependencies ===
Return an indigo.Dict with all the dependencies on this variable.
^ Command Syntax Examples ^
|depDict = indigo.variable.getDependencies(123)|
^ Parameters ^^^^
^ Parameter ^ Required ^ Type ^ Description ^
|direct parameter| Yes | integer |id or instance of the variable to get the dependencies for.|
The dictionary will look something like this:
>>> print indigo.variable.getDependencies(91776575)
Data : (dict)
actionGroups : (list)
controlPages : (list)
devices : (list)
schedules : (list)
Data : (dict)
ID : 552463741 (integer)
Name : Between condition test (string)
Data : (dict)
ID : 296710860 (integer)
Name : Greater than condition test (string)
triggers : (list)
variables : (list)
So, the dictionary will have 5 top-level keys: "actionGroups", "controlPages", "devices", "schedules", "triggers", and "variables". Each one of those keys will return a list object. Inside that list object will be multiple dicts, one for each dependency (or an empty list if there are none). Each dependency dictionary has two keys: "ID" which is the unique id and "Name" which is the name of the object.
=== Move To Folder ===
Use this command to move the variable to a different folder.
^ Command Syntax Examples ^
|indigo.variable.moveToFolder(123, value=987)|
^ Parameters ^^^^
^ Parameter ^ Required ^ Type ^ Description ^
|direct parameter| Yes | integer |id or instance of the variable|
|//''value''//| Yes | integer |id or instance of the folder to move the variable to|
=== Set Remote Display ===
Use this command to set the remote display flag for the folder.
^ Command Syntax Examples ^
|indigo.variable.displayInRemoteUI(123, value=True)|
^ Parameters ^^^^
^ Parameter ^ Required ^ Type ^ Description ^
|direct parameter| Yes | integer |id or instance of the variable|
|//''value''//| Yes | boolean |True to display the variable on remote user interfaces or False to hide it|
=== Update Value ===
Use this command to set the value of a variable without having to get a local copy first.
^ Command Syntax Examples ^
|indigo.variable.updateValue(123, value="New Value")|
^ Parameters ^^^^
^ Parameter ^ Required ^ Type ^ Description ^
|direct parameter| Yes | integer |id or instance of the variable|
|//''value''//| Yes | string |the new value for the variable|
==== Examples ====
# Create a new variable
newVar = indigo.variable.create("fooName", "fooMonster")
# Updating value via command space function:
indigo.variable.updateValue(newVar, "asleep789")
newVar.refreshFromServer() # refresh needed to update local's .value
# changing name property
newVar.name = "goodName"
newVar.replaceOnServer()
newVar.name = "bad name" # should throw because of space character
# changing name and values properties:
newVar.name = "goodName2"
newVar.value = "searchingForWaldo"
newVar.replaceOnServer()
indigo.variable.delete(newVar)
# Getting a variable using it's ID
someVar = indigo.variables[123]
# Getting a variable using it's name
someVar = indigo.variables["MyVarName"]