Template names take the form
name.ext.type, where
name.ext identifies the name of the output file
to be created in the output_directory, and type
indicates which language processor to use for the template.
Like with filters, templates may be written
in a variety of languages and are based on the standard Unix pipe convention
of producing stdout from stdin, but in practice
two languages are used more than others:
Many find htmltmpl
easier to get started with as you can take a simple example of your
output file, sprinkle in a few <TMPL_VAR>s and
<TMPL_LOOP>s and you are done. Eventually, however,
you may find that your template involves <TMPL_IF>
blocks inside of attribute values, and you may find the result difficult
to read and create correctly.
It is also important to note that htmltmpl based templates do not have access to the full set of information available in the feed, just the following (rather substantial) subset:
VAR type source author String author author_name String author_detail.name generator String generator id String id icon String icon last_updated_822 Rfc822 updated_parsed last_updated_iso Rfc3399 updated_parsed last_updated PlanetDate updated_parsed link String link logo String logo rights String rights_detail.value subtitle String subtitle_detail.value title String title_detail.value title_plain Plain title_detail.value url String links[rel='self'].href headers['location']
Note: when multiple sources are listed, the last one wins
In addition to these variables, Planet Venus makes available two
arrays, Channels and Items, with one entry
per subscription and per output entry respectively. The data values
within the Channels array exactly match the above list.
The data values within the Items array are as follows:
Note: variables above which start with
new_ are only set if their values differ from the previous
Item.
If you have the Django
framework installed,
Django templates are automatically available to Venus
projects. You will have to save them with a .html.dj
extension in your themes. The variable set is the same as the one
from htmltmpl, above. In the Django template context you'll have
access to Channels and Items and you'll be
able to iterate through them.
You also have access to the Config dictionary, which contains
the Venus configuration variables from your .ini file.
If you lose your way and want to introspect all the variable in the
context, there's the useful {% debug %} template tag.
In the themes/django/ you'll find a sample Venus theme
that uses the Django templates that might be a starting point for
your own custom themes.
All the standard Django template tags and filter are supposed to
work, with the notable exception of the date filter on
the updated and published dates of an item (it works on the main
{{ date }} variable).
Please note that Django, and therefore Venus' Django support, requires at least Python 2.3.
XSLT is a paradox: it actually makes some simple things easier to do than htmltmpl, and certainly can make more difficult things possible; but it is fair to say that many find XSLT less approachable than htmltmpl.
But in any case, the XSLT support is easier to document as the input is a highly normalized feed, with a few extension elements.
atom:feed will have the following child elements:
planet:source element per subscription, with the same child elements as atom:source, as well as
an additional child element in the planet namespace for each
configuration parameter that applies to
this subscription.planet:format indicating the format and version of the source feed.planet:bozo which is either true or false.atom:updated and atom:published will have
a planet:format attribute containing the referenced date
formatted according to the [planet] date_format specified
in the configurationGenshi approaches the power of XSLT, but with a syntax that many Python programmers find more natural, succinct and expressive. Genshi templates have access to the full range of feedparser values, with the following additions:
feed element which describes the feed
for your planet, there is also a feeds element which contains
the description for each subscription.feed, feeds, and source elements have a child config element which contains the config.ini entries associated with that feed.subtitle, rights, title, summary, content) also contain a stream element which contains the value as a Genshi stream.entries has a new_date and new_feed value which indicates if this entry's date or feed differs from the preceeding entry.