Text substitution provides a way to insert a text value in any line of a list. The $ character is used in front of a variable name to do the substitution. For example:
Maintenance tasks for room $roomNum on floor $floorNum
Text substitutions can be made in any normal line, in any prompt text, or any assignment with a “text” operand. They cannot be used in the markup tag line of a prompt or branch (e.g. ? (question) $var). They also cannot be used in the markup tag line of a link, but they can be used in the list link's optional header line:
@ (local) snow_skiing/ski_gear
{
Pack ski gear for $person
}A line can have one or two variable text substitutions. If a dollar sign needs to be present in the generated output, then “escape” it with a second dollar sign. For example, the line Bring $$20 for food would appear as “Bring $20 for food” in the generated checklist.
Text substitution works for any kind of variable. If the variable is a number, then its numerical value will be substituted into the text. If a boolean, then the word “true” or “false” will be substituted.
Here, a custom prompt message can be created with the name of an additional passenger whose name is stored in variable $name from a previous text prompt. The user will be prompted with a message with the person's name substituted-in.
? (question) bringCarryon
[
Need to bring a carryon bag for $name?
]This is also useful in situations where the same prompt will be used many times, but with a text substitution to customize the message displayed to the user each time.
In this example, a list of road trip items for a guest will be included. Above the list items, a header line with their name will appear.
? (text) guestPassenger
[
What is the guest's name?
]
@ () packing/guests/road_trip_items
{
Pack things for $guestPassenger
}Text substitutions can be used with quantities, time, or inventory. The values can be adjusted as in the example below, and then seamlessly included in the output checklist.
? (number 2:30) guests
[
How many people will attend?
]
Pack for picnic
Paper plates ($guests)
= napkins = guests * 3
Napkins ($napkins)
Cups ($guests)Sometimes lists can become long and contain many variables and links. Depending on how they are organized and written, it may be difficult to understand why the final result is unexpected. Text substitution can be used to display a variable's value in the result, which can help to understand how to correct the problem.
A text substitution references a variable in order to get its text value to put onto a line. This reference exposes the list to a possible variable ordering error, which is discussed in the Variable Ordering section of the syntax page.