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    

subscribe

The subscribe context

Use: {{#is "subscribe"}}{{/is}} to detect this context.

Context
Url
Template
Data
Body Classes

subscribe

/subscribe/

subscribe.hbs

success (boolean)
error (object)
email (string)

.subscribe-template

Description

If a blog has the "subscribers" feature enabled in labs, then a theme gets access to several additional features for outputting a subscribe page and forms.

This page is an overview of the "context" properties, if you are looking for in depth docs on how to add support to your theme please see the subscribers feature page.

Note: if subscribers is not enabled, none of the features on this page will be accessible.

Routes

The subscribe context lives at the matching /subscribe/ route. This cannot be customised at present.

Templates

By default, the subscribe context will be rendered using the subscribe.hbs file which exists in /subscribers/lib/views/. By default, this page is styled to match the Ghost login screen.

To customise this page, theme developers can provide their own subscribe.hbs file as part of their theme. This will override the default.

Data

There are 3 pieces of data passed to the subscribe.hbs template:

  • success (boolean) - is true if this page is being rendered after a successful subscribe
  • error (object) - has a message property if something went wrong when the form was submitted
  • email (string) - the email address that was submitted

Helpers

The subscribe context makes use of a specialist helper called {{subscribe_form}}. Documentation for this helper can be found on the subscribers feature page.

Example Code

The subscribe.hbs template is intended to have a basic structure which displays a different result depending on whether the form has been successfully submitted or not.

The following example shows how to display the form if success is false, or otherwise output a success message:

{{#if success}}
  <header>
    <h1>Subscribed!</h1>
  </header>

  <p>
    You've successfully subscribed to <em>{{@blog.title}}</em>
    with the email address <em>{{email}}</em>.
  </p>
{{else}}
	<header>
    <h1>Subscribe to {{@blog.title}}</h1>
  </header>

  {{subscribe_form autofocus="true"}}
{{/if}}

The default setup assumes that you'll do any error handling you need within the form itself, so the outer page template can just handle the success / no success case.

However, if you want to add some additional template logic based on the error case, it is totally possible to use an 'if - else if - else' structure with handlebars, like this:

{{#if success}}
    <header>
        <h1>Success!</h1>
    </header>
{{else if error}}
    <header>
        <h1>Error!</h1>
    </header>

    {{subscribe_form autofocus="true"}}
{{else}}
    <header>
        <h1>Subscribe.../h1>
    </header>

    {{subscribe_form autofocus="true"}}
{{/if}}

If you're a big fan of minimising your templates, there's a trick you can use from the express-hbs library that Ghost uses called "content blocks". This allows you to define regions of your template, and define the content for those regions separately, although it requires that the content be defined first to work properly:

{{#if success}}
  {{#contentFor "title"}}Success!{{/contentFor}}
  {{#contentFor "body"}}<p>You've successfully subscribed :)</p>{{/contentFor}}
{{else if error}}
  {{#contentFor "title"}}Error!{{/contentFor}}
  {{#contentFor "body"}}{{subscribe_form autofocus="true"}}{{/contentFor}}
{{else}}
  {{#contentFor "title"}}Subscribe..{{/contentFor}}
  {{#contentFor "body"}}{{subscribe_form autofocus="true"}}{{/contentFor}}
{{/if}}

<section class="subscribe">
<header>
  <h1>{{{block "title"}}}</h1>
</header>

{{{block "body"}}}

</section>

If you're looking for more documentation on the {{subscribe_form}} helper, please see the the subscribers feature page.

subscribe

The subscribe context