List Helpers

Shortcuts and helpers for working with tag pairs.

Tag pairs have three different types of helpers available: helper parameters, helper variables, and output shortcuts.

Helper Parameters

Tag pairs have a number of helpers available to make a data-set more flexible and useful. They can be used in any combination with each other to manipulate and modify the display of your data.

As an example, let’s say that you have a variable that looks like this:

variable:
  -
    item: Satchel
    quantity: 250
  -
    item: Backpack
    quantity: 5
  -
    item: Knapsack
    quantity: 30

With helper parameters, you can sort this list when you display it by any of the values it contains:

{{ variable sort_by="item" }}
{{# returns order: Backpack, Knapsack, Satchel #}}

{{ variable sort_by="quantity" }}
{{# returns order: Satchel, Knapsack, Backpack #}}

{{ variable sort_by="random" }}
{{# returns items in random order #}}

And remember that within your tag pairs, you can use single variable modifiers on each of the values when you display them.

View the complete list of helper parameters available.

Helper Variables

Tag pairs loop through their data, rendering what’s between their tags on each pass through the loop. During each of these passes, all of your tag pair’s single variables are available, but Statamic also provides a couple of helpers as well.

For example, the {{ first }} variable will be true during the first pass at the tag pair loop. If you want to display a header above your tag pair data, for example, you could do something like this:

{{ groceries }}
   {{ if first }}
      <h2>Grocery List</h2>
   {{ endif }}

   Would you please grab some {{ name }}?<br>
{{ /groceries }}

The <h2> will only be printed on the first pass through the loop.

View the complete list of helper variables available.

List Output Shortcuts

A lot of the time, all you’ll want to do with a list is list the items on the page with no frills. In those cases, Statamic has a couple of handy single-tag shortcuts that you can use with your tag pairs.

For this example, let’s assume we have a variable that looks like this:

activities: [ fishing, hunting, trapping ]

This is a simple list in YAML. If we want to display these as a comma-separated list, we can do use the single tag {{ variable_list }}.

{{ activities_list }}
{{# prints: fishing, hunting, trapping #}}

By adding _list onto the end of the name of our tag pair, it became a single variable that displays all of the items in our list.

Using taxonomies and want a quick list of the categories used along with links to their respective pages? Simple.

{{ categories_url_list }}
{{# prints a comma-separated list of links to content's categories #}}

View the complete list of output shortcuts available.