Utility Helpers

Utility helpers are used to perform minor, optional tasks. Use this reference list to discover what each handlebars helper can do when building a custom Ghost theme.

Available utility helpers

asset

Usage: {{asset "asset-path"}}

Description

The {{asset}} helper exists to take the pain out of asset management. Firstly, it ensures that the relative path to an asset is always correct, regardless of how Ghost is installed. So if Ghost is installed in a subdirectory, the paths to the files are still correct, without having to use absolute URLs.

Secondly, it allows assets to be cached. All assets are served with a ?v=####### query string which currently changes when Ghost is restarted and ensures that assets can be cache busted when necessary.

Thirdly, it provides stability for theme developers so that as Ghost's asset handling and management evolves and matures, theme developers should not need to make further adjustments to their themes as long as they are using the asset helper.

Finally, it imposes a little bit of structure on themes by requiring an assets folder, meaning that Ghost knows where the assets are, and theme installing, switching live reloading will be easier in future.

Examples

To use the {{asset}} helper to output the path for an asset, simply provide it with the path for the asset you want to load, relative to the assets folder.

For example:

// Styles
<link rel="stylesheet" type="text/css" href="{{asset 'css/style.css'}}" /> // Scripts <script type="text/javascript" src="{{asset 'js/index.js'}}"></script> // Images <img src="{{asset 'images/my-image.jpg'}}" />

ghost_head/foot

Usage: {{ghost_head}} and {{ghost_foot}}

Description

These helpers output vital system information at the top and bottom of the document, and provide hooks to inject additional scripts and styles.

ghost_head

{{ghost_head}} – belongs just before the </head> tag in default.hbs, outputs the following:

Meta description
Structured data Shema.org microformats in JSON/LD - no need to clutter your theme markup!
Structured data tags for Facebook Open Graph and Twitter Cards.
RSS url paths to make your feeds easily discoverable by external readers.
Scripts to enable the Ghost API (if enabled in labs)
Canonical link to equivalent amp post (if enabled in apps)
Anything added in the Code Injection section globally, or at a page-level

ghost_foot

{{ghost_foot}} – belongs just before the </body> tag in default.hbs, outputs the following:

Anything added in the Code Injection section globally, or at a page-level

body_class

Usage: {{body_class}}

Description

{{body_class}} – outputs dynamic CSS classes intended for the <body> tag in your default.hbs or other layout file, and is useful for targeting specific pages (or contexts) with styles.

The {{body_class}} helper outputs different classes on different pages, depending on what context the page belongs to. For example the home page will get the class .home-template, but a single post page would get .post-template.

Ghost provides a series of both static and dynamic body_class classes:

Static classes

home-template – The class applied when the template is used for the home page
post-template – The class applied to all posts
page-template – The class applied to all pages
tag-template – The class applied to all tag index pages
author-template – The class applied to all author pages
private-template – The class applied to all page types when password protected access is activated

Dynamic classes

page-{slug} – A class of page- plus the page slug added to all pages
tag-{slug} – A class of tag- plus the tag page slug added to all tag index pages
author-{slug} – A class of author- plus the author page slug added to all author pages

Examples

default.hbs

<html>
    <head>...</head> <body class="{{body_class}}"> ... {{{body}}} ... </body> </html>

post_class

Usage: {{post_class}}

Description

{{post_class}} outputs classes intended for your post container, useful for targeting posts with styles.

The classes are as follows:

post - All posts automatically get a post class.
featured - All posts marked as featured get the featured class.
page - Any static page gets the page class.
tag-:slug - For each tag associated with the post, the post get a tag in the format tag-:slug.

For example:

A post which is not featured or a page, but has the tags photo and panoramic would get post tag-photo tag-panoramic as post classes.

A featured post with a tag of photo would get post tag-photo featured.

A featured page with a tag of photo and panoramic would get post tag-photo tag-panoramic featured page.

Setting a post as featured or as a page can be done from the post settings menu.

Example Code

<article class="{{post_class}}"> {{content}} </article>

reading_time

Usage: {{reading_time}}

Description

{{reading_time}} renders the estimated reading time for a post.

The helper counts the words in the post and calculates an average reading time of 275 words per minute. For the first image present, 12s is added, for the second 11s is added, for the third 10, and so on. From the tenth image onwards every image adds 3s.

By default the helper will render a text like this:

x min read for estimated reading time longer than one minute
1 min read for estimated reading time shorter than or equal to one minute

You can override the default text.

Example Code

{{#post}}
    {{reading_time}} {{/post}}

pagination

Usage: {{pagination}}

Description

{{pagination}} is a template driven helper which outputs HTML for 'newer posts' and 'older posts' links if they are available and also says which page you are on.

You can override the HTML output by the pagination helper by placing a file called pagination.hbs inside of content/themes/your-theme/partials. Details of the default template are below.

The data used to output the {{pagination}} helper is generated based on the post list that is being output (index, tag posts, author posts etc) and always exists at the top level of the data structure.

Pagination Attributes

page - the current page number
prev - the previous page number
next - the next page number
pages - the number of pages available
total - the number of posts available
limit - the number of posts per page

Default Template

The default template output by Ghost is shown below. You can override this by placing a file called pagination.hbs in the partials directory of your theme.

<nav class="pagination" role="navigation"> {{#if prev}} <a class="newer-posts" href="{{page_url prev}}">&larr; Newer Posts</a> {{/if}} <span class="page-number">Page {{page}} of {{pages}}</span> {{#if next}} <a class="older-posts" href="{{page_url next}}">Older Posts &rarr;</a> {{/if}} </nav>

Unique helpers within this context

{{page_url}} - accepts prev, next and $number to link to a particular page
{{page}} - outputs the current page number
{{pages}} - outputs the total number of pages

prev_post & next_post

Usage: {{#prev_post}}{{title}}{{/prev_post}} - {{#next_post}}{{title}}{{/next_post}}

Description

When in the scope of a post, you can call the next or previous post helper, which performs a query against the API to fetch the next or previous post in accordance with the chronological order of the site.

Inside of the opening and closing tags of the {{#next_post}}{{/next_post}} or {{#prev_post}}{{/prev-post}} helper, the normal helpers for outputting posts will work, but will output the details of the post that was fetched from the API, rather than the original post.

{{#post}}
	{{#prev_post}} <a href="{{url}}">{{title}}</a> {{/prev_post}} {{#next_post}} <a href="{{url}}">{{title}}</a> {{/next_post}} {{/post}}

You can also scope where to pull the previous and next posts from using the inparameter

{{#post}}
	{{#prev_post in="primary_tag"}} <a href="{{url}}">{{title}}</a> {{/prev_post}} {{#next_post in="primary_tag"}} <a href="{{url}}">{{title}}</a> {{/next_post}} {{/post}}

plural

Usage: {{plural value empty="" singular="" plural=""}}

Description

{{plural}} is a formatting helper for outputting strings which change depending on whether a number is singular or plural.

The most common use case for the plural helper is outputting information about how many posts there are in total in a collection. For example, themes have access to pagination.total on the homepage, a tag page or an author page. You can override the default text.

Examples

{{plural pagination.total empty='No posts' singular='% post' plural='% posts'}}

% is parsed by Ghost and will be replaced by the number of posts. This is a specific behaviour for the helper.

translate

Usage: {{t}}

Description

{{t}} is a helper to output text in your site language.

Ghost's front-end and themes are fully translatable by enabling a publication language in the setting in Ghost admin, and using the translate helper to wrap around any plain text in your theme.

Making a theme translatable

Follow these steps to make your theme fully translatable:

1. Create a `locales` folder and add language files

Create a folder called locales. If using a theme that is already translatable, this may exist already.

Inside the locales folder, add target language files for each translatable language used on your site. For example locales/en.json for English and locales/es.json for Spanish. A valid language code must be used.

2. Translate included sentences

Translate the sentences used in your theme inside your new language files.

For example, in locales/en.json:

{
    "Back": "Back", "Newer Posts": "Newer Posts", "Older Posts": "Older Posts", "Page {page} of {pages}": "Page {page} of {pages}", "Subscribe": "Subscribe", "Subscribe to {blogtitle}": "Subscribe to {blogtitle}", "Subscribed!": "Subscribed!", "with the email address": "with the email address", "Your email address": "Your email address", "You've successfully subscribed to": "You've successfully subscribed to", "A collection of posts": "A collection of posts", "A collection of 1 post": "A collection of 1 post", "A collection of % posts": "A collection of % posts", "Get the latest posts delivered right to your inbox": "Get the latest posts delivered right to your inbox", "Latest Posts": "Latest Posts", "<a href='{url}'>More posts</a> by {name}": "<a href='{url}'>More posts</a> by {name}", "No posts": "No posts", " (Page %)": " (Page %)", "Read More": "Read More", "Read <a href='{url}'>more posts</a> by this author": "Read <a href='{url}'>more posts</a> by this author", "See all % posts": "See all % posts", "Share this": "Share this", "Stay up to date! Get all the latest & greatest posts delivered straight to your inbox": "Stay up to date! Get all the latest & greatest posts delivered straight to your inbox", "This post was a collaboration between": "This post was a collaboration between", "[email protected]": "[email protected]", "1 post": "1 post", "% posts": "% posts", "1 min read": "1 min read", "% min read": "% min read" }

And edited to translate into Spanish for locales/es.json:

{
    "Back": "Volver", "Newer Posts": "Artículos Siguientes", "Older Posts": "Artículos Anteriores", "Page {page} of {pages}": "Página {page} de {pages}", "Subscribe": "Suscríbete", "Subscribe to {blogtitle}": "Suscríbete a {blogtitle}", "Subscribed!": "¡Suscrito!", "with the email address": "con el correo electrónico", "Your email address": "Tu correo electrónico", "You've successfully subscribed to": "Te has suscrito con éxito a", "A collection of posts": "Una colección de artículos", "A collection of 1 post": "Una colección de 1 artículo", "A collection of % posts": "Una colección de % artículos", "Get the latest posts delivered right to your inbox": "Recibe los últimos artículos directamente en tu buzón", "Latest Posts": "Últimos Artículos", "<a href='{url}'>More posts</a> by {name}": "<a href='{url}'>Más artículos</a> de {name}", "No posts": "No hay artículos", " (Page %)": " (Página %)", "Read More": "Lee Más", "Read <a href='{url}'>more posts</a> by this author": "Lee <a href='{url}'>más artículos</a> de este autor", "See all % posts": "Ver todos los % artículos", "Share this": "Comparte", "Stay up to date! Get all the latest & greatest posts delivered straight to your inbox": "¡Mantente al día! Recibe todos los últimos y mejores artículos directamente en tu buzón", "This post was a collaboration between": "Este artículo fue una colaboración entre", "[email protected]": "[email protected]", "1 post": "1 artículo", "% posts": "% artículos", "1 min read": "1 min de lectura", "% min read": "% min de lectura", "< 1 min read": "< 1 min de lectura" }

It is possible to use any translation key on the left, but readable English is advised in order to take advantage of the fallback option inside the {{t}} translation helper when no translation is available.

Dates, with month names, are automatically translated. You don't need to include them in the translation files.

Use HTML entities instead of characters, for example < instead of <.

3. Enable blog language

Verify that the .json translation file for your active theme is in place and then activate the language in the General settings of Ghost admin. Enter the correct language code into your settings menu and hit save.

4. Ensure templates exist

To ensure that your theme is fully translatable, two core templates must exist in your theme. Check the following templates exist:

pagination.hbs - exists in content/themes/mytheme/partials, copy the template

navigation.hbs - exists in content/themes/mytheme/partials, copy the template

5. Use the translation helper

Any plain text in your theme must be wrapped in the {{t}} translation helper, with {{t to the left of the text and }} to the right.

Look for any plain text in all of your theme's .hbs template files and ensure the translation helper is present.

6. Declare language in HTML

It's advisable to add the HTML lang attribute to the "<html>" tag at the start of the theme's default.hbs template, using Ghost's {{@site.lang}} helper: <html lang="{{@site.lang}}">. {{@site.lang}} will automatically be replaced on the site with the corresponding language locale tag set in Ghost admin.

7. Reactivate the theme

To make the new changes effective, run restart ghost.

Optional features

The translation helper can interact with many other handlebars expressions in order to implement more advanced translations within your theme.

Here are some of the most commonly used advanced translation features:

Placeholders

Placeholders are dynamic values that are replaced on runtime, and can be implemented using single braces. This is useful for translations if you need to insert dynamic data attributes to your translations.

For example, here is a placeholder in the theme translation file:

"Proudly published with {ghostlink}": "Publicado con {ghostlink}",

Which is defined in the theme template default.hbs using:

{{{t "Proudly published with {ghostlink}" ghostlink="<a href=\"https://ghost.org\">Ghost</a>"}}}

Placeholders with data attributes can also be used, for example:

{{t "Subscribe to {blogtitle}" [email protected]}}

Subexpressions

The concept of subexpressions allows you to invoke multiple helpers in one expression.

For example, a (t) subexpression (instead of normal {{t}} helper) can be used as a parameter inside another helper such as {{tags}}.

This can be used to translate the prefix or suffix attribute of the {{tags}} or {{authors}} helper.

Plural helper

{{plural}} is a formatting helper for outputting strings which change depending on whether a number is singular or plural.

This can be used in translations to output information such as number of posts:

"No posts": "No hay artículos",
"1 post": "1 artículo", "% posts": "% artículos",

In the theme template author.hbs, several (t) subexpressions instead of normal {{t}}helpers can be used as parameters inside

{{plural ../pagination.total empty=(t "No posts") singular=(t "1 post") plural=(t "% posts")}}

Reading time helper

The reading time helper can be used in translations to provide a reading time for your posts in the desired language.

For example, in es.json:

"1 min read": "1 min de lectura", "% min read": "% min de lectura", And in theme template post.hbs

And in the theme template post.hbs:

{{reading_time minute=(t "1 min read") minutes=(t "% min read")}}

Pagination

The {{meta_title}} helper accepts a page parameter that can be used in conjunction with translations. By using the follow it's possible to translate the word "Page" shown in the title of paginated pages:

<title>{{meta_title page=(t "Page %")}}</title>

encode

Usage: {{encode value}}

Description

{{encode}} is a simple output helper which will encode a given string so that it can be used in a URL.

The most obvious example of where this is useful is shown in Casper's post.hbs, for outputting a twitter share link:

<a class="icon-twitter" href="https://twitter.com/share?text={{encode title}}&url={{url absolute='true'}}" onclick="window.open(this.href, 'twitter-share', 'width=550,height=235');return false;"> <span class="hidden">Twitter</span> </a>

Without using the {{encode}} helper on the post's title, the spaces and other punctuation in the title will not be handled correctly.

log

Usage: {{log value}}

Description

When running Ghost in development mode, you can use the {{log}} helper to output debug messages to the server console. In particular you can get handlebars to output the details of objects or the current context

For example, to output the full 'context' that handlebars currently has access to:

{{log this}}

Or, to log each post in the loop:

{{#foreach posts}} {{log post}} {{/foreach}}

If you're developing a theme and running an install using Ghost-CLI, you must use NODE_ENV=development ghost run to make debug output visible in the console.

@labs

The @labs variable provides access to global data properties, which are available anywhere in your theme.

For each feature listed with a checkbox in the settings/labs/ section of a site, the @labs global will provide a boolean flag which tells the theme developer whether or not the feature is enabled.

As of Ghost 1.0.0, there are two features which can be detected:

{{@labs.publicAPI}} – true if the Public API feature is enabled (enabled by default)
{{@labs.subscribers}} – true if the Subscribers feature is enabled (disabled by default)

Examples

Test if subscribers is enabled before outputting HTML elements to surround a subscribe form, or before adding a subscribe button.

{{#if @labs.subscribers}} <div class="subscribe-form"> {{subscribe_form}} </div> {{/if}}

It is also possible to test if the publicAPI is enabled before using the get helper:

{{#if @labs.publicAPI}} <div class="latest-posts"> {{#get "posts" limit="3"}}...{{/get}} </div> {{/if}}

Note: when these features are moved out of beta in future, there will be a point at which these properties are deprecated. Therefore it is very important to keep your theme up-to-date.

concat

Usage: {{concat "a" "b" "c"}}

Description

The {{concat}} helper is designed to concatenate and link multiple things together.

The {{concat}} helper will take all of the items passed to it, treat them as strings, and concatenate them together without any spaces. There can be an unlimited amount of items passed to the helper.

Strings, variables and other helpers can be passed into the {{concat}} helper.

Simple examples

{{concat "hello world" "!" }} Outputs: hello world!

{{concat "my-class" slug }} Outputs: my-classmy-post

{{concat}} is designed for strings. If an object is passed it will output [object Object]in true JavaScript™️ fashion. To make it error proof, if {{concat}} is passed an empty variable, the output will be an empty string.

The separator attribute

By default, strings are concatenated together with nothing in between them. The separator="" attribute inserts the value provided between each string.

Separator example

{{concat "hello" "world" separator=" "}} Outputs: hello world

link_class

Usage: {{link_class for="/about/"}}

Description

The {{link_class}} helper adds dynamic classes depending on the currently viewed page. If the page slug (e.g. /about/) matches the value given to the for attribute the helper will output a nav-current class. A for value must be provided.

Simple example

<li class="nav {{link_class for="/about/"}}">About</li> When on the "/about/" URL it will output: <li class="nav nav-current">About</li> By default it will output: <li class="nav ">About</li>

`activeClass`

By default the active class outputted by {{link_class}} will be nav-current, this is consistent with our navigation helper. However it can be overwritten with the activeClass attribute:

<li class="nav {{link_class for="/about/" activeClass="active"}}">About</li> Will output: <li class="nav active">About</li>

activeClass can also be given false value (activeClass=false), which will output an empty string. Effectively turning off the behaviour.

`class`

Optionally {{link_class}} can have additional active classes. Using the class attribute will add whatever value has been provided when the link is the active URL, nav-current(the default active class value) will be added last:

<li class="nav {{link_class for="/about/" class="current-about"}}">About</li> Will output: <li class="nav current-about nav-current">About</li>

Parent URLs

Not only can {{link_class}} add active classes to current URLs, but it can also apply classes to parent URLs. If a user navigates to /tags/toast/ then {{link_class}} can provide an active class to /tags/ as well as /tags/toast/.

Example

<li class="nav {{link_class for="/tags/"}}">Tags</li> When on the "/tags/" URL it will output: <li class="nav nav-current">Tags</li> When on the "/tags/toast/" URL it will output: <li class="nav nav-parent">Tags</li>

GHOST CMS - Utility Helpers公用事业帮手

Utility Helpers

Available utility helpers

asset

Description

Examples

ghost_head/foot

Description

ghost_head

ghost_foot

body_class

Description

Static classes

Dynamic classes

Examples

post_class

Description

Example Code

reading_time

Description

Example Code

pagination

Description

Pagination Attributes

Default Template

Unique helpers within this context

prev_post & next_post

Description

plural

Description

Examples

translate

Description

Making a theme translatable

1. Create a locales folder and add language files

2. Translate included sentences

3. Enable blog language

4. Ensure templates exist

5. Use the translation helper

6. Declare language in HTML

7. Reactivate the theme

Optional features

Placeholders

Subexpressions

Plural helper

Reading time helper

Pagination

encode

Description

log

Description

@labs

Examples

concat

Description

Simple examples

The separator attribute

Separator example

link_class

Description

Simple example

activeClass

class

Parent URLs

Example

猜你喜欢

1. Create a `locales` folder and add language files

`activeClass`

`class`