$(blog_title)

.. _flavours-and-templates: ====================== Flavours and Templates ====================== Summary ======= This chapter covers the blosxom renderer in Pyblosxom. There are other renderers (like the debug renderer) that operate differently. See the chapter on :ref:`renderers ` for more details. If you want your blog rendered using a different template system---say Cheetah or htmltmpl---implement a renderer that renders the output. This new renderer can be implemented as a Pyblosxom plugin. See the chapter on writing plugins for more information. The rest of this chapter talks about the various things you can do with the blosxom renderer which comes with Pyblosxom. Flavours and templates ====================== The blosxom renderer renders the output of a request with a :term:`flavour`. A :term:`flavour` is a group of templates for a specific output format or style. For example, html, xhtml, atom, rss, rdf, etc. A flavour consists of at least the following templates: * **content_type** - holds the content type of the flavour * **head** - holds everything before all the entries * **story** - holds a single entry * **foot** - holds everything after all the entries * **date_head** - shows at the start of a date * **date_foot** - shows at the end of a date .. Note:: Many plugins require additional templates to render their output in addition to the standard templates listed above. See the documentation for the plugin for more information. .. Note:: Refer to :ref:`lifecycle-of-the-blosxom-renderer` for detailed information on how Pyblosxom's default renderer blosxom uses these templates. More on flavours, how they're stored, and such later. A :term:`template` is one piece of a flavour that specifies a specific portion of the output. For example, the head template of an html flavour would be in a file called ``head`` and might look like this:: $(blog_title) More on templates later. Pyblosxom allows you to manage the flavours and templates for your blog in several different ways: 1. in directories in the flavourdir, OR 2. in directories in the datadir, OR 3. in the datadir along with your entries. .. Note:: Pyblosxom is backwards compatible with previous versions of Pyblosxom. You can put your flavour files in your datadir. You can also put your flavour files in the categories of your datadir. However you cannot have a flavourdir and put flavour files in your datadir---Pyblosxom will look at **EITHER** your datadir **OR** your flavourdir for flavour files. Storing flavours in the flavourdir ---------------------------------- This is the easiest way to store your flavours separately from the entries in your blog. This is the preferred way. If you specify the ``flavourdir`` directory in your ``config.py`` file, you can store each flavour in a directory in the flavourdir. For example, Joe has this in his ``config.py``:: py["flavourdir"] = "/home/joe/blog/flavours/" Joe's blog directory structure would look like this:: /home/joe/blog/ |- entries/ <-- datadir | |- work/ <-- work category of entries | |- home/ <-- home category of entries | |- flavours/ |- html.flav/ <-- html flavour | |- content_type | |- head | |- foot | |- story | |- ... | |- rss.flav/ <-- rss flavour | |- content_type | |- head | |- foot | |- story | |- ... The ``flavourdir`` specifies the directory in which Joe stores his flavours. .. Note:: Flavour directories must end in ``.flav``. .. Note:: Templates in the flavour directory don't need an extension. This structure also makes it easier to use flavour packs found in the flavour registry on the `Pyblosxom website`_. .. _Pyblosxom website: http://pyblosxom.github.com/ Storing flavours in flavour directories in the datadir ------------------------------------------------------ Flavours can be stored in directories in the directory specified by your datadir. This works exactly the same as having a separate flavourdir except that the flavourdir is not a separate directory tree---it's the same tree as your datadir. For example, Joe stores his flavours alongside his entries and his blog directory tree looks like this:: /home/joe/blog/ |- entries/ <-- datadir |- html.flav/ <-- html flavour | |- content_type | |- head | |- foot | |- story | |- ... | |- work/ <-- work category of entries | |- html.flav/ <-- html flavour for the work category | |- ... | |- home/ <-- home category of entries In this way your entries are intermixed with your flavour directories. Storing flavours in the datadir ------------------------------- Instead of storing flavour templates in separate flavour directories in either your datadir or your flavourdir, you can store the templates alongside your entries. This is not recommended---it's a pain in the ass to maintain and everything gets all mixed up. It's supported since this is how Pyblosxom used to work. The template files for a given flavour all have to have the flavour name as the extension of the file. For example, if you were using an "html" flavour, the flavour itself would be composed of the following files: * ``content_type.html`` * ``head.html`` * ``story.html`` * ``foot.html`` * ``date_head.html`` * ``date_foot.html`` If you want to create an "atom" flavour, you would have the following files: * ``content_type.atom`` * ``head.atom`` * ``story.atom`` * ``foot.atom`` * ``date_head.atom`` * ``date_foot.atom`` .. Warning:: If you intermix flavour templates with entries, make sure you don't have flavours that have the same name as the extension of your blog entries. For example, if ``.txt`` is the extension for entries in your blog, don't create a **txt** flavour! Included flavours ================= Pyblosxom comes with the following flavours: * ``html`` - a basic html flavour * ``rss`` - an RSS 2.0 flavour for syndication * ``atom`` - an Atom 1.0 flavour for syndication These flavours are included with Pyblosxom and they will work out of the box with no modifications and no configuration changes. When you run ``pyblosxom-cmd create ``, these get copied into the flavourdir. Play with them! Modify them! Extend them! Overriding included flavours ============================ Pyblosxom allows you to override templates and flavours on a category-by-category basis. For example, Joe has a category devoted to his work on plants which he wants branded differently than the rest of his blog. Joe uses the category *work* for all his plant work and has a different flavour for this category of his blog. Joe's blog directory looks like this:: /home/joe/blog/ |- entries/ <-- datadir | |- work/ <-- work category of entries | |- home/ <-- home category of entries | |- flavours/ |- html.flav/ <-- html flavour | |- content_type | |- head | |- foot | |- story | |- ... | |- work/ |- html.flav/ <-- html flavour for the work category |- ... There is a ``work`` directory in his ``flavours`` directory that parallels the ``work`` directory in his ``entries`` directory. In Joe's blog, the work category has a different html flavour than the root and home categories. You can override individual templates, too. For example, if you had a math category and wanted the story template to look different, you could set up your blog like this:: blog/ |- entries/ | |- math/ <-- math category in datadir | |- flavours/ |- html.flav/ | |- content_type | |- head | |- date_head | |- story | |- date_foot | |- foot | |- math/ <-- math category in flavourdir |- html.flav/ |- story If the request is for an entry in the math category, then the ``story`` file will be taken from the ``flavours/math/html.flav/`` directory and the rest of the templates will be taken from ``flavours/html.flav/``. Finding new flavours ==================== There is a flavour registry on the `Pyblosxom website`_. You can find flavours here that have been created by other people and submit flavours that you've created and want to share. .. _Pyblosxom website: http://pyblosxom.github.com/ Additionally, you can use flavours from `Blosxom`_ and themes from `WordPress`_ after spending some time converting them. .. _Blosxom: http://www.blosxom.com/ .. _WordPress: http://wordpress.org/ The order of overiding works like this: 1. Pyblosxom looks for flavour files that came with Pyblosxom 2. Pyblosxom starts at the root of the flavourdir and looks for flavour files there. If there are some, then these files override the files Pyblosxom has found so far. 3. Pyblosxom iterates through category directories in the flavourdir if there are any that are parallel to the datadir and looks for flavour directories there. If there are some, then those files override the files it has so far. This allows you to easily override specific templates in your blog (like the header or footer) depending on what category the user is looking at. Template variables ================== This is the list of variables that are available to your templates. Templates contain variables that are expanded when the template is rendered. Plugins may add additional variables---refer to plugin documentation for a list of which variables they add and in which templates they're available. Variable syntax --------------- To use a variable in a template, prefix the variable name with a $. For example, this would expand to the blog's title as an h2::

$title

To reduce ambiguity, use parenthesized variables.::

$(title)

You can also use variables that expand into functions which are evaluated::

$(escape(title))

Escaping the $ -------------- If you want a $ in your template that shouldn't signify variable expansion, then you need to escape it with a ``\``::

This blog is all about \$!

renders as:: This blog is all about $! Getting a complete list of variables ------------------------------------ To get a complete list of what variables are available in your blog, use the debug renderer by changing the value of the ``renderer`` property in your ``config.py`` file to ``debug`` like this:: py["renderer"] = "debug" That will tell you all kinds of stuff about the data structures involved in the request. Don't forget to change it back when you're done! URL encoding and escaping of template variables ----------------------------------------------- There are two filters allowing for escaped and urlencoded values: * ``$escape(title)`` - escapes ``$title`` * ``$urlencode(title)`` - urlencoded ``$title`` Plugins can add additional filters. .. Note:: Pyblosxom versions 1.3 and 1.4 escaped and urlencoded variables that ended with ``_escaped`` and ``_urlencoded``. Deprecated in Pyblosxom 1.5. Variables from config.py ------------------------ Anything in your ``config.py`` file is a variable available to all of your templates. For example, these standard properties in your ``config.py`` file are available: * ``blog_description`` * ``blog_title`` * ``blog_language`` * ``blog_encoding`` * ``blog_author`` * ``blog_email`` * ``base_url`` (if you provided it) * ... Additionally, any other properties you set in ``config.py`` are available in your templates. If you wanted to create a ``blog_images`` variable holding the base url of the directory with all your images in it:: py["blog_images"] = "http://example.com/~joe/images/" to your ``config.py`` file and it would be available in all your templates. Calculated template variables ----------------------------- These template variables are available to all templates as well. They are calculated based on the request. ``root_datadir`` The root datadir of this page? Example: ``/home/subtle/blosxom/weblogs/tools/pyblosxom`` ``url`` The PATH_INFO to this page. Example: ``pyblosxom/weblogs/tools/pyblosxom`` ``flavour`` The flavour that's being used to render this page. Example: ``html`` ``latest_date`` The date of the most recent entry that is going to be rendered. Example: ``Tue, 15 Nov 2005`` ``latest_w3cdate`` The date of the most recent entry that is going to be rendered in w3cdate format. Example: ``2005-11-13T17:50:02Z`` ``latest_rfc822date`` The date of the most recent entry that is going to show in RFC 822 format. Example: ``Sun, 13 Nov 2005 17:50 GMT`` ``pi_yr`` The four-digit year if the request indicated a year. Example: ``2002`` ``pi_mo`` The month name if the request indicated a month. Example: ``Sep`` ``pi_da`` The day of the month if the request indicated a day of the month. Example: ``15`` ``pi_bl`` The entry the user requested to see if the request indicated a specific entry. Example: ``weblogs/tools/pyblosxom`` ``pyblosxom_version`` The version number and release date of the pyblosxom version you're using. Example: ``1.2 3/25/2005`` Template variables only available in the date_head and date_foot templates -------------------------------------------------------------------------- ``date_head`` and ``date_foot`` templates have these additional variables: ``date`` The date string of this day. Example: ``Sun, 23 May 2004`` Template variables only available in the story template ------------------------------------------------------- These template variables are only available in your story template. ``title`` The title of the entry. Example: ``First Post!`` ``filename`` The absolute path of the file that the entry is stored in. Example: ``/home/subtle/blosxom/weblogs/tools/pyblosxom/firstpost.txt`` ``file_path`` The filename and extension of the file that the entry is stored in. Example: ``firstpost.txt`` ``fn`` The filename with no extension of the file that the entry is stored in. Example: ``firstpost`` ``absolute_path`` The category/path of the entry (from the perspective of the url). Example: ``weblogs/tools/pyblosxom`` ``body`` The text of the entry. Example: ``

This is my first post!

`` ``tb_id`` The trackback id of the entry. Example: ``_firstpost`` ``path`` The category/path of the entry. Example: ``weblogs/tools/pyblosxom`` ``yr`` The four-digit year of the mtime of this entry. Example: ``2004`` ``mo`` The month abbreviation of the mtime of this entry. Example: ``Jan`` ``mo_num`` The zero-padded month number of the mtime of this entry. Example: ``01`` ``ti`` The 24-hour hour and minute of the mtime of this entry. Example: ``16:40`` ``date`` The date string of the mtime of this entry. Example: ``Sun, 23 May 2004`` ``w3cdate`` The date in w3cdate format of the mtime of this entry. Example: ``2005-11-13T17:50:02Z`` ``rfc822date`` The date in RFC 822 format of the mtime of this entry. Example: ``Sun, 13 Nov 2005 17:50 GMT`` ``fulltime`` The date in YYYYMMDDHHMMSS format of the mtime of this entry. Example: ``20040523164000`` ``timetuple`` The time tuple (year, month, month-day, hour, minute, second, week-day, year-day, isdst) of the mtime of this entry. Example: ``(2004, 5, 23, 16, 40, 0, 6, 144, 1)`` ``mtime`` The mtime of this entry measured in seconds since the epoch. Example: ``1085348400.0`` ``dw`` The day of the week of the mtime of this entry. Example: ``Sunday`` ``da`` The day of the month of the mtime of this entry. Example: ``23`` Also, any variables created by plugins that are entry-centric and any variables that come from metadata in the entry are available. See those sections in this document for more details. Template variables from plugins ------------------------------- Many plugins will create additional variables that are available in templates. Refer to the documentation of the plugins that you have installed to see what variables are available and what they do. Template variables from entry metadata -------------------------------------- You can add metadata to your entries on an individual basis and this metadata is available to your story templates. For example, if I had a blog entry like this:: First Post! #mood happy #music The Doors - Break on Through to the Other Side

This is the first post to my new Pyblosxom blog. I've also got two metadata items in it which will be available as variables!

You'll have two variables ``$mood`` and ``$music`` that will also be available in your story templates. Invoking a flavour ================== The flavour for a given page is specified in the extension of the file being requested. For example: * ``http://example.com/`` - brings up the index in the default flavour which is "html" * ``http://example.com/index.html`` - brings up the index in the "html" flavour * ``http://example.com/index.rss`` - brings up the index in the "rss" flavour (which by default is RSS 0.9.1) * ``http://example.com/2004/05/index.joy`` - brings up the index for May of 2004 in the "joy" flavour Additionally, you can specify the flavour by adding a ``flav`` variable in the query-string. Examples: * ``http://example.com/`` - brings up the index in the default flavour which is "html" * ``http://example.com/?flav=rss`` - brings up the index in the "rss" flavour * ``http://example.com/2004/05/index?flav=joy`` - brings up the index for May of 2004 in the "joy" flavour Setting default flavour ======================= You can change the default flavour from ``html`` to some other flavour in your ``config.py`` file with the ``default_flavour`` property:: py["default_flavour"] = "joy" Doing this will set the default flavour to use when the URI the user has used doesn't specify which flavour to use. This url doesn't specify the flavour to use, so it will be rendered with the default flavour:: http://example.com/cgi-bin/pyblosxom.cgi/2005/03 This url specifies the flavour, so it will be rendered with that flavour:: http://example.com/cgi-bin/pyblosxom.cgi/2005/03/?flav=html Order of operations to figure out which flavour to use ====================================================== We know that you can specify the default flavour to use in the ``config.py`` file with the ``default_flavour`` property. We know that the user can specify which flavour to use by the file extension of the URI. We also know that the user can specify which flavour to use by using the ``flav`` variable in the query string. The order in which we figure out which flavour to use is this: 1. look at the URI extension: if the URI has one, then we use that. 2. look at the ``flav`` querystring variable: if there is one, then we use that. 3. look at the ``default_flavour`` property in the ``config.py`` file: if there is one, then we use that. 4. use the ``html`` flavour. Examples of templates ===================== For examples of templates and flavours, see the included flavours that come with your Pyblosxom installation.