Interacting with lists
When using Text Blaze, you might use Lists in your Snippets to store multiple pieces of information together, filter lists to specific subgroups, randomly select from a list, or power conditional logic.
Where will you find lists in Text Blaze?
Lists are used in multiple places throughout Text Blaze. As your use of Text Blaze becomes more advanced, lists will be a common way you interact with data within your snippets. You may define a list yourself, but other places that they’ll appear include:
- {formmenu} when the multiple option is enabled
- Splitting the text of a string into a list of words
- Retrieving data from Data Blaze
- External data retrieved through the {urlload} command
- Manually defining lists to use its values elsewhere
All lists are [contained within brackets with values separated,by,commas]. Some variables may be a list themselves, for example we could create a variable called numbers that is a list of numbers:
{=numbers}
Lists can be used for a variety of purposes that we’ll walk through in this guide. You can access single values in the list, turn multiple values of the list into a string, or transform the values in your list by iterating each list item.
Types of Lists
Ordered lists are lists that are in a specific order which can be identified by a numerical index, representing the position of that item in the list.
Using {=states} provides me with all of the values in my list: {=states}
I can use [n], with n being the position of the list value, to select a specific value from my list instead of getting the entire list. For instance, {=states[4]} provides me with the 4th item in the list, which is Washington: {=states[4]}
This list is ordered as 1: Connecticut, 2: Massachusetts 3: California, and 4: Washington. The number is not included in the list, but is implied by the position of the item in the list.
Keyed lists are lists that do not have a specific order, and the values of the list are paired with a key. The key can be anything that is alphanumeric and does not need to follow a specific pattern.
Using {=dog} provides me with all of the values in my list: {=dog}
I can append .keyname to the end of my list variable’s name to retrieve a specific keyed value, too. If the key name has a space in it or any other special character, use the format ["key name"] instead.
Retrieving the dog’s name: {=dog.name}
Retrieving the dog’s breed: {=dog["breed type"]}
This keyed list contains several properties about a dog, with each value in the list being tied to a descriptive key. The key "name" has the value "Dougie", the key "age" has the value "6", and so forth.
Adding individual values from a list to snippets
As illustrated in the previous section, it's possible to access specific items inside of a list using a formula field.
For ordered lists, the formula's format is {=listname[1]}, where the number in brackets indicates the index of the item inside the list.
For keyed lists, the formula's format is {=listname[key]}, where the key is the name of any key in the list.
To make it easy to add these to your snippets, click on the ... next to a list variable's name in the Text Blaze editor and choose the option you need.
Ordered lists
Keyed lists
Converting a list into a string
You may want to convert all or some of your list items into a string when your Text Blaze snippet is inserted. The join function is perfect for writing the values of your list more naturally. It takes a list and creates a string using the characters of your choice to separate these values.
| Function | Description | Example |
|---|---|---|
| join(list, del) | Creates a string by joining the elements of a list | join([1, 3, 9], "-") ⇒ 1-3-9 |
The most common use for a list in Text Blaze is a {formmenu} (dropdown menu) where multiple values are selectable. When using a dropdown menu that has multiple values, it will display your selected values separated by commas but not as a list. However, when interacting with the {formmenu}'s variable, the values are stored as a list.
As a reminder, you’ll love this home because of the enhancements the sellers have made to it: {=sellingpoints}.
In this example, the top line shows that selecting multiple items will display them as you would most likely type them. However, the second line shows that, if you wanted to re-use the values selected in that field an additional time later in your snippet, Text Blaze displays them as a list within brackets.
Using join allows us to create a more naturally-written string from that {formmenu} additional times.
Now let’s separate those list values into more natural-looking text in 3 different ways.{endnote}
Separating each value with a comma and a space:
As a reminder, you’ll love this home because of the enhancements the sellers have made to it: {=join(sellingpoints,", ")}
Separating each value into a new line with preceding dashes:
As a reminder, you’ll love this home because of the enhancements the sellers have made to it:
- {=join(sellingpoints,"\n- ")}
Using the special BLAZE_AND formatting:
As a reminder, you’ll love this home because of the enhancements the sellers have made to it: {=join(sellingpoints, "BLAZE_AND")}
Note the final example uses the special delimiter "BLAZE_AND" to create a list that is comma-separated, and ends with an "and" (e.g. "value 1, value 2, value 3, and value 4"). There is also "BLAZE_OR" for a comma-separated list ending with an "or" (e.g. "value 1, value 2, value 3, or value 4").
Filtering lists to only some values
Sometimes you may want to retrieve only some items from a list, defining the criteria for what values you want to retrieve. The filter function allows you to define criteria against which an existing list is evaluated, returning a new list containing only values that meet your criteria.
| Function | Description | Example |
|---|---|---|
| filter(list, fn(value, index/key)) | Returns a new list comprised of the elements where fn evaluates to yes | filter([1, 4, 9], v -> v > 3) ⇒ [4, 9] |
The filter function is formatted as follows:
{=filter([list-to-be-filtered], x -> <boolean function of x>)}.
For instance, if we had a list of numbers [1, 2, 3, 4, 5] and wrote a function of x -> x>2, the filter command would return a new list of [3, 4, 5].
Creating your filter criteria
To write the criteria of your filter, you'll need to create a boolean function. The format of x -> <boolean function of x> is how functions are evaluated against lists across Text Blaze, including filter and other functions we’ll see later in this guide, such as map, and list comprehension. Understanding how to use this format is necessary to interact with lists in more complex ways.
Since this function format is used when interacting with lists, think of "x" as representing each individual value in that list. -> introduces the start of the boolean function used to evaluate the values of those lists. The boolean function can be anything that resolves to yes/no, or true/false. Some examples might include:
- List value is greater than 2: x -> x>2
- List value is less than 10: x -> x<10
- List value contains the text "OTC": x -> contains(x, "OTC")
- List value equals today's date: x -> x={time: YYYY-MM-DD}
Note that "x" is a placeholder that can be replaced with the text of your choice, as long as it’s lowercase and contains no spaces. You could write the above examples in a variety of different ways:
- value -> value>2
- number -> number<10
- medicine -> contains(medicine, "OTC")
- date -> date={time: YYYY-MM-DD}
Practical example of using a filter
In this example, a medical professional is selecting prescribed medication from a {formmenu} in their snippet. Some of the medication is available over the counter, which is indicated in the value names with "OTC".
Using the {formmenu} command creates a list of the medications that were prescribed/selected. First, we’ll display that {formmenu} so you can make selections, then we’ll then use the filter function to filter the selected medication into a second list of prescribed medications that are available over the counter (OTC).
The following medication are available without a prescription and can be purchased over the counter: {=join(filter(prescriptions, x->contains(x, "OTC")), "BLAZE_AND")}
We first tell Text Blaze what list we want to filter (filter(prescriptions). Then, we tell it what to evaluate for each value in that list (written as "x") through the x -> <boolean function of x> format. In this case, we’re nesting contains(x, "OTC") into this, telling Text Blaze to filter the values (x) of the prescriptions list to any value that contains "OTC" in it. Finally, we’re using join with the BLAZE_AND formatting again to rewrite the resulting list more naturally.
Advanced list usage
Lists of Lists
Sometimes the values of a list will be lists themselves. This is commonly the case when you’re importing multiple fields of data from Data Blaze. This happens because related data needs to be stored together.
Let's say I've written a {dbselect} command to retrieve the names of all Professors and what their Building and Office Numbers are. I can do this by using “multiple” and “name” in my {dbselect} to get all values and group them in a variable called “profs”. This variable, “profs”, will be created as a list of lists, with each Professor and their Building and Office Numbers being stored together as a list. A sample of that data looks like this:
Notice how the entire set of data is wrapped in brackets [], and each comma-separated value in that list is contained in brackets as well. That is because this is a list, and each value of that list is a list itself. The lists that are values are keyed lists, with the keys of “full name” and “building & office #”
Quickly create a table from a list of keyed lists
List of lists can be quickly converted to tables inside of your Text Blaze snippet. To do so, find the Forms section of the list of dynamic commands on the right side of the Text Blaze snippet editor. At the top, each of your variables will be listed.
Click on the ... next to the name of a variable that contains a list of keyed lists, and a Insert table... option will appear. This table will automatically convert all values in your list of keyed list into a table.
Using the map function to retrieve portions of a list of lists
What if we have a list of lists, but we want to retrieve only some information from that list? Continuing the example from above, I might have a need to get only the names of Professors from the “profs” list that I retrieved from Data Blaze. I could do a second {dbselect} from Data Blaze, or I can use the map function to create a new list from my existing “profs” list.
The map function is formatted similarly to the filter function, using the X ->
To retrieve only the first names, I would write a map command as follows:
Instead of evaluating a boolean function that resolves to yes/no or true/false, I’m using my function to specify what portion of the list I’d like to retrieve. To understand what is happening in this command, remember that each value of the “profs” list is a keyed list. This command is telling Text Blaze to look at each value in the “profs” list, and then retrieve only the value of that value’s list that has the key of “full name”. I can replace “full name” with any other key in that list to get those values instead.
Combining map and filter
Getting more complex with the same example, I can nest my map and filter functions to get a more granular set of data. Maybe I don’t want to retrieve the name of every professor, but only professors that have offices in the building Quinlan. Starting with the filter function, I can narrow the “profs” list to only profs in the Quinlan building. Then, using the map function, I can separate out the Full Names of that filtered list into their own list:
Filter as a standalone function, saving the results as the variable “filteredprofs”: {filteredprofs=filter(profs, x -> contains(x["building & office #"], "Quinlan"))}
Using the map function on the list that was newly-created above, filteredprofs: {=map(filteredprofs, x -> x["full name"])}
Combining both the filter and map statement into a single line: {=map(filter(profs, x -> contains(x["building & office #"], "Quinlan")), x -> x["full name"])}
List Comprehension as an alternative to map and filter
List comprehension works similarly to the map function, but is written slightly differently. While map and list comprehension yield the same results, one benefit to list comprehension is that you can use an if statement to filter your results at the same time. With the map function, you’d need to combine a map and filter command for the same results. As a result, list comprehension can sometimes be a bit easier to read.
List comprehension is written in the following format:
{=[changetox for x in listgoeshere if condition]}
- changetox for x is the equivalent of the map function's x ->
. This is how the original list's values are being transformed (such as x^2) - in listgoeshere defines what the original list we're transforming is
- if condition is optional and can be used as an equivalent to the filter command (such as if x>4)
To accomplish the same thing as the map and filter example in the previous section, I could write this as a list comprehension that is a little more readable:
Combining List Comprehension with the {repeat} command
In most examples in this guide, the end result of the command or function have been another list. If you have a list and want to transform its values without the results themselves becoming a list, you can combine list comprehension and the {repeat} command.
Continuing the example above of our “profs” list, what if we wanted to write a sentence that told us each professor’s name and their office location? We could do that through this combination:
{profs=[["full name":"Dennis Rodgers", "building & office #":"Quinlan #302"], ["full name":"Gerald Wiley", "building & office #":"Tooken #340"], ["full name":"Vernon Myers", "building & office #":"Quinlan #430"]]}
{repeat: for x in profs}Professor {=x["full name"]}'s office location is {=x["building & office #"]}. {endrepeat}
To quickly add a repeat to your snippet, find the Forms section of the list of dynamic commands on the right side of the Text Blaze snippet editor. At the top, each of your variables will be listed.
Click on the ... next to the name of a variable that contains an ordered list, and a Insert repeat... option will appear.