====================== Flavours and Templates ====================== :Author: PyBlosxom Development Team :Version: $Id: flavours_and_templates.txt 1168 2007-12-11 16:33:55Z willhelm $ :Copyright: This document is distributed under the MIT license. .. contents:: Summary ======= PyBlosxom takes the data provided in the entries and by the plugins and transforms it into output using renderers. Output can be in html, xhtml, xml, or anything else--anything that you could get back from a CGI script or web application. The default renderer can be set in your config file like this:: py["renderer"] = "blosxom" PyBlosxom comes with two renderers: blosxom and debug. The debug renderer displays all the data in the various parts of the PyBlosxom Request object. This is really helpful to see what variables are at your disposal and also to debug problems you might be having with plugins you've installed. The blosxom renderer renders entries just like Blosxom does. If you want your blog rendered using a different template system--say Cheetah or htmltmpl--implement a renderer that renders the output. This can be done 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 uses the same template style that Blosxom uses. As such, you can use most Blosxom flavour templates and only have to make some minor modifications. A flavour can be thought of as a theme or an output format. For example, you could have an "html" flavour that renders the blog data in html format. You could have an "xhtml" flavour that renders the blog in a strict xhtml format. You could have a "happy-sunshine" flavour that renders the blog in html format using a happy sunshiney look and feel. You can have an "rss" flavour that renders the output in RSS 2.0 format with enclosures. So on and so forth. A flavour consists of a series of templates each of which is a part of the page that finally gets rendered. The minimum set of templates are these: * **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 You can have other templates as well. Many plugins require additional templates in order to work. The template files for a given flavour all have the same file extension which is the flavour's name. 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 a "joy" flavour, you would have the following files: * content_type.joy * head.joy * story.joy * foot.joy * date_head.joy * date_foot.joy You can have as many flavours as you want in your blog. .. Warning:: A warning about flavour names: The one thing to be aware of is creating a flavour where the name is the same extension as file extensions of your blog entries. For example, the default extension for pyblosxom blog entries is ``.txt``. Don't create a **txt** flavour. PyBlosxom comes with a series of flavours: html, rss (RSS 0.9.1), rss20 (RSS 2.0), and atom (Atom 1.0). These flavours come as part of PyBlosxom and they will work out of the box with no modifications and no configuration changes. Additionally, you can override all or portions of these flavours. We'll talk about this a little later. Additionally, there is a flavour registry on the PyBlosxom web-site (http://pyblosxom.sourceforge.net/). This is where you can submit flavours that you have created and see flavours other people have created and submitted. Where to Put Your Flavour Files =============================== If you want to override the existing flavours, add new flavours, or develop your own flavours, you should set the ``flavourdir`` property of your ``config.py`` file. I have this directory parallel to my datadir. In my flavourdir, I have flavour directories--one for each flavour in my blog:: home |-- willg/ |-- myblog/ |-- entries/ <-- my datadir | |-- content/ <-- category | |-- dev/ <-- category | |-- links/ <-- category | |-- flavours/ <-- my flavourdir |-- html.flav/ <-- defines the html flavour |-- xml.flav/ <-- defines the xml flavour |-- links/ <-- parallels the links category |-- html.flav/ <-- defines the html flavour for the links category In my flavourdir, I have two flavour directories ``html.flav`` and ``xml.flav``. The ``xml.flav`` is a copy of the ``atom.flav`` directory that comes with PyBlosxom. I copied it so that I could use "xml" for the flavour name. This isn't necessarily a wonderful idea, but it helped me upgrade my blog without disturbing planets and writing lots of ``.htaccess`` redirects and such. You'll notice there's an ``html.flav`` directory in the ``links`` directory. When someone is looking at items in the links directory, then PyBlosxom will use this html flavour. 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. .. Note:: A note about the datadir and flavourdir: 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. Template Variables ================== This is the list of variables that are available to your templates. Additionally, plugins that you are using will add additional variables. To use a variable in a template, prefix the variable name with a $. For example, this would expand to the blog's title as a h2:: <h2>$title</h2> Additionally, you can wrap the variable name in parentheses so that PyBlosxom correctly identifies it and expands it:: <h2>$(title)</h2> This helps in situations where a natural delimiter (space, punctuation, ...) doesn't follow the variable. So this won't work:: $urlindex.atom but this will:: $(url)index.atom To get a complete list of what variables are available in your blog, use the debug renderer by changing 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 ----------------------------------------------- PyBlosxom versions 1.3 and later allows you to escape and URL encode any variables by adding ``_escaped`` or ``_urlencoded`` to the end of the variable name. For example, ``title_escaped`` is an escaped form of the title with ' (single-quote) replaced with ``'`` and " (double-quote) replaced with ``"``. ``title_urlencoded`` is a URL encoded form of the title which uses the Python urllib. Variables from config.py ------------------------ These template variables are available to all templates. They come directly from your ``config.py`` file. ``blog_description`` The description of the blog. Example: ``blosxom with a touch of python`` ``blog_title`` The title of the blog. Example: ``RoughingIT - pyblosxom : /weblogs/tools/pyblosxom`` ``blog_language`` The primary language of the blog. Example: ``en`` ``blog_encoding`` The encoding of the blog. Example: ``iso8859-1`` ``blog_author`` The author of the blog (probably you). Example: ``Joe Dirt`` ``blog_email`` The email address of the author of the blog (feel free to obfuscate it). Example: ``joe at joe dot com`` ``blog_icbm`` The geographical location of your blog as a latitude/longitude pair. Example: ``37.448089,-122.159259`` ``base_url`` This is the url up to and including the portion that kicks off PyBlosxom. If you do not specify this in your ``config.py`` file, then it will be generated based on information your web-server passes PyBlosxom in the environment. Example: ``http://www.example.com/~joe/cgi-bin/pyblosxom.cgi`` Example: ``http://www.example.com/~joe/blog`` You should use ``$base_url`` at the beginning of any links that should be handled by PyBlosxom. 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:: py["blog_images"] = "http://www.joe.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 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: ``<p>This is my first post!</p>`` ``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 <p> 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! </p> 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://some.blog.org/`` - brings up the index in the default flavour which is "html" * ``http://some.blog.org/index.html`` - brings up the index in the "html" flavour * ``http://some.blog.org/index.rss`` - brings up the index in the "rss" flavour (which by default is RSS 0.9.1) * ``http://some.blog.org/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://some.blog.org/`` - brings up the index in the default flavour which is "html" * ``http://some.blog.org/?flav=rss`` - brings up the index in the "rss" flavour * ``http://some.blog.org/2004/05/index?flav=joy`` - brings up the index for May of 2004 in the "joy" 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. For example, if you do the above, then the following URIs will use the default flavour: * ``http://www.joe.com/cgi-bin/pyblosxom.cgi/2005/03`` - uses the default flavour which is set to "joy" * ``http://www.joe.com/cgi-bin/pyblosxom.cgi/2005/03/?flav=html`` - uses the html flavour as specified by ``flav=`` 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.