Firedrop2: The Python Blog Client

Templating with Firedrop2

The Power of embedded code

Note

For a simpler introduction to templating with Firedrop2, read the Introduction to Templates.

Templating
Embedded Code
The Namespace
A Word About Macros
Footnotes

Templating

Firedrop2 works by inserting your blog entries into the HTML templates that you provide. This means that you have complete control over the appearance of your blog. In the course of creating your blog (with front page, category archives, and the archives by date) Firedrop2 generates several (probably many) pages.

To do this it uses two or three different template files, and all are kept in the blog directory.

entry_template.html - this is used to make each individual entry, several of these are likely to be put together to within each page.
page_template.html - this is used as the frame for the pages.
indexpage_template.html - this is used, as the name implies, for the index page in Article Collections and Item Lists; it's not used by Weblogs.

These templates are mainly HTML, with a few special values that do the magic of inserting your entry, its title, the categories, and so on. In order to make the best of your blog, you need to know what these values are - and what properties they have.

Embedded Code

Firedrop2 templates are rendered by a module called embedded_code. It is aptly named, because it allows you to embed chunks of Python code into your templates. When your pages are generated, these chunks are executed. This means that if you are a Python programmer the templating system is very straightforward.

It is so easy though, that with a bit of knowledge even a non-programmer should be able to use it. You can get a long way with copy and paste and a few guesses. It's a good idea to make copies of your templates before you start, but if you really foul things up, it's good to know that there are spare copies of all of the templates in the themes folder, inside the default subfolder.

There are two different ways of using the magic values. They both involve inserting values between tags - either <% .... %> or <# ... #>``.

The simplest is to insert a single name between template tags - <% name %> [1]. This is evaluated and the value inserted into the page.

The second way allows you to execute blocks of code. Whole chunks of code can be inserted between <# ... #> tags. Anything that is printed [2] will be put into the page.

The code must be valid Python, which includes obeying Python's rules about indentation. Here's a quick example :

<table border="1" width="150" summary="Links to the archives">
    <tbody>
        <tr><th>Weblog Category Archives</th></tr>
        <tr><td>
            <a href="all_by_date<% page_ext %>">All By Date</a>
        </td></tr>
        <tr><td>
            <a href="all_by_category<% page_ext %>">All By Category</a>
        </td></tr>

        <#

        # this line starts with a '#'
        # which makes it a comment

        # this displays the links to the different categories
        import urllib
        categories = options.get('categories', [])
        # we use ``.get`` just in case no entries are set
        categories.sort()

        row = '<tr><td><a href="%s">%s</a></td></tr>'
        for category in categories:
            pagename = urllib.quote("arch_%s<% page_ext %>" % (category,))
            print row % (pagename, category)
            # it's what is printed here
            # that ends up in the page

        #>

        <tr>
            <td>&nbsp;</td>
        </tr>
    </tbody>
</table>

In case you can't work it out, this chunk of code uses urllib.quote to properly escape the links to the category archives. It then inserts the link to each category in a table row (row). The code is surrounded by the HTML for the table.

embedded_code will automatically remove any (uniform) excess indentation - this means the whole chunk of code can be indented to fit in with your page structure.

The Namespace

The code chunks are all executed inside a namespace. This determines what variables (names) are available to you to use. So the most important thing is to know what names are available to you to use. These are slightly different in the entry template.

The Entry Template

These are the most significant objects available to you in your entry template :

entry
This is the entry object, which represents the current entry that is being rendered. It has several useful properties that we might want to use.
- entry.get_id()
  
  This is a function [3] that returns the id reference of the current entry. This is useful if we want a unique reference for this entry (e.g. in an anchor point for this entry, to link to).
- entry.title
  
  This is the title of this entry.
- entry.attributes
  
  This is a dictionary [4] of values about the entry. These are the values at the top of each entry. They include entry.attributes['insert_date'], entry.attributes['categories'], and entry.attributes['modified_date']. The categories item, will be a list of categories that entry belongs to.
entry_body

This is the body of the entry - the entry itself.
permalink and abs_permalink

These are both functions. If you give it an entry id then they return a link to the current entry. abs_permalink returns an absolute link, permalink a relative link.

You use it with something like <% permalink(entry.get_id()) %>.
options

This is a dictionary of options for the site. This is the contents of your build.ini file for this site. You can access any of the values in it, but the only one I use in entry_template.html is options['author'].
doc

This object represents the entry as it is being built. For those of you who know what this means, it is a StringIO.StringIO() instance. You probably won't ever need to know this .
stdout

This is the real sys.stdout object. It might be useful if you want to print a traceback to stdout from your template. If you haven't got a clue what I'm on about, then don't worry about it .
page_ext

This is the page extension used by your html pages. Normally it would be .html, but if you use server-side includes in your web server, you might prefer .shtml. This option is set in your build.ini file; if it is missing, Firedop2 will use .html as a default.

Example Entry Template

So you can put it in context, this is my entry_template.html. It illustrates several of the values above :

<div class="bloganchor">
<a  title="Permanent link to this post" id="e<% entry.get_id() %>"
    name="e<% entry.get_id() %>"
    href="<% permalink(entry.get_id()) %>"
        >#<% entry.get_id() %></a>
</div>

<h2><% entry.title %></h2>

<% entry_body %>

<p class="entryfoot">
    Posted by <strong><% options['author'] %></strong> on
    <% entry.attributes['insert_date'] %>.

    <#
    import urllib
    if entry.attributes.get('categories',[]):
        print '<br />\nCategories: '
        catlist= ''
        for entry in entry.attributes['categories']:
            catlist += '<a href="%s">%s</a>, ' % \
                ((urllib.quote("arch_%s<% page_ext %>" % entry)), entry)
        print catlist[:-2]
    #>
</p>

<hr width="50%" />

If you are using your category names as links, then you ought to escape them properly [5]. This is why I include something a bit like :

import urllib
# this imports the urllib module

entry = 'A Category'
link_target = urllib.quote("arch_%s.<% page_ext %>" % entry)
print '<a href="%s">%s</a>' % (link_target, entry)

# urllib.quote does the escaping
# the '%s....%s' % (something, something_else)
# replaces the '%s' with the values on the right

The Page Template

After producing the individual entries, Firedrop2 builds all the pages. This includes the front page and various sorts of archives. Several of the values are the same as the entry_template, but different attributes are more relevant:

options
This is the contents of your build.ini file for this site, as a dictionary. You are likely to use a different set of members in your page_template than you do in the entry_template.
- options['title'] - Your Blog Title
- options['frontpage_name'] - The filename (and therefore relative link to...) the front page of your blog.
- options['description''] - The description of your blog.
- options['rss_filename'] - The filename of your RSS feed.
- options['atom_filename'] - The filename of your atom feed.
- options['categories'] - The list of categories in your blog.
Some of these values you may know, you may feel they are unlikely to change. The advantage of using the values from the options dictionary, rather than just using the values, is that you are able to edit them through the Firedrop GUI. Any changes will then be reflected in every page when you next hit Build.
body

The set of all entries on this page.
shared
This is an interesting object. It acts as an object shared between the pages. It stores all the archives, so you can use it as a way of creating links to previous archives.

It has two attributes :
- shared.archives - this contains a list of ( archive_id, entries).
- shared.archive_names - this contains a list of tuples (archive_id, pagename). The ordering of this list obeys your setting in build.ini.

Example page_template

Following is the framework of my page_template.html file. It serves as an example :

<!DOCTYPE html PUBLIC
    "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
    lang="en" xml:lang="en">
<head>
    <title><% options['title'] %></title>
    <link rel="stylesheet"
        href="/stylesheets/rest.css" type="text/css" />

</head>
    <div id="nav">
        <a class="skiplink" href="#startcontent">
            Skip over navigation</a>
        <a href="/index2.shtml">Home</a> >
        <a href="../index.shtml">Python Index</a> >
        <a href="index.shtml">Techie Blog</a>
    </div>

    <div id="main">
        <a name="startcontent" id="startcontent"></a>
        <div class="title">
            <h1><% options['title'] %></h1>
            <em><% options['description'] %></em>
        </div>

        <div class="sitemap" id="index">
            <table border="1" width="300"
                summary="Links to the archives">
            <tbody>
            <tr>
            <th colspan="2" >Weblog Category Archives</th>
            </tr>
            <tr><td>
            <a href="all_by_date<% page_ext %>">All By Date</a>
            </td>
            <td>
            <a href="all_by_category<% page_ext %>">All By Category</a>
            </td></tr>
        <#
            # this displays the links to the different categories
            import urllib
            categories = options.get('categories', [])
            # just in case no entries are set
            categories.sort()
            a = 0
            start = '<tr><td><a href="%s">%s</a></td>'
            end = '<td><a href="%s">%s</a></td></tr>'
            finish = '<td>&nbsp;</td></tr>'
            last = True
            while a < len(categories):
                category = categories[a]
                p = "arch_%s<% page_ext %>" % (category,)
                pagename = urllib.quote(p)
                if not a % 2:
                    print start % (pagename, category)
                    last = False
                else:
                    print end % (pagename, category)
                    last = True
                a += 1
            if not last:
                print finish

        #>

            <tr>
                <td>&nbsp;</td>
                <td>&nbsp;</td>
            </tr>

            </tbody>
            </table>

        </div>

        <div class="mainbody">

            <% body %>

            <div class="indexblock" >
                <h2>Archives</h2>
                <ul class="links">
                <#
                shared.archive_names.sort()
                archlist = shared.archive_names[-10:]
                # last ten archives
                archlist.reverse()
                for archid, pagename in archlist:
                    line = '<li><a href="' + pagename + '">' \
                        + archid + '</a></li>'
                    print line
                #>
                </ul>
            </div>

            <div class="indexblock" >
            <ul class="links">
                <li><a href="index<% page_ext %>">Front page</a></li>
                <li><a href="index.xml">RSS Feed</a></li>
                <li><a href="atom.xml">Atom Feed</a></li>
                <li><a href="#index">Return to Top</a></li>
            </ul>
            </div>

        </div>
</body></html>

The Indexpage Template

After producing the individual entries, Firedrop2 builds all the pages. This includes the front page and various sorts of archives. If your site contains an Article Collection or Item List, an indexpage will also be built. Most of its values are the same as the entry_template and page_template, but different attributes are more relevant:

footer

This causes a default footer to be drawn on the bottom of every page. The default footer contains the text "Powered by", followed by the Firedrop2 mini-banner:

We know you'll want to let people know your site your site was built with Firedrop2.

Example page_template

Following is the framework of an indexpage_template.html file. It serves as an example :

<#
    print "<head><title><% options['title'] %></title>"
    print '<link rel="stylesheet" href="default.css" type="text/css" /></head>'
    print "<body>"
    print "<h1>%s</h1>" % options['title']
    print "<p>&nbsp;</p>"
    print "<p>Article Collection contains these articles:</p>"
#>
<% index_body %>
<#
    print "<hr>"
#>
<% footer %>
<#
    print "</body>"
#>

A Word About Macros

There is another way of calling simple functions from within templates. These are called macros. Macros allow you to use a shorthand for often-used text or HTML. Included is an example macro file (and supporting modules). It has macros for inserting smilies, colorising Python files, acronyms, etc. You will need to modify it for your own sites, by putting the correct paths into the source code at least. See the page on macros for more details.

Note that macros are evaluated after the template is rendered.

Footnotes

[1]	`name` can be a single value or even an expression. It is the result that is inserted.

[2]	Or written to stdout.

[3]	Because it is a function we have to call it to get the value it returns. This is why it ends with `()`.

[4]	A dictionary is one of the basic Python datatypes. It means it is a set of values that you access by their name. `dictionary['name']` is the value stored in dictionary, that is called name.

[5]	This turns all the characters that shouldn't be in links into their escaped equivalents. See the urllib docs.

Return to Top
Part of the Firedrop2 Docs
Page last modified Fri Apr 28 21:51:53 2006.

Planet Firedrop