Venus Templates

## Templates

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:

### htmltmpl

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:

> VAR | type | source
> --- | --- | ---
> author | String | author
> author_email | String | author_detail.email
> author_name | String | author_detail.name
> author_uri | String | author_detail.href
> content_language | String | content[0].language
> content | String | summary_detail.value
> content[0].value
> date | PlanetDate | published_parsed
> updated_parsed
> date_822 | Rfc822 | published_parsed
> updated_parsed
> date_iso | Rfc3399 | published_parsed
> updated_parsed
> enclosure_href | String | enclosures[0].href
> enclosure_length | String | enclosures[0].length
> enclosure_type | String | enclosures[0].type
> guid_isPermaLink | String | isPermaLink
> id | String | id
> link | String | links[rel='alternate'].href
> new_channel | String | id
> new_date | NewDate | published_parsed
> updated_parsed
> rights | String | rights_detail.value
> title_language | String | title_detail.language
> title_plain | Plain | title_detail.value
> title | String | title_detail.value
> summary_language | String | summary_detail.language
> updated | PlanetDate | updated_parsed
> updated_822 | Rfc822 | updated_parsed
> updated_iso | Rfc3399 | updated_parsed
> published | PlanetDate | published_parsed
> published_822 | Rfc822 | published_parsed
> published_iso | Rfc3399 | published_parsed

Note: variables above which start with `new_` are only set if their values differ from the previous Item.

### django

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.

The django_autoescape config option may be used to globally set the default value for auto-escaping.

### xslt

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:
  - A `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 configuration

### genshi

Genshi 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:

- In addition to a `feed` element which describes the feed for your planet, there is also a `feeds` element which contains the description for each subscription.
- All `feed`, `feeds`, and `source` elements have a child `config` element which contains the config.ini entries associated with that feed.
- All text construct detail elements (`subtitle`, `rights`, `title`, `summary`, `content`) also contain a `stream` element which contains the value as a Genshi stream.
- Each of the `entries` has a `new_date` and `new_feed` value which indicates if this entry's date or feed differs from the preceeding entry.