Query (get) helper

One of the main new features we need to add to Ghost is a ‘query helper’ for themes. This is a helper that gives theme developers access to the API to make custom queries for data they’d like to display.

This helper will only provide access to the GET API endpoints that don’t require user authentication - that is getting published posts, and all tags, with all the sorting and filtering options which are available.

I propose that this helper be a block helper called ‘fetch’:

{{#fetch}}
  .. do stuff with the data here
{{/fetch}}

After that, there are a number of ways we could specify the details of the API call we want to make:

1. Just accept a string parameter that contains the API call URL: {{#fetch "/posts/?limit=5"}} {{#fetch "/posts/12/?include=tags"}}
2. Take the resource as a parameter, and use named attributes for the query params: {{#fetch "posts" limit="5"}} {{#fetch "posts" id="12" include="tags"}}
3. Also have the resource be a named attribute:

{{#fetch resource="posts" limit="5"}} {{#fetch resource="posts" id="12" include="tags"}}

1. Some other format?

We need to find a format that makes sense to theme developers. Using the API call URL as a string is very simple to implement, but all the /'s and ?'s and &'s look quite complex even though URLs are fairly well understood thing.

The second option is kind of inconsistent with itself, but it looks nice. It’s also similar to doing something like {{date published_at format="dd mm YY"}} where there can be a parameter and an attribute, and just like the date helper defaults to published_at, the fetch helper can default to posts.

The third one makes everything consistent, but as soon as you start using named parameters you need to do something like id="12" or slug="welcome-to-ghost" if you want to specify an id, or a slug etc to fetch a specific resource.

Thoughts on a postcard please!

[ErisDS]

Here’s a little bit of how I imagine it working:

In post.hbs, display the 5 most recent posts in a sidebar:

{{#post}}
<article>
  <header><h1>{{title}}</h1></header>
  <section>{{content}}</section>
  <footer>Published at {{date format="DD MMMM YYYY"}}</footer>
</article>
{{/post}}
{{#get "posts" limit="5"}}
  <aside>
    <ol>
    {{#foreach posts}}
      <li>{{title}}</lI>
    {{/foreach}}
    </ol>
  </aside>
{{else}}
  <p>No posts available</p>
{{/get}}

In index.hbs, display a list of all tags in a sidebar:

{{#foreach posts}}
    {{! output partials/post.hbs}}
    {{> "post"}}
{{/foreach}}
{{#get "tags" limit="all" order="alpha"}}
  <aside>
    <ul>
    {{#foreach tags}}
      <li>{{name}}</li>
    {{/foreach}}
  </ul>
</aside>
{{else}}
  <p>No tags available</p>
{{/get}}

[online]

@dbalders thank you, this is just what I need! 😉