📖
PixieBrix Documentation
📘

Text Template Guide

Text Templates Introduction

Text Templates are a way to dynamically create text on the fly when a brick runs. Here’s an example of a simple text template:

Hello, {{ @person.firstName }}!

In PixieBrix, you can use the Text Template entry mode to dynamically construct inputs for any field. Here’s the same template being used to create a greeting for the Window Alert brick:

Using the text template entry mode to dynamically create a greeting for the Window Alert brick.
Using the text template entry mode to dynamically create a greeting for the Window Alert brick.

To provide a text template in the Page Editor, ensure the field entry mode is Text Mode, as indicated by the ABC icon:

Toggle the Text entry mode for a field to provide a text template
Toggle the Text entry mode for a field to provide a text template

Basic Text Templates

The simplest text templates simply insert dynamic content:

I have one {{ @pet.type }} named {{ @pet.name }}

The content inside the mustache brackets {{ }} is called an expression. PixieBrix will fill the expressions with the available values when the brick is run. For example:

I have one cat named Tiger

Data Transformation using Filters

You can transform a expression by providing one or more filters in the template expression. Filters are provided using the | pipe operator.

For example, to upper case the pet’s name:

I have one {{ @pet.type }} named {{ @pet.name | upper }}

Will produce the following:

I have one cat named TIGER

Some filters accept arguments. To pass arguments to a filter, include the arguments list in parentheses: filter(arg1, arg2, ...)

Popular transformation filters are:

  • title: convert text to Title Case
  • truncate: truncate the text with ellipses. For example: @description | truncate(10) to truncate text to 10 characters.
  • join: concatenate values using a separator. For example: @names | join(",")

🤓
Under the hood, PixieBrix uses the popular Nunjucks templating language, developed by the non-profit that make the Firefox web browser!

Conditional Text

Text templates can be used to conditionally produce text for input to a brick.

Condition Expression

If there are only 1 or 2 simple cases, you can write the condition inline as an expression:

{{ "Meow" if @animal == "cat" else "Woof!" }}

Using Text Templates for Brick Conditions

Text Templates are the most convenient way to provide a Condition that controls if a single brick runs.

📖
Learn about the Brick Condition field in the the
🎨
Page Editor Guide
Using a Text Template condition expression to control when a brick is run.
Using a Text Template condition expression to control when a brick is run.

Text Templates can also be used to provide the condition for the If-Else brick. The If-Else brick can run multiple bricks if a condition is met.

Comparison and Logic Expressions

PixieBrix text templates support comparison and logical operators in expressions:

  • == , !=: equals and not equals
  • >, <, >=, <=: numeric comparison
  • and , or: logic
  • not: negation

Here’s an example showing comparison and logic in an expression:

⚠️
To provide multiple conditions using and or or, provide them within the same template expression
{{ true if @run > 0 and @animal == "cat" }}

Condition Tag

If there are multiple cases, or one or more cases are multi-line, you can use condition blocks to provide the cases: 

{% if @animal == "cat" %}
  Meow!
{% elif @animal == "dog" %}
  Woof!
{% else %}
  ???
{% endif %}

As you can see, blocks are designated using {% and %} tag instead of the {{ mustache braces. The tags are if , elif, else , and endif.

⚠️
Note that alternative cases use the elif tag with no space. I.e., as opposed to else if which is used in many programming languages ✅  elif ❌  else if

You can learn more about the if tag in the Nunjucks Template Language documentation.

Template Examples

Using variable paths that contain spaces in their names

Let’s assume a brick produces an output called @userPreferences and you want to reference the favorite color in a text template.

In the Page Editor Data Panel, the Output Data Tab might show:

Example Output Tab of the Data Panel showing data with names that include spaces.
Example Output Tab of the Data Panel showing data with names that include spaces.

To use the favorite color in a text template expression, you must use square brackets and quotation marks:

Your favorite color is {{ @userPreference.data["favorite color"] }}

Text substitution using the replace filter

To replace all occurrences of a word or phrase, use the replace filter. For example, to replace all occurrences of bricks with brix:

{{ @description | replace("bricks", "brix") }}

Chaining multiple filters in an expression

You can chain multiple filters using the | pipe operator. For example:

{{ "Lorem ipsum dolor sit amet" | truncate(15) | title }}

Will produce the following text output:

Lorem Ipsum...

Looping over elements of an array

You can use the for tag to loop over elements of an array. This is handy for creating bulleted lists in inputs that support Markdown, such as the Render Markdown brick

{% for @item of @items %}
- {{ @item }}
{% endfor %}

Twitter