Parentheses: attribute 'offset' references (offset addressing)

Referring to attributes of the current note

In action code, when calling the value of an attribute the value returned is for the current note. In most normal cases this is the note currently selected in the view (or the first item in the selection for a selection of notes). Getting the colour of the current note is coded like so:

$Color 

So it could also be written as:

$Color(this) 

as in specifying 'this' note. But, here the explicit use of the this designator is redundant, as is coding the action as:

$Color() 

All the above 'mean the same thing to the Tinderbox action code parser, but the first example is the normal usage. The value returned is the value set for that note, or an inherited value. Inheritance of attribute is discussed separately, here. The syntax above is used for both reading and setting values:

$MyColor = $Color; 

$Color = "blue"; 

Addressing (referring to) attributes of the current note

But what if there is a need to fetch a value of the same attribute, but from a different note? That is where those trailing parentheses come into play. To fetch the value of $Path for a note called "Prospects", the note title of target source note for the value—its $Name—is given as an argument inside the parentheses:

$Color("Prospects") 

Note it is the same as for the current note but extra information is now supplied in parentheses directly after the attribute name:

$Color("Prospects") Correct

Do not use white space between the name and opening parenthesis:

$Color ("Prospects") WRONG

The same method applies whether or getting a value in another note:

$MyColor = $Color("Prospects"); 

or setting a value in another note:

$Color("Prospects") = "blue"; 

For offset addressing there is only ever one argument inside the parentheses.

The basic syntax for an offset addressing is as basic as that.

Other ways to specify the argument for offset addressing (i.e. to a different note)

The two methods above are the most common form of specifying the source/target. Occasionally, such as when two notes in the same container (or map) have the same $Name, this means their path is the same. In this case, the note's ID can be used via $IDString (which supplants older use of $ID for this purpose). In this example note 'Prospects' has an $IDString value of "tbx:BktGvS":

$MyColor = $Color("tbx:BktGvS"); 

$Color("tbx:BktGvS") = "blue"; 

Also see the operator listing for $AttributeName[(scope)], which covers this topic from the perspective of action code operators.

What if the offset value needs to be variable value?

For instance, finding the $Color of the first child of the current note.

Designators. In this case a designator is used (for more about designator use in actions: see here). Here, the correct choice would be the 'child' designator:

$MyColor = $Color(child); 

$Color(child) = "blue"; 

Note that designators are not enclosed in quotes. This helps signal to Tinderbox that the argument is not a note title or path.

Attribute values. Another way to use a variable argument is to use a value stored in another attribute. If a Color-type attribute 'SomeColor' holds a colour value, then:

$Color = $MyColor; 

or putting together some lessons above

$Color("tbx:BktGvS") = $MyColor("Prospects"); 

Note that when reading or setting an attribute values, the attribute name must be prefixed with a '$' character.

Action code variables. Action code also allow creation of variable and these to can be used in an offset. Assume a variable 'vColor' has been defined and stored a colour value, then:

$Color = vColor; 

Evaluating arguments

In more complex situations it might appear there is a need to use an expression as an argument. Better is to evaluate that expression and store the result in an attribute or a variable and use the latter as the argument describing the offset.

Offset address arguments: when to quote or not?

Standard practice is to enclose literal text and titles ($Name) used as arguments within (straight) quotes but not quote note paths ($Path). The norm is to use double straight quotes but single straight quotes may be used instead. Doing the opposite generally gives the same result. But, users new to action code and/or without programming experience are advised to use the standard practice described. In addition, variables or attribute $-references are never enclosed in quotes. So:

$Color = "blue"; 

$Color = $Color("Prospects"); 

$Color = $Color(/the/path/to/Prospects); 

$Color = $Color($MyString); where $MyString holds a path or title value

$Color = $Color(vString); where vString holds a path or title value