Templating Language Guide

In this guide, we will learn what and how to use the Nunjucks template language.

Specifically, we will learn:

Understand what is a templating language
Learn how to use a templating language in PixieBrix
See examples of how to use the templating language Nunjucks to manipulate data

Understanding the templating language

PixieBrix uses the Nunjucks templating language inside the Page Editor to allow any user to modify data on the fly.

A templating language gives you superpowers: not the kind of superpowers where you can fly but in the form of the ability to modify text, numbers and data contained in variables, using a logical approach. It is similar to a small subset of a programming language. In fact, some people call using these templating languages metaprogramming.

The simplest example of template language you can write, in PixieBrix, is this one:

I have one cat named {{@catname}}

If you run this in the right context you will see the output being returned as

I have one cat named Tiger

You might be wondering - how come it replaced {{@catname}} with Tiger?

Let’s analyze how that worked:

We started with a line of text that contains a template variable.

The template variable is the part that says {{@catname}}

ℹ️

What happens when PixieBrix sees this variable? It replaces the variable with the value assigned to it.

In PixieBrix we replace all variables with their value - so if somewhere in the code I had specified that @catname was set to Tiger...that’s what the cat’s name would be outputted as.

Nunjucks has many more features:

Filters: For ex: you can apply functions to text-strings to make them uppercase, lowercase
Logical operations: IF-ELSE and FOR loops on lists, strings, etc
Math operations on numbers: Add, Subtract, Multiply, Divide etc
String manipulation: Make a text string shorter, replace words inside a string

Learn how to use a templating language in PixieBrix

Now that you know what Nunjuck is, you might be wondering: Where can I use it in PixieBrix?

In PixieBrix you can use Nunjucks templating language in pretty much any field you see that is of type “ABC”.

Typically that is a field which looks like this one:

A string field which supports Nunjucks

You can see the icon has ABC (in blue) written next to it.

In these fields you can write any Nunjucks you like: the advantage of using this, is that you can use Nunjucks to alter your data. It’s an elegant and quick way of manipulating data, add logic, use loops, conditionals etc.

There are some examples of how you can alter data in the next section.

This will allow your data flowing through the Page Editor to be dynamic, since you can manipulate it.

When using Nunjucks variables and expressions in the various input fields of the Page Editor, this data is parsed at execution.

Then the internal engine evaluates it and the values are recompiled into strings at run-time.

See examples of how to use Nunjucks templating language to manipulate data

Return a value with a short-hand if-statement (ternary operator)

{{ true if @variable == 'some value' }} This statement above will return true if the value of the variable called @variable equals the string of value ‘some value’ {{ 'nice one' if @variable == 1337 }} This statement returns the string ‘nice one’ if the value of the variable equals the integer 1337

Add filters to a text string or a variable to alter their output

ex1.
{{ @variable | title }}

ex2.
{{ ["Some", "dash", "text", "here"] | join("-") }}

ex3.
{{ "president pixie" | replace("pixie", "brix") | capitalize }}

In the first example, we pass the Title-ization filter to the variable @variable. Whatever value is contained into @variable will be altered to look like a Title. For example is the value of @variable was “this is a title” the output of that template would look like “This Is A Title” - making every first letter of every word a capital
In the second example, we’re using the join filter and specifying the joining parameter - a dash symbol- to join together every element of the array of text strings. The output of this example would look likeSome-dash-text-here
In the third example, we’re replacing, using the replace() filter function, the text pixiewith pixiebrix and then we’re capitalizing the whole sentence using the capitalize filter so that once executed it results in President brix

More resources to learn about Nunjucks

Related resource to learn about Nunjucks: Nunjucks Reference