ghost-theme-utils

Easily add Ghost functionality to custom themes.

See the blog article Everything you need to know about subscription forms in Ghost for a detailed explanation.

What's included

• Base functional styles and javascript for subscribe forms.
• Message overlays e.g. for 'Thank you' pages after contact form submission.
• Generic Koenig styles - inclusion of _koenig.scss passes gscan.

Styles include the source SCSS files in addition to generated CSS.

Demo

You can see this package in action in the following ways.

Single page demo with simulated Ghost

• https://getmindspun.github.io/ghost-theme-utils/

This is the easiest way to explore the functionality provided by this package.

As part of the GhostStead default theme

• https://demo.ghoststead.net/

Usage

From the CDN (recommended)

<link href="https://cdn.jsdelivr.net/npm/ghost-theme-utils@latest/dist/css/style.min.css" rel="stylesheet">

<script src="https://cdn.jsdelivr.net/npm/ghost-theme-utils@latest/dist/js/ghost-theme-utils.min.js" async
        defer></script>

The packaged version of the CSS also contains the CSS from bootstrap-avatar. Usage of the above CDN does NOT require either Bootstrap or jQuery.

From source

The SCSS sources files may be included in a custom build as usual:

@import "node_modules/ghost-theme-utils/scss/subscribe"

Or you can use the standalone files from the dist/ directory.

Technically you may add these file only on specific pages, but generally they are included in default.hbs

Subscription

Here's how to get started using the subscription support in your theme.

Add HTML messages

You need to add HTML to the theme to show the message both on email confirmation failure and error:

<div class="position-fixed top-0 p-4 w-100 text-center text-white bg-success subscribe-notification subscribe-success-message"
     data-autohide="false">
    <a class="btn-close btn-close-white float-end subscribe-close-button" href="javascript:"></a>
    You've successfully subscribed to {{@site.title}}!
</div>
<div class="position-fixed top-0 p-4 w-100 text-center text-white bg-danger subscribe-notification subscribe-failure-message">
    <a class="btn-close btn-close-white float-end subscribe-close-button" href="javascript:"></a>
    Could not sign up! Invalid sign up link.
</div>

These messages use Bootstrap classes for styling, but that isn't required.

Test

During development, the easiest way to test is to navigate to the following URLs on your site:

Success : /?action=subscribe&success=true

Failure : /?action=subscribe&success=false

If all is working, you should see the corresponding message.

Of course, one deployed, test using the real subscription mechanism in Ghost.

Forms

Here's how to integrate a contact form into your theme. Contact forms are the most common usage, but this methodology works with any type of form you want to use.

Create the form

<div class="form">
    <div class="form-group">
        <label for="contact-name">Name</label>
        <input id="contact-name" type="text" name="name" class="form-control">
    </div>
    <div class="form-group">
        <label for="contact-email">Email</label>
        <input id="contact-email" type="email" name="email" class="form-control">
    </div>
    <div class="form-group">
        <label for="contact-message">Message</label>
        <textarea class="form-control" id="contact-message" name="message" rows="6"></textarea>
    </div>
    <input name="location" type="hidden" value="{{@site.url}}/#thank-you">
    <input name="api_key" type="hidden" value="1234567890abcdefghijklmn">
    <button class="btn btn-primary w-100" type="submit">Write to us</button>
</div>

This example is the contact from https://www.mindspun.com/contact/ and uses the Mindspun form handler, but any form service will do. The important thing is to redirect the user to the anchor #thank-you after form submission. In this example, the user would be redirected to https://www.mindspun.com/contact/#thank-you.

Add the HTML message

After the form is submitted, a confirmation message is shown as an overlay. The first step is to add the HTML for the message to the page where you redirect the user. Don't include the HTML in the page containing the form (unless they are the same page). For example, if your form lives at /contact/ and you return the user to your home page at / after form submission, then this HTML must be included in the home page.

<div id="thank-you"
     class="bg-white d-flex flex-column justify-content-center align-items-center position-fixed top-0 bottom-0 start-0 end-0 overlay">
    <a class="btn-close p-4 position-fixed top-0 end-0 subscribe-close-button"
       href="javascript:window.location.href=/^[^?#]+/.exec(window.location.href)[0]"></a>
    <p class="display-1">Thank you</p>
</div>

The small amount of Javascript in the link simply removes the anchor tag from the URL - in this case #thank-you. For example if the page URL is /#thank-you which causes the overlay to be shown, then clicking the close button will send the user back /.

Test

You can test style of the 'thank-you' page by navigating to anchor directly. From the above example, click on https://www.mindspun.com/contact/#thank-you and you'll see the contact form 'thank you' messages without actually submitting the form.

Development

npm run dev

---

This repository is maintained by Mindspun.