Macros are encapsulated sections of text that may be used to insert larger or more complex sections of text back into the document or into exported pages. They are used in conjunction with the ^do()^ export code or do() action code. The former allows the user to insert the macro's output directly into exported text or HTML (as does do() if enclosed in ^value^. By contrast, internally do() is best used to populate string attributes values via actions and rules.
Macros cannot, generally, evaluate export or action code, so might best be thought of sections of boilerplate text with configurable text inputs. An exception is that ^do()^ may use export code, but only within the context of export from Tinderbox. There is thus a subtle difference in the behaviour of export code vs. action code invoked macros with regard to how inline code is treated.
Macros are managed via the Macro tab of the HTML Inspector.
Macro utility can be used in both queries and actions.
Within macros, the character $ prefixing a number has a special meaning which will be familiar to those who have used regular expressions before. $1 means "the first argument to the macro". This is actually the second argument in do(): the first is always the macro name (same applies to action and export versions). There is no limit to the number of arguments applied, though practicality precludes using excessive numbers; point being that unlike with regular expression back-references you may have more than 9 references, e.g. a $10.
These are applied recursively, so that if we have a macro called "Petshop" whose value is simply: $1
Then calling the macro…
^do("Petshop","This parrot is $2","dead!")^
…will give us…
This parrot is dead!
…whilst…
^do("Petshop","This parrot is $2","just sleeping.")^
…will give us…
This parrot is just sleeping.
In the above example note the need to allow for white space at string joins, so either a space between 'is' and '$2' or at the beginning of the second string.
Another example, take a macro named 'dot' whose value is:
<img src="anImage.gif" height="16" width="16" alt="">
…is called as…
^do("dot")^
…and results in…
<img src="anImage.gif" height="16" width="16" alt="">
As written, this is effectively just boilerplate insertion. To make this a more useful macro and allow it to set the image tag attribute's for name, height, width, and also set the alt to the image name then change the macro's value to:
<img src="$1" height="$2" width="$3" alt="$1">
…is called as…
^do("dot","pic.gif",20,30)^
…that results in…
<img src="pic.gif" height="20" width="30" alt="pic.gif">
Or, if the code is
<img src="$1" height="$2" width="$3" alt="$4">
…called as…
^do("dot","pic.gif",20,30,"caption")^
…that results in…
<img src="pic.gif" height="20" width="30" alt="caption">
If there is no caption, but no width/height, commas indicating a blank input should still be supplied:
^do("dot","pic.gif",,,"caption")^
…that results in…
<img src="pic.gif" height="" width="" alt="caption">
Trailing omissions should still be observed, as below where $4 is not supplied:
^do("dot","pic.gif",20,30,)^
…that results in…
<img src="pic.gif" height="20" width="30" alt="">
Whereas, a missed alt tag is not a show stopper, providing height/width tags with no value might be mistaken by a browser for a zero value. Better would be this macro code
<img src="$1"^if($2)^ height="$2"^endIf^^if($3)^ width="$3"^endIf^ alt="$1">
Escaping special macro characters. If you want to remove the special meaning from $ in a macro argument, precede it with a backslash \$. Commas in text strings should also be escaped lest they be parsed as argument delimiters, this \\. To insert a string like "Prices, $6 \ $16.", change the above macro to:
<img src="$1" height="$2" width="$3" alt="$4">
…and run as…
^do("dot","pic.gif",20,30,"Prices\, \$6 \\ \$16.")^
…to get…
<img src="pic.gif" height="20" width="30" alt="Prices, $6 \ $16.">
Export vs. internal use. In an export context the inline export code in the macro can only be accessed using the ^do()^ export code. Otherwise, all export/action code in the macro or input arguments is treated as literal text (but see the next paragraph below). For in-document actions, use the action code do() operator instead; export code should not be used inline in $Text except for actual export purposes.