Twig Variables in BranchCMS

Variables are the primary way that you output data in templates. Here is an example variable using a blog post for our data set.

{{ post.content }}

The above tag will simply output the post content value.

Variables can have a simple name like {{ header }} and hold a string value.

Or, variables can represent an array of data like the {{ post }} variable above. The {{ post }} variable represents an array of data and content is just one value in that array. If the variable is an array then you access values in the array using the dot syntax. For example: 

{{ post.content }}
{{ post.abstract }}
{{ post.postTitle }}

We've taken Twig variables beyond an array and in a lot of cases what looks like an array is actually a data object. This gives you superpowers as a developer and it allows you to manipulate data before it's used. For example, if your data represents an image and its HTML tag, then you can manipulate the image tag data before it's displayed. You can even add custom attributes to the image tag. In the example below we will check and see if the alt text is set for the image, and if not, set it before outputting the image tag.

{% if image.alt|length == 0 %}
    {% set image.alt = 'My custom alt text' %}
{% endif %}
{{ image.tag }}

You can also modify variable values by using filters. For example, to convert a string to be camel-cased you can use the camel filter.

{{ post.postTitle|camel }}

Where do the variables come from?

There are two types of variables that you will use in your template.

  1. Page/app-specific variables
  2. Global variables

Variables that are specific to a page or an app are set in the context of that app, page, or item. Some examples include:

  • Content Builder Element field variables are only available in the template for that Content Builder Element.
  • Form field variables are only available in the template for the form that the field is part of.
  • Blog post variables are only available within the Blog app, while Store product variables are only available within the Store app.

Global variables are variables that are available in either all or most templates across your entire site. We'll discuss them in more detail next.

Global variables

You can easily identify global variables in templates because they start with an underscore ( _ ). For example: 

{{ _page.title }}
{{ _page.content('sidebar') }}
{{ _core.settings.companyName }}
{{ _core.date.year }}
{{ _page.cookies.cookieName }}

There are four types of global variables.

API variables

These are sort of like variables because they could be used to output a single value, but typically they are a way to retrieve data from another section of your website. We call them API variables because they make an API-like call internally to either:

  • get data from another section of a site
  • set or update data in another section of the site
  • display data from another section of a site

Learn more about making API calls.

A few simple examples include:

  • Displaying a form on a page.
  • Retrieving recent blog posts to display on a home page.
  • Displaying store categories in the sidebar of a product page.

Core variables

Core variables hold data that is not page-specific and can be used in nearly all templates.

Learn more about core variables.

Page variables

Page variables hold data that is specific to a page. For example, the SEO title for the page. See the Page Object section for more information.