Skip to content

Making a blog part 2 Making a theme

Jump to bottom
Filip Hnízdo edited this page May 20, 2016 · 12 revisions

Objective

After the last tutorial you should have an entity of type blog, have created a blog entry at path /my-first-blog and set permissions so people can see the blog. In this guide we're going to create a theme for our blog site.

A theme in Iris is a list of templates and static files such as images, stylesheet files and client side JavaScript files.

We're going to call our theme mytheme but you can call it whatever you want, just swap out mytheme for your theme's name in this tutorial.

The theme directory and the .iris.theme file

Navigate to your site's directory (for example /mysite/) and create a new folder called themes if there isn't already one there. Inside the themes folder create a folder called mytheme and inside that create a file called mytheme.iris.theme. This is a JSON file that will hold configuration information about your theme.

In mytheme.iris.theme write the following:

{
  "name": "My theme",
  "regions": ["header", "sidebar", "footer"]
}

Enabling the theme

This theme won't do much at the moment but let's enable it to get it working. Head over to the themes tab in the admin toolbar and enable My theme in the list. Only one theme can be enabled at a time.

Adding templates to your theme

Iris reads HTML templates which can contain special embed and template codes using its own template language found in [[[ ]]] embeds and Handlebars. This guide will not cover the full workings of Handlebars or the template system. If you want more information read the theme and template system guide.

Creating a template folder and our first templates

Add a folder called templates into your theme folder. This can have as many subfolders as you like and will contain all your theme's templates.

How template naming works

Iris templates are HTML files named using a list of double underscore __ separated names. When Iris is asked to look up a template it is generally passed two sets of parameters, one for the wrapper template and one for the inner content template.

Making a wrapper template

Let's start with wrapper template.

When asked to look for a wrapper template for an entity the Iris system is passed a list of words to look for in the file name. This will look something like ["html", "blog", "1"]. html is the generic wrapper template, blog is the entity type and 1 is the unique entity ID. When passed this information the system looks for the following templates in core Iris files, custom modules and then finally your enabled theme (allowing the theme to overwrite any template). Here's what files it looks for in those directories.

  • First it looks to see if there is a template file named html__blog__1.html, the most specific file.
  • If it can't find that it looks for a template wrapper file for all blog entries html__blog.html.
  • If it can't find that it'll fall back to look for html.html the general top level wrapper.

We probably only need one wrapper for our site so make a file in the templates directory called html.html. This should be the outer HTML of the page with a special [[[MAINCONTENT]]] variable inside the template which is where the inner template content will go.

Here's an example. Don't worry about understanding the {{current.title}} for now, we'll get on to that soon. [[[tags headTags]]] will automatically insert any JavaScript, meta or CSS tags provided by Iris modules.

<!doctype HTML>
<html>
<head>
<title>My blog site - {{current.title}}</title>
[[[tags headTags]]]
</head>
<body>
[[[MAINCONTENT]]]
</body>

</html>

Making a template for your blog entity type

How you have a wrapper template you'll need something to put inside it (this will be slotted into the [[[MAINCONTENT]]] variable in the wrapper.

Template lookup for inner templates works the same as the wrapper ones. The lookup words it gets passed are the entity type and the entity ID. So it'll look for blog_1.html followed by blog.html.

We don't want to create a new template for every blog so create a template file called blog.html and in it put the following:

<h1>{{current.title}}</h1>
{{{current.body}}}

The current Handlebars variable

The current Handlebars variable contains all the fields of the current entity you are viewing (if you're viewing an entity through its path). {{current.title}} gives you the title field you created earlier for example. {{{current.body}}} is wrapped in three, rather than two, sets of Handlebars curly brackets because it contains HTML. Refer to the Handlebars documentation for more information about this.

Adding stylesheets and other static client side files

If you head over to /my-first-blog it should have now be using your templates. Let's add a stylesheet to make it look a bit nicer.

Back in your theme folder, create a static directory and in it put a CSS stylesheet for your blog. Feel free to add CSS classes to any of the elements in the template to make styling easier. All files in this static directory will be accessible through the path /themes/themeName/... so a file called base.css in the static directory could be found at /themes/mytheme/base.css.

In your wrapper template put in something like:

  <link rel="stylesheet" href="/themes/{{iris_theme}}/base.css">

to reference this file. Note the {{iris_theme}} helper variable. This isn't needed as it simply substitutes out to your theme name (mytheme in this case) but it could be useful if you were using the same template for multiple themes.

You now have a basic pair of templates you can use for your blog site.

System and API

Clone this wiki locally