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    

Subscribers

Theme tools for collecting emails from your blog

Beta Feature

The subscribers feature is currently a Beta feature and is subject to heavy change over the coming months. We'll be trying not to break things, but be aware you may need to make theme updates to keep the feature working fully.

To enable this feature, visit yourblog.com/ghost/settings/labs/ and tick the 'Subscribers' checkbox.

Documentation in progress ✨

When a user enables the "subscribers" feature in labs, several new features are activated:

  • The route /subscribe/ will now render subscribe.hbs (provides there is not already a page at that route)
  • A new {{subscribe_form}} helper is registered for use within the theme
  • The API gets a new /subscribers/ endpoint

It is possible to detect whether or not this feature has been enabled from within a theme, by using the new {{@labs}} helper, please see @labs.

The subscribe page rendered at /subscribe/ will appear using the default template, regardless of whether a theme is updated. However, in order to get the subscribe form to appear on a post, theme changes will be needed.

It is highly recommended that themes be updated to support the subscribe form on the post page, as Ghost will record which post a subscriber came from, and will be able to show stats in a later version.

The subscribe page

The subscribe page is intended as a new landing page for your blog, where users can go to subscribe. The page is also used to display error and success states for the subscribe form. Currently the subscribe feature is designed to be used with a simple oldschool form posting mechanism. We'll be introducing tools for making the form work nicely with Ajax in a future release.

Conditionally linking to the subscribe page, if it's available can be achieve like this:

{{#if @labs.subscribers}}
  <a class="subscribe-button" href="{{@blog.url}}/subscribe/">Subscribe</a>
{{/if}}

The subscribe form helper

Usage: {{subscribe_form}}

Type
Parameters
Attributes

n/a

  • form_class (string)
  • input_class (string)
  • button_class (string)
  • placeholder (string)
  • autofocus (boolean)

Description

The {{subscribe_form}} helper wraps up all of the internals of the form used for submitting email addresses to subscribe. It contains a lot of hidden functionality, so it's not recommended to override the HTML for the form unless you really need to, as it may mean you miss out if we add extra behaviour in future!

Under the hood, {{subscribe_form}} is a template-driven helper just like navigation and pagination, meaning that the HTML can be overridden by providing a correctly named partial.

Attributes

The {{subscribe_form}} will accept values for a number of attributes. The first few are used for adding classes to the form, to make it easier to style:

  • form_class - a class, or space-separated list of classes to apply to the form element
  • input_class - a class, or space-separated list of classes to apply to the email input element
  • button_class - a class, or space-separated list of classes to apply to the submit button

The last two are additional attributes that get passed down to the email input element:

  • placeholder - a string to display as the placeholder
  • autofocus - a boolean of whether the input should be autofocused - we recommend passing true here in the subscribe.hbs template, but not anywhere else in your theme.

Example Code

Here's how the default subscribe.hbs page uses the helper (it uses all of the options):

{{subscribe_form
  form_class="gh-signin"
  input_class="gh-input"
  button_class="btn btn-blue btn-block"
  placeholder="Your email address"
  autofocus="true"
}}

Note that all the attributes should be wrapped in quotes, even the boolean!

Here's how the default theme Casper includes the form at the bottom of the post.hbs template:

 {{!-- Email subscribe form at the bottom of the page --}}
 {{#if @labs.subscribers}}
   <section class="gh-subscribe">
     <h3 class="gh-subscribe-title">Subscribe to {{@blog.title}}</h3>
     <p>Get the latest posts delivered right to your inbox.</p>
     {{subscribe_form placeholder="Your email address"}}
     <span class="gh-subscribe-rss">or subscribe <a href="http://cloud.feedly.com/#subscription/feed/{{@blog.url}}/rss/">via RSS</a> with Feedly!</span>
   </section>
 {{/if}}

Note that this form does not pass autofocus="true" as this would cause the page to scroll down to the form.

Documentation in progress ✨

Default template

The default template for the {{subscribe_form}} helper, is shown below. This can be overridden by including a file called subscribe_form.hbs in your partials/ directory.

If you're overriding this form, please be very careful! It's easy to miss something and break functionality, and you'll also need to check back regularly to make sure we haven't updated any of the functionality.

<form method="post" action="{{action}}" class="{{form_class}}">
    {{! This is required for the form to work correctly }}
    {{hidden}}

    <div class="form-group{{#if error}} error{{/if}}">
        {{input_email class=input_class placeholder=placeholder value=email autofocus=autofocus}}
    </div>
    <button class="{{button_class}}" type="submit">Subscribe</button>
    {{! This is used to get extra info about where this subscriber came from }}
    {{script}}
</form>

{{#if error}}
    <p class="main-error">{{{error.message}}}</p>
{{/if}}

The subscribe_form.hbs template is passed a set of attributes which are all required:

  • action - the action for the form, e.g. where it needs to send its post data
  • hidden - a set of hidden fields which are needed for the form to behave properly
  • script - a small piece of JavaScript used for setting referrer information, so that Ghost can figure out where subscribers came from.

In order to make the form work, it MUST also include the line to output the email field:

{{input_email class=input_class placeholder=placeholder value=email autofocus=autofocus}}

This template also gets provided the {{error}}, {{success}} and {{email}} fields provided to the subscribe page after the form is submitted.

Documentation in progress ✨

Subscribers

Theme tools for collecting emails from your blog