{"_id":"5937b2388e8d9b002f1df289","category":{"_id":"5937b2388e8d9b002f1df272","version":"5937b2378e8d9b002f1df26e","project":"542fe92a5eceb608003fddc8","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-04T12:45:40.548Z","from_sync":false,"order":3,"slug":"helper-reference","title":"Helper Reference"},"user":"55acc88c6b4ff90d00784b61","parentDoc":null,"project":"542fe92a5eceb608003fddc8","version":{"_id":"5937b2378e8d9b002f1df26e","project":"542fe92a5eceb608003fddc8","__v":1,"createdAt":"2017-06-07T07:58:47.936Z","releaseDate":"2017-06-07T07:58:47.936Z","categories":["5937b2388e8d9b002f1df26f","5937b2388e8d9b002f1df270","5937b2388e8d9b002f1df271","5937b2388e8d9b002f1df272","5937b2388e8d9b002f1df273","5937b2388e8d9b002f1df274"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0.0"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-03T11:37:08.887Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":33,"body":"[block:html]\n{\n  \"html\": \"<div class=\\\"github-deeplinks\\\">\\n    <a href=\\\"https://github.com/TryGhost/Ghost/blob/master/core/server/helpers/get.js\\\"><i class=\\\"fa fa-github-alt fa-right\\\"></i>Source</a>\\n    <a href=\\\"https://github.com/TryGhost/Ghost/blob/master/core/test/unit/server_helpers/get_spec.js\\\" class=\\\"fa fa-check-square-o fa-right\\\">Tests</a>\\n</div>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Beta Feature\",\n  \"body\": \"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\\n\\nTo enable this feature, visit yourblog.com/ghost/settings/labs/ and tick the 'Public API' checkbox.\"\n}\n[/block]\nUsage: `{{#get \"posts\"}}{{/get}}`\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Type\",\n    \"h-1\": \"Parameters\",\n    \"h-2\": \"Attributes\",\n    \"0-0\": \"[Block](doc:helpers#section-block), [Ghost](doc:helpers#section-ghost), [Query](/docs/helpers#section-query)\",\n    \"0-1\": \"resource either:\\n* [posts](doc:post)\\n* [tags](doc:tags)\\n* [users](doc:author)\\n\\noptional:\\nblock parameters for collection name and pagination\\ncollection name - |collection pagination|\",\n    \"0-2\": \"Browse:\\n* [limit](doc:get#section--limit-)  (string)\\n* [page](doc:get#section--page-)  (string)\\n* [order](doc:get#section--order-)  (string)\\n* [include](doc:get#section--include-) (string)\\n* [fields](doc:get#section--fields-) (string)\\n* [filter](doc:get#section--filter-)  (string)\\n\\nRead:\\n* [resource field](doc:get#section--resource-field-) (id, slug, email)\\n* [include](doc:get#section--include-) (string)\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n## Description\n\n`{{#get}}` is a special block helper that makes a custom query to the [Ghost API](http://api.ghost.org) 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**](doc:context-overview).\n\nIn its most basic form it can perform a 'browse' query to create a block of data that represents a list of your [posts](doc:post), [authors](doc:author) (users) or [tags](doc:tags). That block of data can then be iterated over using the [`{{#foreach}}`](doc:foreach) helper.\n\nIt 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.\n\n**Please note**: This is a powerful tool, that has the potential to be overused and cause problems on a blog.\n\n### Simple Examples\n\nA basic request for posts, this will fetch 15 posts from the API including their related tags and author data.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#get \\\"posts\\\" include=\\\"tags,author\\\"}}\\n    {{#foreach posts}}\\n   \\t    {{title}} \\n    {{/foreach}}\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\nA basic request for a single post with id of 2, including its related tags and author data.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#get \\\"posts\\\" id=\\\"2\\\" include=\\\"tags,author\\\" as |post|}}\\n    {{#post}}\\n   \\t    {{title}} \\n    {{/post}}\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\nFetch all tags, and output them using the tags helper:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#get \\\"tags\\\" limit=\\\"all\\\"}}{{tags}}{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Usage\"\n}\n[/block]\nThe `{{#get}}` helper has many more options than most helpers, the following section walks through the various options and how they can be used.\n\n## Parameters\n\nThe first parameter passed in is the name of the resource that you want to query. This can be either `\"posts\"`, `\"tags\"` or `\"users\"` (authors).\n\n[posts](doc:post) - only published posts can be retrieved\n[tags](doc:tags) - currently all tags can be retrieved \n[users](doc:author) - only active users can be retrieved\n\nExample:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#get \\\"posts\\\"}}\\n    {{! Loop through our posts collection }}\\n    {{#foreach posts}}\\n   \\t    {{title}} \\n    {{/foreach}}\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n## Block Parameters\n\nAs 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.\n\n> Note: Block Params are entered between pipe symbols, which are vertical bars: `|`\n\nUsage: `as |featuredposts pagination|`\n\nThe `{{#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](doc:pagination) object.\n\nExample using block parameters:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#get \\\"posts\\\" as |articles pages|}}\\n    {{! Loop through our articles collection }}\\n    {{#foreach articles}}\\n   \\t    {{title}} \\n    {{/foreach}} \\n    {{! Use our pages (pagination) object }}\\n    {{pages.total}}\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\nIn the example above we are fetching **posts** which we will then refer to **as articles** in our loop and a [pagination](doc:pagination) object called **pages**. \n\n## Attributes\n\nThe 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](http://api.ghost.org/v0.1/docs/parameters). 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.\n\n### *limit* \n\nSpecify the size of your collection\nAllowed values: positive integer and 'all'\nDefault value: 15\n\nIt 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](doc:packagejson#section-recommended-property) file, this global value is available via the `:::at:::config` global as [email protected]_per_page`. \n\nExamples:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{! Fetch the 20 most recently published posts }}\\n{{#get \\\"posts\\\" limit=\\\"20\\\"}}{{/get}}\\n\\n{{! Fetch all published posts }}\\n{{#get \\\"posts\\\" limit=\\\"all\\\"}}{{/get}}\\n\\n{{! Use the posts_per_page setting}}\\n{{#get \\\"posts\\\" [email protected]_per_page}}{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n> Note: If no limit attribute is provided the **default** value of **15** will be used.\n\n### *page*\n\nThe resulting collection from the `{{#get}}` query may be paginated, therefore you can choose which page of that collection you want to fetch.\n\nExample:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{! Fetch the 4th page of results }}\\n\\n{{#get \\\"posts\\\" limit=\\\"5\\\" page=\\\"4\\\"}}{{/get}}\\n{{! In this case where limit = 5, we are accessing posts 16 - 20 }}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n### *order*\n\nSpecify how your data is ordered before being returned. You can choose any valid resource *field* in ascending (`asc`) or descending (`desc`) order.\n\nExamples:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{! Fetch the oldest 5 posts }}\\n{{#get \\\"posts\\\" limit=\\\"5\\\" order=\\\"published_at asc\\\"}}{{/get}}\\n\\n{{! Fetch the 5 most recently published posts }}\\n{{#get \\\"posts\\\" limit=\\\"5\\\" order=\\\"published_at desc\\\"}}{{/get}}\\n\\n{{! Fetch posts in alphabetical order of title ([0-9], A->Z) }}\\n{{#get \\\"posts\\\" limit=\\\"5\\\" order=\\\"title asc\\\"}}{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n### *include*\n\nWhen making an API request, the resulting response will only contain base data from the Resource itself.\n\nA Resource may have additional related data that can be included to expand your collection.\n\nBase Resource data:\n* [**Post**](doc:post)\n* [**Tag**](doc:tag)\n* [**User**](doc:user)\n\nThere can be multiple *includes* separated by a comma.\n\nThe *Post* resource by default has a tags array and an author_id. These can be expanded to include more information.\n\nInclude options for *Post*: \"author\" - expands author, \"tags\" - expands tags.\n\nThe *User* and *Tag* resources can be expanded to include the post count for each resource.\n\nInclude options for *User* and *Tag*: \"count.posts\"  \n\nNote: If you include count.posts you can use it to [**order**](doc:order) your collection.\n\nExamples:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{! Fetch posts with author }}\\n{{#get \\\"posts\\\" limit=\\\"5\\\" include=\\\"author\\\"}}\\n\\t\\t{{#foreach posts}}\\n    \\t\\t<span>Written by: {{author.name}}</span>\\n    {{/foreach}}\\n{{/get}}\\n\\n{{! Fetch posts with author and tags }}\\n{{#get \\\"posts\\\" limit=\\\"5\\\" include=\\\"author,tags\\\"}}\\n\\t\\t{{#foreach posts}}\\n    \\t\\t<p>Written by: {{author.name}}</p>\\n        <p>Tags: {{tags separator=\\\", \\\"}}</p>\\n    {{/foreach}}\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n### *fields*\n\nSpecify which resource **fields** to retrieve.\n\nYou can choose multiple **fields** with a comma separating the string.\n\nExample:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{! Fetch only the title and slug for all posts using block params }}\\n{{#get \\\"posts\\\" limit=\\\"all\\\" fields=\\\"title,slug\\\" as |articles|}}\\n\\t\\t{{#foreach articles}}\\n    \\t\\t<a href=\\\"{{slug}}\\\">{{title}}</a>\\n    {{/foreach}}\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n> Note: If you specify *fields* for *posts*, you cannot then use the [`{{url}}`](doc:url) helper.\n\nSummary of valid **fields**:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Resource\",\n    \"h-1\": \"Fields\",\n    \"0-0\": \"posts\",\n    \"1-0\": \"users\",\n    \"2-0\": \"tags\",\n    \"0-1\": \"id, uuid, title, slug, markdown, html, image, featured, page, status, language, created_at, created_by, updated_at, updated_by, published_at, published_by\",\n    \"1-1\": \"id, uuid, name, slug, image, cover, bio, website, location, status, language, last_login, created_at, created_by, updated_at, updated_by\",\n    \"2-1\": \"id, uuid, name, slug, description, image, created_at, created_by, updated_at, updated_by\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n### *filter*\n\nThis 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*:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#get \\\"posts\\\" limit=\\\"all\\\" filter=\\\"featured:true\\\"}}\\n\\t\\t{{#foreach posts}}\\n    \\t\\t<a href=\\\"{{slug}}\\\">{title}}</a>\\n    {{/foreach}}\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\nFiltering 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](http://api.ghost.org/docs/filter) in the API docs.\n\n#### Passing data to `filter`\n\nWhen 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#post}}\\n\\t<h3><a href=\\\"{{url}}\\\">{{title}}</a></h3>\\n  <section class=\\\"author-meta\\\">\\n  <p>Post by: {{author.name}}</a></p>\\n  {{#get \\\"posts\\\" filter=\\\"author:{{author}}+id:-{{id}}\\\" limit=\\\"3\\\"}}\\n    <p>More posts by this author:\\n      <ol>\\n\\t\\t\\t\\t{{#foreach posts}}\\n          <li><a href=\\\"{{url}}\\\">{{title}}</a></li>\\n        {{/foreach}}  \\n      </ol>\\n    </p>\\n    {{/get}}\\n{{/post}}\",\n      \"language\": \"handlebars\",\n      \"name\": \"post.hbs\"\n    }\n  ]\n}\n[/block]\nIn 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.\n\n**Note:**\n\n### Resource field\n\nEach 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. \n\nThe Browse request provides a resource array and a meta object that includes a [pagination](doc:pagination) object. The read request only returns a single resource object based on the field requested.\n\nSummary of resources and valid *read* fields:\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Resource\",\n    \"h-1\": \"Read fields\",\n    \"0-0\": \"posts\",\n    \"1-0\": \"users\",\n    \"2-0\": \"tags\",\n    \"0-1\": \"id, slug\",\n    \"1-1\": \"id, slug, email\",\n    \"2-1\": \"id, slug\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nExamples:\n\n1. Get the post which has the slug 'welcome-to-ghost'\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#get \\\"posts\\\" slug=\\\"welcome-to-ghost\\\" as |post|}}\\n  {{#post}}\\n  <h2><a href=\\\"{{slug}}\\\">{{title}}</a></h2>\\n  <div class=\\\"post-content\\\">\\n    {{content}}\\n  </div>\\n  {{/post}}\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n2. Get the user with email [email protected]'\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#get \\\"users\\\" email=\\\"[email protected]\\\"}}\\n  {{#user}}\\n  <section class=\\\"user-meta\\\">\\n    <h4><a href=\\\"/author/{{slug}}\\\">{{name}}</a></h4>\\n    <p>{{{bio}}}</p>\\n    <dl>\\n      <dt>website:</dt><dd>{{website}}</dd>\\n      <dt>location:</dt><dd>{{location}}</dd>\\n    </dl>  \\n  </section>\\n  {{/user}}\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples\"\n}\n[/block]\n### Fetch all *posts* for a specific user and order them alphabetically by post title.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#get \\\"posts\\\" limit=\\\"all\\\" order=\\\"title asc\\\" include=\\\"author\\\" filter=\\\"author:david\\\"}}\\n    <ul>\\n  \\t\\t{{#foreach posts}}\\n      \\t\\t<li><a href=\\\"{{slug}}\\\">{{title}}</a></li>\\n      {{/foreach}}\\n    </ul>\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n### Fetch all *Users* ordered by their creation date.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#get \\\"users\\\" limit=\\\"all\\\" order=\\\"created_at asc\\\"}}\\n    <ul>\\n  \\t\\t{{#foreach users}}\\n      \\t\\t<li><a href=\\\"/author/{{slug}}\\\">{{title}}</a></li>\\n      {{/foreach}}\\n    </ul>\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n### Make a *Tag* Cloud\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#get \\\"tags\\\" limit=\\\"all\\\" include=\\\"count.posts\\\" order=\\\"count.posts desc\\\"}}\\n    <ul>\\n  \\t\\t{{#foreach tags}}\\n      \\t\\t<li><a href=\\\"/tag/{{slug}}\\\">{{name}}</a></li>\\n      {{/foreach}}\\n    </ul>\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Limitations\"\n}\n[/block]\nThere are a few known limitations with the `{{#get}}` helper at the moment, after all, it is in beta :wink: \n\n- `{{#get}}` helpers may not work correctly when nested\n- Other [async helpers](http://themes.ghost.org/v0.7.2/docs/helpers#section-async) may not work when nested inside a get block (you may see an **aSyNcId_###** error on your page).\n- you cannot yet filter on count.posts\n- ordering alphabetically may be case sensitive depending on database\n- `{{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)](https://github.com/TryGhost/Ghost/wiki/Channels-101).","excerpt":"`{{get}}` Helper - Fetches a collection of data - posts, authors or tags","slug":"get","type":"basic","title":"get"}

get

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

[block:html] { "html": "<div class=\"github-deeplinks\">\n <a href=\"https://github.com/TryGhost/Ghost/blob/master/core/server/helpers/get.js\"><i class=\"fa fa-github-alt fa-right\"></i>Source</a>\n <a href=\"https://github.com/TryGhost/Ghost/blob/master/core/test/unit/server_helpers/get_spec.js\" class=\"fa fa-check-square-o fa-right\">Tests</a>\n</div>" } [/block] [block:callout] { "type": "warning", "title": "Beta Feature", "body": "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\n\nTo enable this feature, visit yourblog.com/ghost/settings/labs/ and tick the 'Public API' checkbox." } [/block] Usage: `{{#get "posts"}}{{/get}}` [block:parameters] { "data": { "h-0": "Type", "h-1": "Parameters", "h-2": "Attributes", "0-0": "[Block](doc:helpers#section-block), [Ghost](doc:helpers#section-ghost), [Query](/docs/helpers#section-query)", "0-1": "resource either:\n* [posts](doc:post)\n* [tags](doc:tags)\n* [users](doc:author)\n\noptional:\nblock parameters for collection name and pagination\ncollection name - |collection pagination|", "0-2": "Browse:\n* [limit](doc:get#section--limit-) (string)\n* [page](doc:get#section--page-) (string)\n* [order](doc:get#section--order-) (string)\n* [include](doc:get#section--include-) (string)\n* [fields](doc:get#section--fields-) (string)\n* [filter](doc:get#section--filter-) (string)\n\nRead:\n* [resource field](doc:get#section--resource-field-) (id, slug, email)\n* [include](doc:get#section--include-) (string)" }, "cols": 3, "rows": 1 } [/block] ## Description `{{#get}}` is a special block helper that makes a custom query to the [Ghost API](http://api.ghost.org) 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**](doc:context-overview). In its most basic form it can perform a 'browse' query to create a block of data that represents a list of your [posts](doc:post), [authors](doc:author) (users) or [tags](doc:tags). That block of data can then be iterated over using the [`{{#foreach}}`](doc: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. [block:code] { "codes": [ { "code": "{{#get \"posts\" include=\"tags,author\"}}\n {{#foreach posts}}\n \t {{title}} \n {{/foreach}}\n{{/get}}", "language": "handlebars" } ] } [/block] A basic request for a single post with id of 2, including its related tags and author data. [block:code] { "codes": [ { "code": "{{#get \"posts\" id=\"2\" include=\"tags,author\" as |post|}}\n {{#post}}\n \t {{title}} \n {{/post}}\n{{/get}}", "language": "handlebars" } ] } [/block] Fetch all tags, and output them using the tags helper: [block:code] { "codes": [ { "code": "{{#get \"tags\" limit=\"all\"}}{{tags}}{{/get}}", "language": "handlebars" } ] } [/block] [block:api-header] { "type": "basic", "title": "Usage" } [/block] 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](doc:post) - only published posts can be retrieved [tags](doc:tags) - currently all tags can be retrieved [users](doc:author) - only active users can be retrieved Example: [block:code] { "codes": [ { "code": "{{#get \"posts\"}}\n {{! Loop through our posts collection }}\n {{#foreach posts}}\n \t {{title}} \n {{/foreach}}\n{{/get}}", "language": "handlebars" } ] } [/block] ## 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](doc:pagination) object. Example using block parameters: [block:code] { "codes": [ { "code": "{{#get \"posts\" as |articles pages|}}\n {{! Loop through our articles collection }}\n {{#foreach articles}}\n \t {{title}} \n {{/foreach}} \n {{! Use our pages (pagination) object }}\n {{pages.total}}\n{{/get}}", "language": "handlebars" } ] } [/block] In the example above we are fetching **posts** which we will then refer to **as articles** in our loop and a [pagination](doc:pagination) object called **pages**. ## 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](http://api.ghost.org/v0.1/docs/parameters). 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](doc:packagejson#section-recommended-property) file, this global value is available via the [email protected]` global as [email protected]_per_page`. Examples: [block:code] { "codes": [ { "code": "{{! Fetch the 20 most recently published posts }}\n{{#get \"posts\" limit=\"20\"}}{{/get}}\n\n{{! Fetch all published posts }}\n{{#get \"posts\" limit=\"all\"}}{{/get}}\n\n{{! Use the posts_per_page setting}}\n{{#get \"posts\" [email protected]_per_page}}{{/get}}", "language": "handlebars" } ] } [/block] > 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: [block:code] { "codes": [ { "code": "{{! Fetch the 4th page of results }}\n\n{{#get \"posts\" limit=\"5\" page=\"4\"}}{{/get}}\n{{! In this case where limit = 5, we are accessing posts 16 - 20 }}", "language": "handlebars" } ] } [/block] ### *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: [block:code] { "codes": [ { "code": "{{! Fetch the oldest 5 posts }}\n{{#get \"posts\" limit=\"5\" order=\"published_at asc\"}}{{/get}}\n\n{{! Fetch the 5 most recently published posts }}\n{{#get \"posts\" limit=\"5\" order=\"published_at desc\"}}{{/get}}\n\n{{! Fetch posts in alphabetical order of title ([0-9], A->Z) }}\n{{#get \"posts\" limit=\"5\" order=\"title asc\"}}{{/get}}", "language": "handlebars" } ] } [/block] ### *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: * [**Post**](doc:post) * [**Tag**](doc:tag) * [**User**](doc:user) 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**](doc:order) your collection. Examples: [block:code] { "codes": [ { "code": "{{! Fetch posts with author }}\n{{#get \"posts\" limit=\"5\" include=\"author\"}}\n\t\t{{#foreach posts}}\n \t\t<span>Written by: {{author.name}}</span>\n {{/foreach}}\n{{/get}}\n\n{{! Fetch posts with author and tags }}\n{{#get \"posts\" limit=\"5\" include=\"author,tags\"}}\n\t\t{{#foreach posts}}\n \t\t<p>Written by: {{author.name}}</p>\n <p>Tags: {{tags separator=\", \"}}</p>\n {{/foreach}}\n{{/get}}", "language": "handlebars" } ] } [/block] ### *fields* Specify which resource **fields** to retrieve. You can choose multiple **fields** with a comma separating the string. Example: [block:code] { "codes": [ { "code": "{{! Fetch only the title and slug for all posts using block params }}\n{{#get \"posts\" limit=\"all\" fields=\"title,slug\" as |articles|}}\n\t\t{{#foreach articles}}\n \t\t<a href=\"{{slug}}\">{{title}}</a>\n {{/foreach}}\n{{/get}}", "language": "handlebars" } ] } [/block] > Note: If you specify *fields* for *posts*, you cannot then use the [`{{url}}`](doc:url) helper. Summary of valid **fields**: [block:parameters] { "data": { "h-0": "Resource", "h-1": "Fields", "0-0": "posts", "1-0": "users", "2-0": "tags", "0-1": "id, uuid, title, slug, markdown, html, image, featured, page, status, language, created_at, created_by, updated_at, updated_by, published_at, published_by", "1-1": "id, uuid, name, slug, image, cover, bio, website, location, status, language, last_login, created_at, created_by, updated_at, updated_by", "2-1": "id, uuid, name, slug, description, image, created_at, created_by, updated_at, updated_by" }, "cols": 2, "rows": 3 } [/block] ### *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*: [block:code] { "codes": [ { "code": "{{#get \"posts\" limit=\"all\" filter=\"featured:true\"}}\n\t\t{{#foreach posts}}\n \t\t<a href=\"{{slug}}\">{title}}</a>\n {{/foreach}}\n{{/get}}", "language": "handlebars" } ] } [/block] 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](http://api.ghost.org/docs/filter) 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: [block:code] { "codes": [ { "code": "{{#post}}\n\t<h3><a href=\"{{url}}\">{{title}}</a></h3>\n <section class=\"author-meta\">\n <p>Post by: {{author.name}}</a></p>\n {{#get \"posts\" filter=\"author:{{author}}+id:-{{id}}\" limit=\"3\"}}\n <p>More posts by this author:\n <ol>\n\t\t\t\t{{#foreach posts}}\n <li><a href=\"{{url}}\">{{title}}</a></li>\n {{/foreach}} \n </ol>\n </p>\n {{/get}}\n{{/post}}", "language": "handlebars", "name": "post.hbs" } ] } [/block] 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](doc:pagination) object. The read request only returns a single resource object based on the field requested. Summary of resources and valid *read* fields: [block:parameters] { "data": { "h-0": "Resource", "h-1": "Read fields", "0-0": "posts", "1-0": "users", "2-0": "tags", "0-1": "id, slug", "1-1": "id, slug, email", "2-1": "id, slug" }, "cols": 2, "rows": 3 } [/block] Examples: 1. Get the post which has the slug 'welcome-to-ghost' [block:code] { "codes": [ { "code": "{{#get \"posts\" slug=\"welcome-to-ghost\" as |post|}}\n {{#post}}\n <h2><a href=\"{{slug}}\">{{title}}</a></h2>\n <div class=\"post-content\">\n {{content}}\n </div>\n {{/post}}\n{{/get}}", "language": "handlebars" } ] } [/block] 2. Get the user with email [email protected]' [block:code] { "codes": [ { "code": "{{#get \"users\" email=\"[email protected]\"}}\n {{#user}}\n <section class=\"user-meta\">\n <h4><a href=\"/author/{{slug}}\">{{name}}</a></h4>\n <p>{{{bio}}}</p>\n <dl>\n <dt>website:</dt><dd>{{website}}</dd>\n <dt>location:</dt><dd>{{location}}</dd>\n </dl> \n </section>\n {{/user}}\n{{/get}}", "language": "handlebars" } ] } [/block] [block:api-header] { "type": "basic", "title": "Examples" } [/block] ### Fetch all *posts* for a specific user and order them alphabetically by post title. [block:code] { "codes": [ { "code": "{{#get \"posts\" limit=\"all\" order=\"title asc\" include=\"author\" filter=\"author:david\"}}\n <ul>\n \t\t{{#foreach posts}}\n \t\t<li><a href=\"{{slug}}\">{{title}}</a></li>\n {{/foreach}}\n </ul>\n{{/get}}", "language": "handlebars" } ] } [/block] ### Fetch all *Users* ordered by their creation date. [block:code] { "codes": [ { "code": "{{#get \"users\" limit=\"all\" order=\"created_at asc\"}}\n <ul>\n \t\t{{#foreach users}}\n \t\t<li><a href=\"/author/{{slug}}\">{{title}}</a></li>\n {{/foreach}}\n </ul>\n{{/get}}", "language": "handlebars" } ] } [/block] ### Make a *Tag* Cloud [block:code] { "codes": [ { "code": "{{#get \"tags\" limit=\"all\" include=\"count.posts\" order=\"count.posts desc\"}}\n <ul>\n \t\t{{#foreach tags}}\n \t\t<li><a href=\"/tag/{{slug}}\">{{name}}</a></li>\n {{/foreach}}\n </ul>\n{{/get}}", "language": "handlebars" } ] } [/block] [block:api-header] { "type": "basic", "title": "Limitations" } [/block] 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](http://themes.ghost.org/v0.7.2/docs/helpers#section-async) 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 - 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)](https://github.com/TryGhost/Ghost/wiki/Channels-101).