PyroCMS Tags

What are tags?

One of the unique features of PyroCMS is Tags, powered by the Lex Parser. Tags allow you to tap into more advanced functionality using simple syntax right inside your page layouts and even pages themselves. Tags can allow you to do some really powerful things without crowding your layouts with messy PHP code.

The following guide will teach you the basics of tags and how to use them in your layouts.

Basic Tags

At their very basic form, tags are simply a variable:

{{ my_var }}

When you put that in your markup, it will be replaced by some value. Pretty simple! Generally, the whitespace as shown in the example should be used.

Now let's take the example of a common concept in PyroCMS: a tag with two words separated by a colon:

{{ settings:site_name }}

This tag has some basic parts: two curly braces on either site and two text strings separated by a colon. This format tells PyroCMS that we want to access a plugin's function or plugin's variable. The first string, settings in this case, tells the tag what plugin to reference and then the second string, site_name in this case, tells the tag what function or variable to call.

So if we put the above tag in our layout and our site_name variable was set to "Bill's Bagels", then it would return:

 Bill's Bagels


If you'd like to comment out a section of code or content, you can wrap them inside {{# and #}}. Ex: {{# This is a comment #}}. This has the advantage over conventional HTML comment tags that it won't be visible to users viewing your website's source code. There must be a space after the first # and before the final one.

Tag Attributes

What makes tags really powerful is they can take attributes that give you the freedom to modify the tag output based on input data. Here is an example:

{{ url:segments segment="1" }}

In the above example, we are calling the url plugin which has a segments function. This is all well and good, but we can also pass the tag parameters in order to modify the output. In this case, we are telling the tag to get the first segment. So if your URL was, this tag would return:


You can have multiple parameters as well. So, for example, the segments function allows you to specify a default value via a second parameter:

{{ url:segments segment="1" default="home" }}

If the first segment is empty, the tag will return "home".

Some parameters are required and some are optional. Check the plugins section to make sure you are passing all of the right parameters and if there are any optional ones that will give you added functionality you need.

Using Tags and Variables In Tag Parameters

Inside quotes, PyroCMS cannot parse curly braces. So, for instance, if you wanted to pass the value of the slug from the page plugin, this will not work:

{{ url:segments segment="1" default="{{ page:slug }}" }}

However, you can pass a plugin function's output value or variable by eliminating the curly braces. So, this will work:

{{ url:segments segment="1" default=page:slug }}

You can also use tag parameters in functions that are being used as a tag parameter by using a single curly brace with no spaces and no quotes:

{{ url:segments segment="1" default={foo:bar value="baz"} }}

Although this is an easy solution for single functions and variables, for more complex logic within tag paramters, you can use square braces instead of curly braces, like this:

{{ url:segments segment="1" default="[[ page:slug ]]" }}

PyroCMS parses each parameter separately for square brackets, so you can even do logic within your paramters:

{{ url:segments segment="1" default="[[ if global:environment == 'development' ]]dev_home[[ else ]]home[[ endif ]]" }}

Tag Pairs

Another powerful feature of PyroCMS tags is the ability to use data between tags. Take this example of a blog posts tag:

{{ blog:posts limit="2" order-by="title" order-dir="desc" }}
     <h2>{{ title }}</h2>
{{ /blog:posts }}

As you'll notice, we have an opening and closing tag here. In this case, the blog posts function will repeat and parse the content between our tag pair for each blog post that matches the criteria we set up with our tag parameters. So for this tag, we might get this output:

<h2>Blog Post One</h2>
<h2>Blog Post Two</h2>

Tag pairs don't necessarily loop through content, however. For example, we can simply use the content between the tags like we would a parameter, like in the format plugin:

{{ format:markdown }}Let's _convert_ this to **HTML**.{{ /format:markdown }}

Single Variable Loops

Occasionally, single tags can act as arrays of data that you can loop through. You can do so using a similar tag pair syntax:

{{ images }}
     <img data-pyroimage="true" src="{{ url }}" />
{{ /images }}

Tag Conditionals

Many times in your layouts you will want to show something under certain conditions. For instance, if a user is logged in or if a url segment has a certain value. PyroCMS tags allow you to do that with an if/else tag syntax.

Undefined variables in Conditionals are evaluated to be null. This allows you to do things like {{ if foo }} to check if a variable exists.

Basic Conditionals

Here is a simple example of a conditional tag statement:

{{ if user:logged_in }}
     <p>You are logged in.</p>
{{ endif }}

This general structure will look very familiar if you are acquainted with conditionals in languages like PHP. The first tag checks if the value of user:logged_in is true and returns what is between that tag and the endif tag.

Conditional Operators

You can use operators to compare values in an if statement. These used to compare two values. Here's an example:

{{ if {url:segments segment="2"} == 'categories' }}
    <p>Looks like you are in the categories section.</p>
{{ endif }}

PyroCMS function tags can be used in conditionals, but must be wrapped in single curly braces if they have one or more parameter, as in the above example.

When using function tags wrapped in curly braces in conditionals, the space after the opening curly brace and before the closing curly brace must be omitted. The tag will not render properly otherwise. Ex: {url:segments segment="2"}.

Here are the available conditional operators:

Operator Notes
== Equals. Values equal each other.
!= Does not equal. Values do not equal each other.
=== Values equal each other in value and type. For instance, if one value is a true boolean value, the other value must also be in order to fufill this operator.
!== Same concept as above but checks that values do not equal each other and are not the same type.
> Greater than
< Less than
>= Greater than or equal to
<= Less than or equal to

You can also use the ! or the not logical operator:

{{ if !user:logged_in }}
    <p>You are not logged in.</p>
{{ endif }}

{{ if not user:logged_in }}
    <p>You are not logged in.</p>
{{ endif }}

! and not are interchangeable. The only requirement is that not must have a space on both sides.

Checking if a Variable Exists

To check if a variable exists in a conditional, you use the exists keyword.


{{ if exists foo }}
        Foo Exists
{{ elseif not exists foo }}
        Foo Does Not Exist
{{ endif }}

You can also combine it with other conditions:

{{ if exists foo and foo !== 'bar' }}
        Something here
{{ endif }}

The expression exists foo evaluates to either true or false. Therefore something like this works as well:

{{ if exists foo == false }}
{{ endif }}

Multiple Conditionals

You can have multiple conditionals for some more advanced conditional statements:

{{ if variables:custom_var == 'foo' }}
    <p>Looks like a foo.</p>
{{ elseif variables:custom_var == 'bar' }}
    <p>Looks like a bar.</p>
{{ else }}
    <p>Neither foo nor bar.</p>
{{ endif }}

Logical Operators

You can also use logical operators like so:

{{ if variables:custom_var != 'foo' and variables:custom_var != 'bar' }}
    <p>No foos and no bars!</p>
{{ endif }}

The logical operators available are:

  • and / &&
  • or / ||