The Ghost Themes Developer Hub

Welcome to the Ghost Themes developer hub. You'll find comprehensive guides and documentation to help you start working with Ghost Themes as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

foreach

{{foreach}} Helper - Loop through available template data

Usage: {{#foreach data}}{{/foreach}}

Type
Parameters
Attributes
  • data (collection) - collection to loop over
  • columns (number)
  • limit (number)
  • from (number)
  • to (number)
  • visibility (string, default: "public")

Description

{{#foreach}} is a special loop helper designed for working with lists of posts. It can also iterate over lists of tags or users if needed. The foreach helper will output the content placed between its opening and closing tags {{#foreach}}{{/foreach}} once for each item in the collection passed to it.

The {{#foreach}} helper is context-aware and should always be used instead of Handlebars each when working with Ghost themes.

Simple Example

The main use of the {{#foreach}} helper in Ghost is iterating over the posts to display a list of posts on your home page, etc:

{{#foreach posts}}
<article class="{{post_class}}">
  <h2 class="post-title"><a href="{{url}}">{{{title}}}</a></h2>
  <p>{{excerpt words="26"}} <a class="read-more" href="{{url}}">&raquo;</a></p>
  <p class="post-footer">
    Posted by {{author}} {{tags prefix=" on "}} at <time class="post-date" datetime="{{date format='YYYY-MM-DD'}}">{{date format="DD MMMM YYYY"}}</time>
  </p>
</article>
{{/foreach}}

Note

The {{#foreach}} helper can only operate on the data available to it in the current template scope. You can find out what data a template has access to by looking it up in the context table, and you can fetch additional data using the get helper.

Data Variables

When inside a {{#foreach}} block, you have access to a set of data variables about the current iteration. These are:

  • @index (number) - the 0-based index of the current iteration
  • @number (number) - the 1-based index of the current iteration
  • @key (string) - if iterating over an object, rather than an array, this contains the object key
  • @first (boolean) - true if this is the first iteration of the collection
  • @last (boolean) - true if this is the last iteration of the collection
  • @odd (boolean) - true if the @index is odd
  • @even (boolean) - true if the @index is even
  • @rowStart (boolean) - true if columns is passed and this iteration signals a row start
  • @rowEnd (boolean) - true if columns is passed and this iteration signals a row end

Usage

{{#foreach}} is a block helper. The most common use case in Ghost, is looping through posts.

{{#foreach posts}}
<h2><a href="{{url}}">{{title}}</a></h2>
<p>{{excerpt}}</p>
{{/foreach}}

It's just as easy to loop through tags (although this is more easily done with the tags helper).

<ul>
{{#foreach tags}}
<li><a href="{{url}}">{{name}}</a></li>
{{/foreach}}
</ul>

{{else}} and negation

Like all block helpers, {{#foreach}} supports adding an {{else}} block, which will be executed if there was no data to iterate over:

{{#foreach tags}}
<a href="{{url}}">{{name}}</a>
{{else}}
<p>There were no tags...</p>
{{/foreach}}

Again, like all block helpers, {{#foreach}} supports using ^ instead of # for negation - this means that the {{#foreach}} and {{else}} blocks are reversed if you use {{^foreach}} and {{else}} instead.

{{^foreach tags}}
<p>There were no tags...</p>
{{else}}
<a href="{{url}}">{{name}}</a>
{{/foreach}}

The limit attribute

Passing {{#foreach}} a limit attribute, will tell it stop after a certain number of iterations.

{{#foreach posts limit="3"}}
{{! will stop after 3, no matter how many posts there are...}}
<a href="{{url}}">{{name}}</a>
{{/foreach}}

Note that as the {{#foreach}} helper is only passively iterating over data, not actively fetching it, if you set limit to a number higher than the number of items in the collection, it will have no effect.

The from and to attributes

Passing {{#foreach}} a from or to attribute will change the items which are output. Both attributes are 1-indexed and inclusive, so from="2" means from and including the 2nd post.

{{#foreach posts from="2" to="5"}}
{{! will start at the 2nd post, and stop at the 5th, outputting 3 posts, providing the posts per page setting is at least 5}}
<a href="{{url}}">{{name}}</a>
{{/foreach}}

The columns attribute

The purpose of this is to help developers build grid layouts. For example, if you wanted to output your posts in a grid of 3 columns, you can use the columns attribute to pass this information to the {{#foreach}} helper, and it will then set handy @rowStart and @rowEnd booleans you can use to add css classes:

{{#foreach posts columns="3"}}
<section class="{{post_class}}{{#if @rowStart}} row-start{{/if}}{{#if @rowEnd}} row-end{{/if}}">
<h2>{{title}}</h2>
<p>{{excerpt</p>
</section>
{{/foreach}}

This just makes it a little easier to style the left-most and right-most items in the grid.

The visibility attribute

As of Ghost 0.9 posts, tags and users all have a concept of visibility, which defaults to public. The key feature build on this so far is Internal Tags, which are tags where the visibility is marked as internal instead of public. These tags will therefore not be output in a {{#foreach}} loop unless you specifically ask for them.

By default the visibility attribute is set to the string "public". This can be overridden to pass any other value, and if there is no matching value for visibility nothing will be output. E.g. you can set visibility to be "internal" to only output internal tags. You can also pass a comma-separated list of values, or the value "all" to output all items.

{{#foreach tags visibility="all"}}

Data variable examples

@index, @number and @key

{{@index}} is the 0-based index of the collection - that is the "count" of the loop. It starts at 0 and then each time around the loop, {{@index}} increases by 1. This is useful for adding numbered classes:

{{#foreach posts}}
  <div class="post-{{@index}}">{{title}}</div>
{{/foreach}}

{{@number}} is very similar to @index, but starts at 1 instead of 0, which is useful for outputting numbers you want users to see, e.g. in styled numbered lists:

<ol>
{{#foreach posts}}
  <li>
    <a href="{{url}}">
      <span class="number" aria-hidden="true">{{@number}}</span>{{title}}
    </a>
  </li>
{{/foreach}}
</ol>

{{@key}} will contain the object key, in the case where you iterate over an object, rather than an array. There's no real use case for this in Ghost at present.

@first & @last

The following example checks through an array or object e.g posts and tests for the first entry.

{{#foreach posts}}
  {{#if @first}}
    <div>First post</div>
  {{/if}}
{{/foreach}}

We can also nest if statements to check multiple properties. In this example we are able to output the first and last post separately to other posts.

{{#foreach posts}}
    {{#if @first}}
    <div>First post</div>
    {{else}}
        {{#if @last}}
            <div>Last post</div>
        {{else}}
            <div>All other posts</div>
        {{/if}}
    {{/if}}
{{/foreach}}

@even & @odd

The following example adds a class of even or odd, which could be used for zebra striping content:

{{#foreach posts}}
        <div class="{{#if @even}}even{{else}}odd{{/if}}">{{title}}</div>
{{/foreach}}

Block Params

Handlebars recently added the concept of block params to its {{#each}} helper. In Ghost the {{#foreach}} helper has been upgraded to also support this feature.

Block params allow you to name the individual item being operated on inside the loop, E.g.

{{#foreach posts as |my_post|}}
   {{#my_post}}
      <h1>{{title}}</h1>
    {{/my_post}}
{{/foreach}}

Which is much the same as doing posts.forEach(function (my_post) {} in JavaScript. Useful with advanced features like the {{get}} helper.

Note: Handlebars has a built-in each helper, but Ghost's {{foreach}} helper has extra functionality, so we always recommend using {{foreach}}.

foreach

{{foreach}} Helper - Loop through available template data