Dmitry Pavlenko , Software Developer & Technical Lead
Grain theme is a project that provides a layout-based skeleton for creating static websites by only adjusting the configuration and adding a content. This post shows how to use the theme template in order to create a custom Grain theme — starting from defining content files and page layouts, and up to building user-friendly, page-formatting tools.
You should consider that to build custom website without using a ready-made theme, it is required to know Groovy or at least Java. Do not hesitate to give it a try if you are not familiar with Groovy yet.
Core Grain concepts
Before we proceed further, there are a few core concepts worth discussing to make it easier to understand how Grain works: resources, components and configuration.
Components. Grain ships with a variety of components that provide different resource processing methods. For instance, thanks to RST processor, it is possible to generate HTML content from .rst files, Pygments highlighter allows to apply syntax highlighting to website pages, and so on. Some of the components make it possible to heavily customize pages from a theme. Оne of them is the resource mapper which aims to handle resources in order to provide various pseudo-dynamic features, like pagination.
Configuration. Configuration defines which components process which resources, thus binding them in a certain way to provide a specific theme implementation. Grain comes with a default configuration, but it is also possible to change the settings on a per-project or system-wide basis.
Website theme template
Grain provides a handy template that can be used to start building a custom website or site theme from scratch. The template ships with all the necessary features and makes it a lot easier to utilize Grain components.
The theme template comes with:
- default configuration that is applicable for building websites
- raw content files that show common use cases for handling the site content
You can download the Grain Theme Template v0.4.0 from the Grain Themes page. It is not required to have Grain installed to start working with the template since the framework will be downloaded automatically as a dependency.
Grain framework is equally well applicable for implementing a static website and generating a project documentation. Although we will discuss only the basics of creating custom static sites, the use cases listed below can be effectively applied to any other Grain project, for instance to build a custom documentation generator.
Creating a custom page
Grain allows to specify custom commands through command-line extension component. The theme template utilizes this mechanism to provide a useful command for creating new pages:
- page - relative path to the new page, must start with '/'
- page title - the page title
To create the new Contacts page, navigate to the template directory and execute
create-page as follows:
Then, run preview mode
./grainw preview and open newly created http://localhost:4000/contacts/ page.
Grain determines the content markup type based on a file extension, besides HTML and XML, it is also possible to use Markdown, RST or any other markup currently supported by Grain components.
Page as a Grain resource
It is time to dive deeper into Grain and find out what features are available for page or resource processing
and what actually happens when you run
Navigate to the /content/contacts directory of your project and open the index.html file. As you can see,
this file does not contain any HTML markup, instead it has YAML content separated by
---. This content
is called a resource header. Resource header provides the static page configuration or the model. This configuration
can be accessed within the page content through the
page variable in embedded Groovy code.
As an example, let's add some contact information to the contacts page. At first, specify a map of contacts in YAML header:
Then, put the following code and markup right below the header:
Refresh the http://localhost:4000/contacts/ page to see the result.
There are a few more properties added by the create-page command to the page header: layout and published. To understand these variables, you should have a look at the layout and resource mapper components that are briefly described in the next sections.
Creating a custom page template
Page template is called a layout in Grain. Layouts provide generic page markup and are used to create new custom pages. By default, page layouts come as a part of a theme and are located in the /theme/layouts folder.
Layout can be applied to a page by specifying
layout property in the page header:
When a page applies a layout:
- the layout is rendered instead of the page
- page content is passed to the layout’s
- page header is merged with the layout header
Let's create the product template that will define markup for product marketing pages. Open the /theme/layouts directory and create the product.html file:
Note that it is not required to copy the content provided by the default template, you can just apply it
by specifying the
layout: default property in the product layout header. Also, it is worth mentioning that the
page model is available through the layout's
page map, since the page header is merged with the layout header.
Put the newly created template in use, navigate to the
/content/product folder and create the following index.html
file which provides the appropriate model and the content for the layout:
Finally, open the http://localhost:4000/product/ page to see the result.
Creating a custom website configuration
Grain project configuration can be defined in the
SiteConfig.groovy class which you can find in the root directory of
the theme template. The
SiteConfig.groovy is a ConfigSlurper file where settings can be specified using a dot notation
and scoped with a help of closures:
The website configuration is available in any project resource through the
site map. For instance, you can declare the
site_author property in the SiteConfig.groovy:
And then access the value of the property in the default layout to display a copyright notice:
It is also possible to manage the configuration of all the Grain components though the 'SiteConfig.groovy' when required. For more details, please, refer to the documentation.
Basics of resource processing in Grain
Grain provides a variety of resource customization components that allow to implement highly demanding features in a quick and timely manner. The most essential of them are the tag library and the resource mapper.
Tag library component allows to inject methods (also called as tags) into website resources. Tags are very helpful when it comes to content processing that can be done only within the website pages.
Any Grain tag is just a closure declared in a tag library class. Let's navigate to the /theme/sources/ directory and
ThemeTagLib.groovy file which is the default tag library of the theme template. Then, add the
tag by specifying the following closure:
The newly created
capitalize tag will be available from within all the site resources. For example, you can call
it from the product layout to convert the page header:
Resource mapper component is the last thing you should learn before start building websites with Grain. Resource mapper allows to customize page models, dynamically create new resources and change page URLs and markup types. You can find detailed description of the resource mapper component in the post Creating paginated archives in Grain.
Now, when you are familiar with the most vital Grain concepts and components, it is a time to start developing your own site and exploring advanced Grain features. Please, follow us on twitter to keep up on the latest news and updates and don’t forget to leave a feedback!