Vellum

Index > Templates: developer documentation

If you're happy with the current templates, then you don't really need to look at this documentation. Most people like to customise them a little at least, though, so this document describes how to do it.

The first thing you should do is go and look at the templates that come with Vellum. Go on, do that now. They're in the templates directory under your vellum directory. I'll wait here until you've done it.

OK, looking at that, you'll have had one of two reactions:

Stone the crows, that's a load of complex rubbish! How am I meant to customise that?
Wow! It's all real Python! I feel the power at my fingertips!

If your reaction was the first, then Vellum might not be for you. There are many, many blogging systems out there with simpler templates, and you should seriously consider one of them. Vellum templates are complicated, no two ways about it. If you've not been scared off at this point, then read on for what it all means.

Python

Vellum templates are Python embedded in HTML, in a Microsoft ASP sort of a way. This is not the place to teach you Python. If you're unsure of the language, then you'll find lots of information at the Python language website, and an excellent tutorial at Dive Into Python.

How to embed

You embed a Python statement between <% and %> markers. That statement will be processed at that point when the template is rebuilt. Note that you can add HTML in the middle of loops and so on, so to print a list of numbers, you might do:

<h1>My list of numbers</h1>
<% for num in range(5): %>
  The number is: <strong><% print num %><br>
<% end %>

You can also use <%=expr%> as a shorthand for <% print expr %>, where expr could be a variable or an expression; anything that would work with the print statement.

The end statement

If you know Python, then you might have noticed something odd about those templates: the word end appears all over the place. This is because, as you already know, Python does blocking by indentation: you indent the contents of a loop and then stop indenting when you reach the end of the loop code. This is exceedingly awkward when your Python is embedded in HTML, because HTML is traditionally indented for readability. So, as a compromise, Vellum insists that you terminate loops with an end statement, and indentation is not required. Loops begin with a line that ends with a colon, and they end with a line with end alone on it. You can still indent for readability, though. So the following Python code:

for i in range(5):
    for j in range(i,0,-1):
        print (i,j)

becomes

for i in range(5):
    for j in range(i,0,-1):
        print (i,j)
    end
end

in a Vellum template.

Variables you get

Each Vellum template gets a few variables in its namespace which you don't have to gather yourself.

entries — a list of all entries that should be displayed in this template
blog — the blog containing those entries
entry — for individual templates (i.e., those which display only one entry), this is that entry
time — the Python time module (so you don't have to import it yourself)

The blog variable is actually a vellum.Blog object, so you can use any of that object's methods. Similarly, entries is a list of vellum.Entry objects.