====== Tokens ======
A token is basically a variable that you can store data in or retrieve data from at runtime in your guiDesigner projects. A token has a name and a value.

===== Token Naming =====
Suggested Syntax: ''[name]''

A token can be named anything you like, but we suggest you follow the syntax above, including the square brackets in your token names. By doing this, it makes it easier to see where your token is actually being used within command values, etc.

===== Types of Tokens =====
There are three types of tokens:
  - Global Tokens
  - Predefined Tokens
  - Object Tokens

==== Global Tokens ====
As the name suggests, a global token is available to be used globally throughout your guiDesigner project.\\
Global tokens are defined in Project Properties > Global Token Manager.\\
A global token is the only type of token that can be set to persist its data across launches of iViewer, so you can store state data and retrieve it again the next time iViewer is opened.

Using our [[software:iviewer:iviewer-javascript-api|JavaScript API]], you could persist a JSON string across sessions and restore the JSON object on each launch, allowing you to theoretically store any dynamic data across launches.

<WRAP center round important 80%>
NOTE: Data is not persisted across GUI reloads. Each time the GUI is reloaded (when Reload GUI Layout is enabled in [[software:iviewer:settings|iViewer Settings]]), global token values will be reset to their default value (or blank if no value is defined in the Global Token Manager).
</WRAP>

==== Predefined Tokens ====
There are a number of tokens that are predefined for you in certain cases, depending where the token is being used.

=== Globally defined ===
  * ''[ipv4address]'' - The IP Address of the device.
  * ''[ipv4netmask]'' - The subnet mask of the device.
  * ''[ipv4addresshex]'' - The IP Address of the device, in hex bytes.
  * ''[ipv6address]'' - The IPv6 Address of the device.
  * ''[ipv6netmask]'' - The IPv6 subnet mask of the device.
  * ''[networkSSID]'' - The SSID of the Wi-Fi network currently connected.
  * ''[networkType]'' - The network type currently being used for communications. Eg. None, WiFi, WAN, Other, VPN.
  * ''[uuid]'' - The device ID of the mobile device running iViewer that is used for licensing purposes.
  * ''[MACAddress]'' - The MAC Address of the device. Note this will return '02:00:00:00:00:00', since Apple denies any app from accessing the MAC Address since iOS7 onwards.

=== Attached to every GUI object ===
  * ''[join]'' - The join number and join type of the object, e.g. 'd10' for a [[software:gui-designer:joins|digital join]] of a [[software:gui-designer:buttons|button]], 's4' for the [[software:gui-designer:joins|serial join]] of an [[software:gui-designer:images|image object]], 'a12' for the [[software:gui-designer:joins|analog join]] of a [[software:gui-designer:sliders|slider object.]]
  * ''[@<join>]'' - Get the 'value' of a specific join. eg: ''[@s10]'' would return the value of serial join 10. ''[@d5]'' would return the value (0 or 1) of digital join 5.
  * ''[@<join>:<token>]'' - Same as above, but returning the value of a specific token assigned to a specific join. eg. ''[@l5:[count]]'' would return the number of list items in the list assigned join 5.

=== Attached to all Objects within Lists ===
Any object within a list ([[software:gui-designer:buttons|button]], [[software:gui-designer:sliders|slider]], [[software:gui-designer:images|image]], etc) will automatically have the following tokens attached to it:
  * ''[list_join]'' - The join number of the list that the object resides in
  * ''[item_index]'' - The list index (zero based) of the list item that the object resides in.
  * ''[count]'' - The total number of items the list contains.
  * ''[visible]'' - The total number of items that are currently visible within the list.
  * ''[top]'' - The index of the first visible item within the list.
  * ''[scrolloffset]'' - The scroll position of the list in pixels.

=== Attached to gesture actions ===
See the [[software:gui-designer:gestures#pinch-zoom|gesture wiki entry]] for details on the predefined tokens available for gesture actions.

=== Attached to sliders ===
  * ''[sliderval]'' - The numerical value of the current slider position, based on the [[software:gui-designer:sliders|slider's]] min and max settings.

=== Attached to input fields ===
  * ''[inputval]'' - The string value of the input field's current text.
==== Object Tokens ====
Tokens can be assigned to any object via its join number at runtime. These tokens can be set and retrieved at runtime only. For example, you can store the state state of something in a token applied to a button. Then when that button is pressed, use the token value as part of the command that the button sends, or even use the token within a math expression or JavaScript function that the button calls.

===== Using Tokens =====
Tokens can be used throughout your guiDesigner project in a number of ways:
  * Via our JavaScript API
    * [[http://www.commandfusion.com/docs/scripting/gui.html#cF.setToken|Setting token values]]
    * [[http://www.commandfusion.com/docs/scripting/gui.html#cF.getJoin|Getting token values]]
  * Within command values - simply use the token name within a command value and it will automatically be replaced with the token value when the command is sent.
  * In [[software:gui-designer:system-manager:feedback-parsing:feedback-properties|feedback processing]]
  * Within [[software:gui-designer:math-expressions|math expressions]]