In order to get you ready to develop Ghost themes, there are some preliminary steps you'll need to take and some base information you'll need to be aware of. There are four languages we're going to be working with as we walk you through the creation of Ghost themes.
The two primary languages used will be HTML and CSS, as you would expect with any web design process, and we'll also use a small amount of JavaScript in order to enhance responsive functionality and browser compatibility.
HTML and JavaScript will be typed directly into your documents in the regular fashion; however, rather than manually creating raw CSS, we're going to use a CSS preprocessor called Stylus to make the development process much easier for you. So you won't be typing up your CSS in raw form, rather you'll be coding in the Stylus syntax, which will be explained in more detail later in this chapter.
The fourth language, although the term language is more loosely used in this case, is Handlebars.js, a templating system that acts as the connection between your theme files and Ghost's data.
The chapter assumes you already have a local installation of Ghost, having followed the steps in Chapter 1, The First Steps with Ghost, or Chapter 2, Manual Installation and Configuration of Ghost, and that you know how to access a terminal/command window on your computer in order to run commands.
It will also assume that you have a basic level of familiarity with coding for the Web; however, if you don't, you should still be able to follow along just fine by reading closely.
In this chapter, you'll learn about:
- Handlebars.js logic-less templating
- Creating CSS via Stylus
- Setting up a code editor to work with the languages you'll be using
- Setting up a theme development project that handles JavaScript minification and automatic Stylus compilation
The use of Handlebars.js is at the core of how Ghost themes operate. Handlebars is what is known as a "logic-less" templating language, which in a nutshell means its job is simply to display blog-specific content.
When creating themes for Ghost, it is important to understand that the platform keeps a very clear delineation between design, which is the area themes are responsible for, and functionality, which is the area Ghost itself and apps are responsible for. The logic-less nature of Handlebars helps to ensure that Ghost themes don't step outside the role for which they are intended, and that is controlling the presentation of a blog.
Unlike PHP-driven templating systems, Ghost's Handlebars-driven template files don't handle any manipulation of data, custom database queries, or any other processes driven by logic. In a Ghost theme, you can't write functions, create variables, or evaluate conditions outside of checking whether or not there is content available for display.
Handlebars gets its name from its distinctive use of double or triple curly brackets to denote template tags, for example:
{{pagination}}All Handlebars template tags are predefined by Ghost, or by apps, so wherever a template tag like the preceding one is placed in your theme, the corresponding predetermined content will be placed on that location. Ghost theme template files primarily comprise these Handlebars template tags in combination with HTML.
The preceding example template tag is the one Ghost has predefined to output pagination on the front page of your blog or your tag archives. So to have pagination appear in your theme, all you need to do is insert this template tag anywhere in the appropriate theme file. Note that we'll cover which template tags you'll need and how they should be used in which parts of your theme later.
There are a few key elements of how Handlebars.js works that you'll find important to be aware of when you get started coding up your theme's template files.
Template tags can have double curly braces like this:
{{date}}Or triple curly braces like this:
{{{body}}}The difference is that the first will escape any HTML content that is delivered, while the second won't. What this means is that if there is a string of HTML included in the content pulled in via a template tag, double curly braces will show you the HTML itself on the screen, while the triple curly braces will actually render the HTML into the page.
For that reason, pay close attention to using triple braces where it's indicated they should be, as per the previous example, where the {{{body}}} tag uses three braces. If you see a string of code appearing on your page for no apparent reason, change your double braces to triple braces at the point you see the unwanted display.
Sometimes individual pieces of content can be nested inside a parent content object. For example, in Ghost, all the information saved by navigating to the Settings | User of the admin panel is available under the author parent content object; however, to access the individual content items you must identify the child item you wish to display via a Handlebars path, expressed as a dot.
To show an image of the author, you would target the author object's image child by separating the two terms with a dot, as follows:
{{author.image}}Similarly, you could display the author's bio or website URL:
{{author.bio}}
{{author.website}}The {{#each}} helper is used to cycle through groups of multiple parent content objects, allowing you to directly access the child items of each. The name of the parent object is included in the opening tag and whatever is included between the each tags will be repeated for every parent object that is cycled through:
{{#each parentobject}}
{{childcontent}}
{{/each}}Built into Ghost is a custom version of this helper that is specific to the display of published blog posts. It is used in the same way as an {{#each}} helper, but is written as follows:
{{#foreach post}}
{{content}}
{{/foreach}}So for each parent item, that is, each published blog post, whatever is between the foreach tags will be repeated. We use this to display things such as the title, content, and tags for each available post.
The default function of the if helper is very simple, which is purely to check if there is any available content to be retrieved via a specific template tag.
For example, before outputting HTML to display an author's location, you can check to see if there is location information available to display:
{{#if author.location}}
<p itemscope itemtype="https://schema.org/PostalAddress"><span itemprop="addressLocality">{{author.location}}</span></p>
{{/if}}If you didn't use the preceding check and the user had not saved anything into the location field, an empty paragraph would be displayed. Using this technique, you can make sure that sections of HTML are only output in your theme if there is content to go along with them.
In Ghost themes, the if helper has an additional function, in that, it can be used to check on some extra private properties available for some content objects. For example, it can be used to check if a post is the first in the list like this:
{{#if @first}}
<div>First post</div>
{{/if}}We'll cover more on the specific properties that can be checked with the if helper later on.
The unless helper has the inverse functionality of the if helper. It checks to see if a certain piece of content is not available before proceeding. This can be used to create fallback content where appropriate.
For example, if the user has not uploaded an image of themselves, you might wish to fall back to a custom avatar image you have designed instead:
{{#unless author.image}}
<div id="my_custom_avatar_fallback"></div>
{{/unless}}The unless helper can be used by itself; however, you could alternatively create the same functionality described in the above example by using the else helper, as long as it's in conjunction with an if helper as follows:
{{#if author.image}}
<img src="{{author.image}}">
{{else}}
<div id="my_custom_avatar_fallback"></div>
{{/if}}In some cases, template tags can accept parameters that will affect how they output content. For example, in Ghost, a blog post's content can be displayed with the basic template tag:
{{content}}Alternatively, it can have the number of words to display specified:
{{content words="100"}}We'll give a thorough rundown on the template tag parameters available for you to work with in Ghost as part of Chapter 4, Beginning Ghost Theme Development.
If you would like to include comments in your theme, for example, to help users identify areas they might like to edit, use double curly braces with an exclamation mark immediately after the opening two braces:
{{! This is how comments are written with Handlebars}}The comment will appear in the template file, but not in the HTML that is output during rendering.
Note
For more information on handlebars and how they are used in Ghost, check out their documentation page at http://themes.ghost.org/.