Collection

Example

The most basic example would be to iterate over entries in a single collection:

{{ collection from="blog" }}
    {{ title }}
{{ /collection }}

You can also use the shorthand syntax for this:

{{ collection:blog }}
    {{ title }}
{{ /collection:blog }}

If you’d like to fetch entries from multiple collections, you can only do that in the standard syntax, like so:

{{ collection from="blog|events" }}
    {{ title }}
{{ /collection }}

To get entries from all collections, use *. You may also exclude collections when doing this.

{{ collection from="*" not_from="blog|events" }}
    {{ title }}
{{ /collection }}

Grouping entries by date

You can visually group repeating date-based entries.

When using this parameter, the templating structure you need to use will be a little different from a regular loop.

Example

Let’s assume that the entries in the blog collection are date-based.

{{ collection:blog group_by_date="M Y" as="entries" }}
    {{ date_groups }}
        <h3>{{ date_group }}</h3>
        <ul>
            {{ entries }}
                <li>{{ title }}</li>
            {{ /entries }}
        </ul>
    {{ /date_groups }}
{{ /collection:blog }}

The code above will output something like this:

<h3>May 2015</h3>
<ul>
  <li>A post from May</li>
  <li>Another from May</li>
</ul>
<h3>June 2015</h3>
<ul>
  <li>A post from June</li>
</ul>

The {{ date_group }} variable will be the date formatted by whatever you specifed in the group_by_date parameter.

The {{ entries }}{{ /entries }} tag pair will allow you to iterate over the entries in that date group. The name of this variable is specified by the as parameter. For example, if you used as="posts", you’d use a {{ posts }}{{ /posts }} tag pair.

Grouping by a custom date field

If you’d like to group by an arbitrary date field, you can specify the field name as the second value of the parameter.

{{ collection:blog group_by_date="M Y|purchase_date" sort="purchase_date" }}

Here we are grouping on the purchase_date field. Note that you should also sort by that field, as the default sorting on date-based entries would still be the entry date.

Filtering

There are a number of ways to filter your collection. There’s the conditions syntax for filtering by fields, taxonomy filter for using terms, and the custom filter class if you need extra control.

Conditions syntax

Want to get entries where the title has the words “awesome” and “thing”, and “joe” is the author? You can write it how you’d say it:

{{ collection:blog
   title:contains="awesome"
   title:contains="thing"
   author:is="joe"
}}

There are a bunch of conditions available to you, like :is, :isnt, :contains, :starts_with, and :is_before. There are many more than that. In fact, there’s a whole page dedicated to conditions - check them out.

Taxonomies

Filtering by a taxonomy term (or terms) is done using the taxonomy parameter, similar to the conditions syntax mentioned above.

To show entries with the harry-potter term within the tags taxonomy, you could do this:

{{ collection:blog taxonomy:tags="harry-potter" }}

There are a number of different ways to use this parameter. They are explained in depth in the Taxonomies Guide

Custom filters

Doing something complicated? You can reference a custom filter which can do the heavy lifting from outside of the template.

For example, want to filter drink entries by whether or not it’s one of the user’s favorites?

{{ collection:drinks filter="users_favorite" }}

This’ll load a custom filter file and do its thing from within there. Statamic makes the collection available to you, and you can manipulate it however you like. For example:

class UsersFavoriteFilter extends Filter
{
    public function filter()
    {
        $faves = User::getCurrent()->get('favorite_drinks');

        return $this->collection->filter(function($entry) use ($faves) {
            return in_array($entry->get('title'), $faves);
        });
    }
}

Read more about custom filters.

Pagination

To enable pagination mode, add the paginate="true" parameter, along with the limit parameter to specify the number of entries in each page.

{{ collection:blog limit="10" paginate="true" as="posts" }}

    {{ if no_results }}
        <p>Aww, there are no results.</p>
    {{ /if }}

    {{ posts }}
        <article>
            {{ title }}
        </article>
    {{ /posts }}

    {{ paginate }}
        <a href="{{ prev_page }}">⬅ Previous</a>

        {{ current_page }} of {{ total_pages }} pages
        (There are {{ total_items }} posts)

        <a href="{{ next_page }}">Next ➡</a>
    {{ /paginate }}

{{ /collection:blog }}

In pagination mode, your entries will be scoped (in the example, we’re scoping them into the posts tag pair). Use that tag pair to loop over the entries in that page.

The paginate variable will become available to you. This is an array containing data about the paginated set.

Pagination Examples

The auto_links tag is designed to be your friend. It’ll save you more than a few keystrokes, and even more headaches. It’ll output a Twitter Bootstrap-ready list of links for you. With a large number of pages, it will create segments so that you don’t end up with hundreds of numbers. You will see something like this:

It’s clever enough to work out a comfortable range of numbers to display, and it’ll also throw in the prev/next arrow for good measure. Nice, right?

Maybe the Bootstrap markup isn’t for you. You want something more custom. You’re a maverick. That’s cool. You’ll want to check out the links:all or links:segments arrays. These give you all the data you need to recreate your own set of links. The links:all array is simply all the pages with url and page variables. The links:segments will contain the segments like we mentioned earlier. You’ll be able to access first, slider, and last, which are the 3 segments.

Here’s the auto_links output, recreated using the other tags, for you mavericks out there:

{{ paginate }}
    <ul class="pagination">
        {{ if prev_page }}
            <li><a href="{{ prev_page }}">&laquo;</a></li>
        {{ else }}
            <li class="disabled"><span>&laquo;</span></li>
        {{ /if }}

        {{ links:segments }}

            {{ first }}
                {{ if page == current_page }}
                    <li class="active"><span>{{ page }}</span></li>
                {{ else }}
                    <li><a href="{{ url }}">{{ page }}</a></li>
                {{ /if }}
            {{ /first }}

            {{ if slider }}
                <li class="disabled"><span>...</span></li>
            {{ /if }}

            {{ slider }}
                {{ if page == current_page }}
                    <li class="active"><span>{{ page }}</span></li>
                {{ else }}
                    <li><a href="{{ url }}">{{ page }}</a></li>
                {{ /if }}
            {{ /slider }}

            {{ if slider || (!slider && last) }}
                <li class="disabled"><span>...</span></li>
            {{ /if }}

            {{ last }}
                {{ if page == current_page }}
                    <li class="active"><span>{{ page }}</span></li>
                {{ else }}
                    <li><a href="{{ url }}">{{ page }}</a></li>
                {{ /if }}
            {{ /last }}

        {{ /links:segments }}

        {{ if next_page }}
            <li><a href="{{ next_page }}">&raquo;</a></li>
        {{ else }}
            <li class="disabled"><span>&raquo;</span></li>
        {{ /if }}
    </ul>
{{ /paginate }}

Aliasing

Often times you’d like to have some extra markup around your list of entries, but only if there are results. Like a <ul> element, for example. You can do this by aliasing the results into a new variable tag pair. This actually creates a copy of your data as a new variable. It goes like this:

{{ collection:blog as="posts" }}
  <ul>
  {{ posts }}
    <li><a href="{{ url }}">{{ title }}</a></li>
  {{ /posts }}
  </ul>
{{ /collection:blog }}

Scoping

Sometimes not all of your entries have the same set of variables. And sometimes the page that you’re on (while listing entries in a Collection, for example) may have those very same variables on the page-level scope. Statamic assumes you’d like to fallback to the parent scope’s data to plug any holes. This logic has pros and cons, and you can read more about scoping and the Cascade here.

You can assign a scope prefix to your entries so you can be sure to get the data you want. Define your scope and then prefix all of your variables with it.

# Page data
featured_image: /img/totes-adorbs-kitteh.jpg

{{ collection:blog scope="post" }}
  <div class="block">
    <img src="{{ post:featured_image }}">
  </div>
{{ /collection:blog }}

You can also add your scope down into your alias loop. Yep, we thought of that too.

{{ collection:blog as="posts" }}
  {{ posts scope="post" }}
    <div class="block">
      <img src="{{ post:featured_image }}">
    </div>
  {{ /posts }}
{{ /collection:blog }}

Combining both an Alias and a Scope on a Collection Tag doesn’t make a whole lot of sense. You shouldn’t do that.

Parameters

Variables