A path array describes the location of an element in your prototype, or within a component nested within your prototype. Each item in the array describes the next part of the path a script must follow to locate the element you’re targeting.
A path array always starts at the very top of the document tree, with the name of a page in your main prototype, then progressively steps down through the document to locate the target element.
Simple path arrays look like this:
[“Page 1”, “First Name”]
In the example above, the path describes an element on Page 1 of the main prototype, with the layer name First Name.
Note: Names of pages and component instances are case-sensitive.
If the element is located within a component, which is nested inside your prototype, the path will be longer.
For example, to describe a path to an element located within a component, the path array would look more like this:
[“Page 1”, “Menu overlay”, “Visible”, “Title”]
This path array is saying: On the page named Page 1 of the main prototype, locate the layer named Menu overlay (in this case the component), then inside that component, look for a page named Visible and then for an element/layer on that page with the name Title.
The path array pattern
Path arrays follow a pattern where they start with a page name, then the layer name of an element on that page. A path array will always ends with an element name.
[pageName, elementName, pageName, elementName]
Using path arrays in functions
The most common use for path arrays is to tell an Atomic function which specific element to target. For example, this could be when you’re using state() to change the state of a component, text() to get or set the value of the text element, scrollTo() to change the scroll position of a container (see the full guide to these functions).
Using the example above, if we wanted to change the value of the Title text element, we would pass the path array described above to the text() function as its first argument, then pass a second argument, a string, with the new value we want to set the text value to, like this:
text([“Page 1”, “Menu overlay”, “Visible”, “Title”], “Hello World”)
This script is saying: Locate the text element described in the path array and set its value to Hello World.
myPath = [“Page 1”, “Menu overlay”, “Visible”, “Title”]
text(myPath, “Hello World”)
Path arrays containing variables
menuState = “Visible”
myPath = [“Page 1”, “Menu overlay”, menuState, “Title”]
Here the value of menuState will be used as the third array slot when myPath is referenced. So if the value of menuState was changed to “Hidden”, the next time the path array was used, the array would read:
[“Page 1”, “Menu overlay”, “Hidden”, “Title”] .
SELF, the dynamic self-referencing path array object
In many cases the path to an element can’t easily be hardcoded. The most common case for this is when a script inside a component references an element within the component. In this situation the path array for the target element will contain both the path to the component and the path within the component to the target element.
For example, in the path array we looked at earlier:
[“Page 1”, “Menu overlay”, “Visible”, “Title”] the first two items describe the path to the component and the last two describe the path within the component to the target element.
Building on the example, if the Menu overlay component needs to be placed on more than just Page 1 of our main prototype, let say it needs to be present on Page 2 as well, then we can no longer just use a hardcoded path array pointing to the Text element in the array as it will only work in the component instance placed on Page 1.
In situations like this, we need a way for a script to dynamically find out ‘where in the document am I?’ and for that to be included in the path array to the target element dynamically. This is where the SELF object comes in.
What is SELF?
Next, with your browser console open, enter Preview mode and you’ll see the value of SELF printed to the console.
If we had a simple prototype with only one page, which was named Page 1 and we wrote a simple script inside a 0sec delay page action that contained
console.log(SELF) we would expect SELF to simply return:
If we moved that script down into a page action inside a component, like on the Visible page within the Menu overlay component mentioned earlier, which was located on Page 1 of the main prototype, then we would expect SELF to return:
[“Page 1”, “Menu overlay”, “Visible”]
If instead of running the script as a page action inside the component, we moved that script to be run when a user clicked on a hotspot on the ‘Visible’ page, which had a layer name of ‘Hotspot’ then we would expect SELF to return:
[“Page 1”, “Menu overlay”, “Visible”, “Hotspot”]
Working with SELF
If SELF returns the exact path array you need, then you could use it like this:
In this case, the function will look for a component at the location returned by the path array provided by SELF, if one exists, the script attempts to change that component’s state to “Hidden”.
It’s also common to want to modify the value SELF returns before using it, such as adding items to, or removing items from the array.
Earlier we saw the following path array:
[“Page 1”, “Menu overlay”, “Visible”, “Title”]
In this example, Menu overlay is a component, and Visible is a page within it. Let’s imagine that we are writing a script as a page action on the Visible page, that attempts to change the value of the Title text element also on that page.
When our script calls SELF, it is going to be returned
[“Page 1”, “Menu overlay”, “Visible”] because this is the path to the page our script is located on. This is close, but not a complete path to the text element we want to target, we still need to add one item to the path array.
To see what that returned, we could print this to the console:
console.log( SELF.concat([“Title”]) )
// Expected result: [“Page 1”, “Menu overlay”, “Visible”, “Title”]
We could then pass that to a text() function like this:
Tip: Notice how “Title” is enclosed in square brackets like this: [“Title”]? That’s because concat will only work in this way when we are joining two arrays (the array returned by SELF, with this one).