Tag Paths
Tags and their properties can be referenced by a string-based path in many areas of Ignition, such as expressions and scripts. Each Tag has a unique absolute path and often has many equivalent relative paths when referenced from other Tags. In most cases these paths are generated automatically via helper buttons. However, it's a good idea to understand how Tag paths work, particularly if you need to configure an Indirect Tag Binding, or access a Tag from an expression, or script.
A Tag path looks something like this: [Tag Provider]folder/path/tag.property
The folder/path/tag.property portion of the path may contain the following:
- A Tag
- Any number of nested folders followed by a Tag, separated by forward slashes (/)
- A period (.) followed by a property name after the Tag. Omitting this is equivalent to using the .value property
The [Tag Provider] portion surrounded by square braces can have the following options:
| Source Option | Meaning |
|---|---|
[Tag Provider Name] | The name of the Tag provider that hosts the Tag. |
[] or not specified | The default Tag provider for the current project. If used in the Gateway scope, this notation can (generally) result in an invalid path, as the Gateway doesn't have a default Tag provider. |
[.] | Relative to the folder of the Tag that is being bound. This is especially useful in UDT definitions. |
[~] | Relative to the Tag provider of the Tag that is being bound (root node). |
[Client] | Refers to the Vision Client Tag provider, which contains only Vision Client Tags. |
[System] | Refers to a System Tag. |
Using Relative Tag Paths​
Tag paths that begin with [.] or [~] are known as relative paths. They are used inside Tags that bind to other Tags, and they are relative to the host Tag's path. Using the relative path syntax helps to avoid problems caused by moving Tags and renaming providers.
[.] refers to the Tag's current folder. By using [.], Tags can be moved from folder to folder without problem (provided that all of the applicable Tags are moved together). Additionally, you can use ".." (two periods) to go back one folder from the current relative position, for example [.]../../tag allows you to reference a Tag that is two folders up.
[~] refers to the Tag's provider root. It replaces an explicit provider name and thus protects the Tag path from "breaking" if the provider is renamed or if the Tag is imported/exported/moved between different providers.
Tag Path Manipulation Ignition provides a great deal of flexibility for Tag addressing since Tag paths and Tag properties are string-based. The underlying strings that compose a valid Tag path can be assembled from many different parts in which the eventual construction results in a valid Tag path.
The following scripting demonstrates this concept. Suppose there was a Tag path to a level indicator in a tank. In this case it is the default Tag provider, Tanks folder, Tank 1 Folder, and the Level Tag.
tagPath = "[default]Tanks/Tank 1/Level"
But suppose that there was more than just Tank 1 and instead there was Tank 2, Tank 3, Tank 4, etc. Dynamically changing the Tag paths is simple because Ignition's Tag paths are string representations. The following takes the tank number and inserts it into a new Tag path. The tankNumber variable changes the eventual creation of the tagPath. Using this method in scripting or in an expression binding will look slightly different.
tankNumber = 2
tagPath = "[default]Tanks/Tank %i/Level" % tankNumber
tag("[default]Tanks/Tank "+{Root Container.tankNumber}+"/Level")
The result of the tagPath variable will be [default]Tanks/Tank 2/Level which is a valid Tag path to the the level sensor for Tank 2.
Array Type Tag Paths​
When a path leads to an array type tag, individual elements can be accessed using square brackets, and the index offset.
[default]Folder/myArrayTag[0]
Document Type Tag Paths​
When a path leads to a document type tag, individual objects within the tag's value can be accessed by using square brackets wrapped around a set of quotations marks that lead to the object. For example, say we have a documentation tag with the following value:
The following would return "one", which is in the first element of the "key" array:
[default]myDocumentTag['key[0]']
JSON Values are references with a '.' character, so the following would retrieve the value of "two" inside of the "sub-object":
[default]myDocumentTag['sub-object.greetings']
For more complex structures, you can continue adding to the JSON string. The following would return "three" from the key in "deep-object":
[default]myDocumentTag['sub-object.deep-object.key']
Writing to Document Type tags​
The paths above aren't only for reading. Using the same addressing mentioned above on a bi-directional component binding would allow the binding to write back to the specific JSON object in the document.
Using the {this} Keyword​
Tags have a built-in "this" keyword, that can be used as a reference to the Tag. The keyword is useful in cases where an expression is being configured on a Tag property and you want to reference the value of another property.
// The expression below always returns the name of the Tag
{this.name}
Using {this} in Alarms​
The "this" keyword is also available for use on expressions on alarms. However when used like this, the keyword still refers to the Tag, not the alarm. Thus, "this.name" on an alarm property expression would return the name of the Tag, not the name of the alarm.
For more information on Ignition 's Expression language, see Expression Overview and Syntax.