ghost-theme-utils v1.7.0
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
This is the easiest way to explore the functionality provided by this package.
As part of the GhostStead default theme
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.