GHOST CMS - Functional Helpers功能助手
Functional Helpers
Functional helpers are used to work with data objects. Use this reference list to discover what each handlebars helper can do when building a custom Ghost theme.
Available functional helpers
is
Usage: {{#is "contexts"}}
Description
The {{#is}}
helper allows you to check the context of the current route, i.e. is this the home page, or a post, or a tag listing page. This is useful when using shared partials or layouts, to output slightly different context in different places on your theme.
Usage
The is
helper takes a single parameter of a comma-separated list containing the contexts to check for. Similar to the has
helper, the comma behaves as an or
statement, with and
being achieved by nesting helpers.
As with all block helpers, it is possible to use an else statement:
If you only want the reverse, or negation, you can use the ^
character:
Contexts
The following contexts are supported:
- home - true only on the home page
- index - true for the main post listing, including the home page
- post - true for any individual post page, where the post is not a static page
- page - true for any static page
- tag - true for any page of the tag list
- author - true for any page of the author list
- paged - true if this is page 2, page 3 of a list, but not on the first page
- private - true if this is the private page shown for password protected sites
foreach
Usage: {{#foreach data}}{{/foreach}}
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:
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.
{{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:
The limit
attribute
Passing {{#foreach}}
a limit
attribute, will tell it stop after a certain number of iterations.
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.
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:
{{@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>
{{@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.
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.
@even & @odd
The following example adds a class of even or odd, which could be used for zebra striping content:
Block Params
Block params allow you to name the individual item being operated on inside the loop, E.g.
Which is much the same as doing posts.forEach(function (my_post) {}
in JavaScript. Useful with advanced features like the {{get}}
helper.
has
Usage: {{#has tag="value1,value2" author="value"}}
{{#has slug=../slug}}
{{#has number="nth:3"}}
{{#has any="twitter, facebook"}}
{{#has all="twitter, facebook"}}
Description
{{#has}}
is like {{#if}}
but with the ability to do more than test a boolean. It allows theme developers to ask questions about the current context and provide more flexibility for creating different layouts.
Like all block helpers, {{#has}}
supports adding an {{else}}
block or using ^
instead of #
for negation - this means that the {{#has}}
and {{else}}
blocks are reversed if you use {{^has}}
and {{else}}
instead. In addition, it is possible to do {{else has ...}}
, to chain together multiple options like a switch statement.
Simple Example
The {{#has}}
helper can be combined with internal tags, to display different information for different types of posts. E.g. you can implement a link-style post by adding an internal tag of #link
and using the has helper to detect it:
Usage
The {{#has}}
helper supports four different types of "questions":
- Post has tag or author
- Context has slug or id
- Context has any or all properties set
- Foreach loop number or index
Questions are asked by providing attribute-value pairs, e.g. tag="tag-name"
. You can pass multiple attributes, and the {{#has}}
helper will always treat this as an OR
.
E.g. You can look for a post with a slug of "welcome" OR a tag of "getting started":
Post tag or author
Comma Separated List
Specifically when inside the context of a post, you can use the {{#has}}
helper to find out if the post has a particular tag or author. Both the tag
and author
attributes take a comma separated list. If you pass multiple values separated by a comma, these will be treated as an OR.
Tag and author matching is a lowercase match on the tag name or author name, which ignores special characters. This behaviour will be upgraded in future to try to match on either slug or name.
Counting
The author
and tag
attribute accepts a counting value. You can choose between:
count:[number]
count:>[number]
count:<[number]
This functionality can be helpful when designing a theme. You can change the behaviour if a post has only one author or more than 1.
Slug or id
If you're in the context of an object that has a slug (e.g. post, author, tag and navigation items) you can use the {{#has}}
helper to do an exact match. Similarly for all objects that have an ID.
You can either pass the {{#has}}
helper a string wrapped in quotes, or a path to a data value from else where in the template data. For example, the following code does an exact match on the string "welcome". If the post's slug is the same, the code inside the has helper will execute.
Alternatively, you can pass a handlebars path, which references a different piece of data to match against:
Any or all
The any
comparison will return true if any one of the properties is set in the current context, with support for paths and globals:
Similarly, the all
comparison will return true only when all of the properties are set:
Foreach loop number or index
When you're inside a {{#foreach}}
loop of any kind, you have access to two special data variables called @index
and @number
. @index
contains the 0-based index or count of the loop, and @number
contains a 1-based index. That is each time around the loop these values increase by 1, but @index
starts at 0, and @number
starts at 1.
The {{#has}}
helper will let you check which number/index of the iteration you are on using the 3 different styles of matching shown above. For example, if you have a list of posts and want to inject a special widget partial every 3rd post, you could do so using the nth:3
pattern:
Example Code
To determine if a post has a particular tag:
You can also supply a comma-separated list of tags, which is the equivalent of an OR query, asking if a post has any one of the given keywords:
You can do an AND query by nesting your {{#has}}
helpers:
if
Usage: {{#if featured}}{{/if}}
The {{#if}}
block helper comes built in with Handlebars.
Description
{{#if}}
allows for testing very simple conditionals, and executing different template blocks depending on the outcome.
The conditionals that can be tested are very simple, essentially only checking for 'truthiness'. The evaluation rules are explained in the section below.
Like all block helpers, {{#if}}
supports adding an {{else}}
block or using ^
instead of #
for negation - this means that the {{#if}}
and {{else}}
blocks are reversed if you use {{^if}}
and {{else}} instead. In addition, it is possible to do {{else if ...}}
, to chain together multiple options like a switch statement.
Evaluation rules
The if helper takes a single value, and evaluates whether it is true or false. Any passed in value which is equivalent to false
, 0
, undefined
, null
, ""
(an empty string) or []
(an empty array) is considered false, and any other value is considered true.
- Any boolean value, like the featured flag on a post, will evaluate to true or false as you expect.
- Any string value will be true, as long as it is not null or empty
- All numerical values, with the exception of
0
evaluate to true, 0 is the same as false - Any property which doesn't exist or is not set will always evaluate false
- Empty arrays or objects will be false
Example code
When in the scope of a post, featured
is a boolean flag. The following code example will evaluate to true only if the post is marked as featured.
You can also use this to test if any property is set. Strings, like image URLs will evaluate to true as long as one is present, and will be null (false) otherwise:
unless
Usage: {{#unless featured}}{{/unless}}
The {{#unless}}
block helper comes built in with Handlebars.
Description
{{#unless}}
is essentially the opposite of {{#if}}
. If you want to test a negative conditional only, i.e. if you only need the {{else}}
part of an {{#if}}
statement, then {{#unless}}
is what you need.
It works exactly the same as {{#if}}
and supports both {{else}}
and ^
negation if you want to get really confusing!
Unless also uses the exact same conditional evaluation rules as {{#if}}
.
Example code
Basic unless example, will execute the template between its start and end tags only if featured
evaluates to false.
If you want, you can also include an else block, although in the majority of cases, if you need an else, then using {{#if}}
is more readable:
// This is identical to if, but with the blocks reversed
get
Usage: {{#get "posts"}}{{/get}}
## 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 site.
Simple Examples
A basic request for posts, this will fetch 15 posts from the API including their related tags and authors.
A basic request for a single post with id of 2, including its related tags and author data, using a block parameter.
Fetch all tags, and output them using the tags helper:
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 "authors"
.
posts - only published posts can be retrieved
tags - any tag that has a post associated with it
authors - any author who has a post associated with it
Example:
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 piperefers to your returned data collection. The second entry refers to your pagination object.
Example using block parameters:
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.
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.
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:
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:
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:
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
- Tag
- Author
There can be multiple includes separated by a comma.
The Post resource by default has a tags and authors array. These can be expanded to include more information.
Include options for Post: "authors" - expands authors, "tags" - expands tags.
The Author and Tag resources can be expanded to include the post count for each resource.
Include options for Author and Tag: "count.posts"
Note: If you include count.posts you can use it to order your collection.
Examples:
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:
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:
In this example, we look for posts with the primary_author
(which is an alias of authors[0]
), 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.
In some cases, you'll need to wrap the data you pass in with quotes, for example if you pass a title rather than a slug, because it contains spaces, and also if you want to use dates.
Also be aware that, if you want to filter based on dates, you need to use the data attributes e.g.{{published_at}}
, not the {{date}}
helper, as helper functions do not get called inside of a filter.
Filtering by primary tag
The primary_tag
is a virtual post property and we support filtering by this property.
In this example we fetch 3 posts which have the same primary tag as the current post.
Filtering by primary author
The primary_author is a virtual post property and we support filtering by this property.
Limitations
There are a few known limitations with the {{#get}}
helper at the moment:
{{#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
- 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.
link
Usage: {{#link href="/about/"}}About{{/link}}
Description
{{#link}}
is a block helper that creates links with dynamic classes. In its basic form it will create an anchor element that wraps around any kind of string, HTML or handlebars constructed HTML.
With additional options it can have an active class
or target
behaviour, or onclick
JavaScript events. A href
attribute must be included or an error will be thrown.
Simple example
All attributes associated with the <a></a>
element can be used in {{#link}}
. Check out the MDN documentation on the anchor element for more information.
Variables
Handlebars variables can be used for attribute values as well as strings. Variables do not need be wrapped with quotations:
Simple variables example
Advanced variables example
Dynamic attributes
activeClass
By default the active class outputted by {{#link}}
will be nav-current
, this is consistent with our navigation helper. However it can be overwritten with the activeClass
attribute:
activeClass
Example
activeClass
can also be given false
value (activeClass=false
), which will output an empty string. Effectively turning off the behaviour.