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    

get

{{get}} Helper - Fetches a collection of data - posts, authors or tags

Beta Feature

The get helper is currently a Beta feature and should be not be used in production. For more information on what Beta means, see http://support.ghost.org/public-api-beta

To enable this feature, visit yourblog.com/ghost/settings/labs/ and tick the 'Public API' checkbox.

Usage: {{#get "posts"}}{{/get}}

Type
Parameters
Attributes

resource either:

optional:
block parameters for collection name and pagination
collection name - |collection pagination|

Browse:

Read:

Description

{{#get}} is a special block helper that makes a custom query to the Ghost API to fetch publicly available data. These requests are made server-side, before your templates are rendered. This means you can fetch additional data, separate from what is provided by default in each context.

In its most basic form it can perform a 'browse' query to create a block of data that represents a list of your posts, authors (users) or tags. That block of data can then be iterated over using the {{#foreach}} helper.

It can also be used to perform a 'read' query that fetches one specific author, post or tag if the relevant resource field - E.g. id or slug is provided as an attribute.

Please note: This is a powerful tool, that has the potential to be overused and cause problems on a blog.

Simple Examples

A basic request for posts, this will fetch 15 posts from the API including their related tags and author data.

{{#get "posts" include="tags,author"}}
    {{#foreach posts}}
   	    {{title}} 
    {{/foreach}}
{{/get}}

A basic request for a single post with id of 2, including its related tags and author data, using a block parameter.

{{#get "posts" id="2" include="tags,author" as |post|}}
    {{#post}}
   	    {{title}} 
    {{/post}}
{{/get}}x

Fetch all tags, and output them using the tags helper:

{{#get "tags" limit="all"}}{{tags}}{{/get}}

Usage

The {{#get}} helper has many more options than most helpers, the following section walks through the various options and how they can be used.

Parameters

The first parameter passed in is the name of the resource that you want to query. This can be either "posts", "tags" or "users" (authors).

posts - only published posts can be retrieved
tags - currently all tags can be retrieved
users - only active users can be retrieved

Example:

{{#get "posts"}}
    {{! Loop through our posts collection }}
    {{#foreach posts}}
   	    {{title}} 
    {{/foreach}}
{{/get}}

Block Parameters

As with the {{#foreach}} helper, it is possible to use block parameters to rename your returned data collection to make it easier to reference or more distinguishable.

Note: Block Params are entered between pipe symbols, which are vertical bars: |

Usage: as |featuredposts pagination|

The {{#get}} helper supports two parameters entered here. The first entry in the pipe refers to your returned data collection. The second entry refers to your pagination object.

Example using block parameters:

{{#get "posts" as |articles pages|}}
    {{! Loop through our articles collection }}
    {{#foreach articles}}
   	    {{title}} 
    {{/foreach}} 
    {{! Use our pages (pagination) object }}
    {{pages.total}}
{{/get}}

In the example above we are fetching posts which we will then refer to as articles in our loop and a pagination object called pages.

Read requests

If you are using the {{get}} helper to make a read request, e.g. you are passing a specific ID or slug that you want to fetch, you will need to use either block parameters to name your returned object, or to use the foreach helper as the result will be an array.

Using {{else}}

All block helpers support the {{else}} helper, which allows you to output content when the first block doesn't match. In the case of the {{get}} helper, this only happens if there is an error and is mostly useful for debugging whilst developing.

If you want to output different content when there are no results, you will need to use {{else}} with the {{#foreach}} helper.

{{#get "posts" filter="featured:true"}}
    {{! Loop through our featured posts }}
    {{#foreach posts}}
   	    {{title}} 
    {{else}}
    {{! If there are no featured posts}}
       <p>No posts!</p>
    {{/foreach}} 
{{else}}
  <p class="error">{{error}}</p>
{{/get}}

Attributes

The attributes that can be passed to the {{#get}} helper exactly match up to the query parameters that you can use in the Ghost JSON API. These allow you to specify the data to look for and how much data is returned. If you're making a 'browse' request (fetching multiple items) you can use any of these attributes and if you're making a 'read' request (fetching a single item by id or slug) only include is available.

limit

Specify the size of your collection
Allowed values: positive integer and 'all'
Default value: 15

It is possible to use the global "posts per page" setting which is 5 by default or it can be configured via the active theme's package.json file, this global value is available via the @config global as @config.posts_per_page.

Examples:

{{! Fetch the 20 most recently published posts }}
{{#get "posts" limit="20"}}{{/get}}

{{! Fetch all published posts }}
{{#get "posts" limit="all"}}{{/get}}

{{! Use the posts_per_page setting}}
{{#get "posts" limit=@config.posts_per_page}}{{/get}}

Note: If no limit attribute is provided the default value of 15 will be used.

page

The resulting collection from the {{#get}} query may be paginated, therefore you can choose which page of that collection you want to fetch.

Example:

{{! Fetch the 4th page of results }}

{{#get "posts" limit="5" page="4"}}{{/get}}
{{! In this case where limit = 5, we are accessing posts 16 - 20 }}

order

Specify how your data is ordered before being returned. You can choose any valid resource field in ascending (asc) or descending (desc) order.

Examples:

{{! Fetch the oldest 5 posts }}
{{#get "posts" limit="5" order="published_at asc"}}{{/get}}

{{! Fetch the 5 most recently published posts }}
{{#get "posts" limit="5" order="published_at desc"}}{{/get}}

{{! Fetch posts in alphabetical order of title ([0-9], A->Z) }}
{{#get "posts" limit="5" order="title asc"}}{{/get}}

include

When making an API request, the resulting response will only contain base data from the Resource itself.

A Resource may have additional related data that can be included to expand your collection.

Base Resource data:

There can be multiple includes separated by a comma.

The Post resource by default has a tags array and an author_id. These can be expanded to include more information.

Include options for Post: "author" - expands author, "tags" - expands tags.

The User and Tag resources can be expanded to include the post count for each resource.

Include options for User and Tag: "count.posts"

Note: If you include count.posts you can use it to order your collection.

Examples:

{{! Fetch posts with author }}
{{#get "posts" limit="5" include="author"}}
		{{#foreach posts}}
    		<span>Written by: {{author.name}}</span>
    {{/foreach}}
{{/get}}

{{! Fetch posts with author and tags }}
{{#get "posts" limit="5" include="author,tags"}}
		{{#foreach posts}}
    		<p>Written by: {{author.name}}</p>
        <p>Tags: {{tags separator=", "}}</p>
    {{/foreach}}
{{/get}}

fields

Specify which resource fields to retrieve.

You can choose multiple fields with a comma separating the string.

Example:

{{! Fetch only the title and slug for all posts using block params }}
{{#get "posts" limit="all" fields="title,slug" as |articles|}}
		{{#foreach articles}}
    		<a href="{{slug}}">{{title}}</a>
    {{/foreach}}
{{/get}}

Note: If you specify fields for posts, you cannot then use the {{url}} helper.

Summary of valid fields:

Resource
Fields

posts

id, uuid, title, slug, markdown, html, image, featured, page, status, language, created_at, created_by, updated_at, updated_by, published_at, published_by

users

id, uuid, name, slug, image, cover, bio, website, location, status, language, last_login, created_at, created_by, updated_at, updated_by

tags

id, uuid, name, slug, description, image, created_at, created_by, updated_at, updated_by

filter

This is a powerful tool that allows you to make a complex logic-based queries on the data to fetch. In its most basic form, you can choose to fetch posts that meet a simple boolean logic such as featured posts:

{{#get "posts" limit="all" filter="featured:true"}}
		{{#foreach posts}}
    		<a href="{{slug}}">{title}}</a>
    {{/foreach}}
{{/get}}

Filtering can be used to specify multiple rules using and or or* and can check for booleans, match against strings, look for items within a group, and many other things. For a full breakdown of the filtering syntax and how to use it, please see the Filter documentation in the API docs.

Passing data to filter

When used with the {{#get}} helper, filters can be passed data which is already available within your theme template. For example, if in your post.hbs file you wanted to get 3 more posts by the author of the current post, you can do so as shown here:

{{#post}}
	<h3><a href="{{url}}">{{title}}</a></h3>
  <section class="author-meta">
  <p>Post by: {{author.name}}</a></p>
  {{#get "posts" filter="author:{{author.slug}}+id:-{{id}}" limit="3"}}
    <p>More posts by this author:
      <ol>
				{{#foreach posts}}
          <li><a href="{{url}}">{{title}}</a></li>
        {{/foreach}}  
      </ol>
    </p>
    {{/get}}
{{/post}}

In this example, we look for posts with the author (which is an alias of author.slug) that matches the current author and that does not have the same id as the current post, so that we will get 3 different posts.

Note:

Resource field

Each Resource has at least one field that can be used as a parameter to change the API request from a browse request to a read request.

The Browse request provides a resource array and a meta object that includes a pagination object. The read request only returns a single resource object based on the field requested.

Summary of resources and valid read fields:

Resource
Read fields

posts

id, slug

users

id, slug, email

tags

id, slug

Examples:

  1. Get the post which has the slug 'welcome-to-ghost'
{{#get "posts" slug="welcome-to-ghost" as |post|}}
  {{#post}}
  <h2><a href="{{slug}}">{{title}}</a></h2>
  <div class="post-content">
    {{content}}
  </div>
  {{/post}}
{{/get}}
  1. Get the user with email '[email protected]'
{{#get "users" email="[email protected]" as |user|}}
  {{#user}}
  <section class="user-meta">
    <h4><a href="/author/{{slug}}">{{name}}</a></h4>
    <p>{{{bio}}}</p>
    <dl>
      <dt>website:</dt><dd>{{website}}</dd>
      <dt>location:</dt><dd>{{location}}</dd>
    </dl>  
  </section>
  {{/user}}
{{/get}}

Examples

Fetch all posts for a specific user and order them alphabetically by post title.

{{#get "posts" limit="all" order="title asc" include="author" filter="author:david"}}
    <ul>
  		{{#foreach posts}}
      		<li><a href="{{slug}}">{{title}}</a></li>
      {{/foreach}}
    </ul>
{{/get}}

Fetch all Users ordered by their creation date.

{{#get "users" limit="all" order="created_at asc"}}
    <ul>
  		{{#foreach users}}
      		<li><a href="/author/{{slug}}">{{title}}</a></li>
      {{/foreach}}
    </ul>
{{/get}}

Make a Tag Cloud

{{#get "tags" limit="all" include="count.posts" order="count.posts desc"}}
    <ul>
  		{{#foreach tags}}
      		<li><a href="/tag/{{slug}}">{{name}}</a></li>
      {{/foreach}}
    </ul>
{{/get}}

Limitations

There are a few known limitations with the {{#get}} helper at the moment, after all, it is in beta :wink+:

  • {{#get}} helpers may not work correctly when nested
  • Other async helpers may not work when nested inside a get block (you may see an aSyNcId_### error on your page).
  • you cannot yet filter on count.posts or on dates
  • ordering alphabetically may be case sensitive depending on database
  • {{pagination}} won't output anything sensible when used inside {{#get}} block - because the get helper can only fetch existing data, it doesn't create a /page/2/ version of the data you are fetching. If you're looking for something like this, you're probably looking for channels (coming soon).

get

{{get}} Helper - Fetches a collection of data - posts, authors or tags