Tiller 0.8.0 released!

Note : This page may contain outdated information and/or broken links; some of the formatting may be mangled due to the many different code-bases this site has been through in over 20 years; my opinions may have changed etc. etc.

Tiller has just seen its 0.8.0 release, and as you’d expect from a major version bump, it’s a big one. There’s some breaking changes if you write your own plugins - nothing too major, a quick search & replace should fix things for you. But, more importantly, there’s a major new feature which brings two big improvements.

I’ve added a “helper modules” feature, which lets you group together custom utility functions in Ruby that can be called from within templates. And I’ve included a built-in function called Tiller::render that lets you include and parse nested sub-templates from another template.

Sub-Templates

Now you can include other templates in your templates by using the built-in Tiller::render helper function. This may be useful if you have a large configuration file to generate: you can now split it up into separate files for each section and combine them together at run-time. Or, you may need to generate a lot of similar configuration blocks (for example, Nginx virtual hosts). You can now iterate over a list and render a single sub-template for each block.

For example, if you have a template called main.erb, you can include another template called sub.erb by calling this function inside main.erb:

This is the main.erb template. 
This will include the sub.erb template below this line:
<%= Tiller::render('sub.erb') -%>

You can nest sub-templates as deeply as you wish, so you can have sub-templates including another sub-template and so on.

Helper modules

The sub-template system builds on top of a new “helper module” feature. A helper module is intended to group together small blocks of code that you can include in your templates to perform mark-up or other utility functions. They aren’t intended to replace the existing Data- and Template-source plugins; if you need to get some values into your templates, or hook up to some external service, these are probably still the best way to go about it.

But you can see how if you had a more complicated transformation to do (e.g. convert markdown text into HTML) or needed to include some logic in a function, this would help clean up your templates, as well as keep a clean separation of code and configuration.

As an example, this is how you’d add a Lorem Ipsum generator for filling in place-holder text. We’ll simply wrap the excellent forgery gem, so first make sure you have it installed:

$ gem install forgery
Successfully installed forgery-0.6.0
Parsing documentation for forgery-0.6.0
Done installing documentation for forgery after 0 seconds
1 gem installed

I’ll also assume you are using the default directory for custom plugins; if you want to change this, use the -l/--lib-dir option to Tiller to point to somewhere else.

First, create a file named /usr/local/lib/tiller/helper/lorem_ipsum.rb , and put the following code inside:

require 'forgery'

module Tiller::LoremIpsum
  def self.words(num)
    Forgery(:lorem_ipsum).words(num)
  end
end

Note that I defined this inside a custom namespace so it doesn’t clash with anything else. You can then load this module by adding the following to the top-level of your common.yaml:

helpers: [ "lorem_ipsum" ]

Now, in your templates you can call this function like so:

This is some place-holder content : <%= Tiller::LoremIpsum.words(10) %>

When you run Tiller with the -v (verbose) flag, you’ll see Helper modules loaded ["lorem_ipsum"] amongst the output, and your template will contain the following text when generated :

This is some place-holder content : lorem ipsum dolor sit amet consectetuer adipiscing elit proin risus