Templates

Templates are one of Awasu's more powerful features that lets you control how your channel pages, reports, etc. look. You just specify how the page should look in a template file, using placeholders to indicate where you want things like the channel name, item descriptions, etc. to go and Awasu will use that to dynamically generate each page. Here's a really simple example that generates an HTML list for all the feed items in a channel:

<ul>
{%REPEAT% FeedItems}
    <li> <a href="{%ITEM-METADATA% url}"> {%ITEM-METADATA% name} </a>
{%/REPEAT%}
</ul>

{%REPEAT% FeedItems%} instructs Awasu to repeat through each feed item and as it does so, {%ITEM-METADATA% url} and {%ITEM-METADATA% name} will be replaced with the current item's URL and name respectively.

Metadata

Metadata means "information about information." Awasu brings all this information to you via RSS/Atom feeds but it also tracks a lot of information about this information e.g. when a feed item was published, who wrote it, if it has any enclosures, etc. Awasu tracks a lot of metadata about each channel and its items, all of which can be included in templates using the {%CHANNEL-METADATA%} and {%ITEM-METADATA%} parameters.

Metadata is stored in a tree-like hierarchy, so a channel's metadata might look something like this:

    *
    |
    +-- Name            The channel's name
    +-- Description     The channel's description
    +-- Link
    |   |
    |   +-- URL         The channel's home page URL
    |
    +-- Author
        |
        +-- Name        The author's name.
        +-- Email       The author's email address.
        +-- URL         The author's home page

These are accessed using the {%CHANNEL-METADATA%} parameter and so you could create a link to the author's home page like this:

<a href="mailto:{%CHANNEL-METADATA% author/url}">
    {%CHANNEL-METADATA% author}
</a>

Entries in the metadata hierarchy are either metadata values (e.g. Name or URL in the example above) or metadata groups (e.g. Link or Author). Metadata groups have no actual value themselves but if they are used in template parameters (e.g. {%CHANNEL-METADATA% author}) then Awasu will check the child metadata values and choose the most appropriate one.

So, in the example above, Awasu will generate a mailto: link for the author's email address, using the author's name, email address or URL (in that order of preference) as the display text.

Conditional sections

Templates can test for certain conditions and generate different output according to the results.

{%?xxx%} tests if the xxx parameter has been set and if so, generates the output up to the next {%ENDIF%} tag. {%!xxx%} does the opposite, generating output if the parameter has not been set. Both of these can also have an {%ELSE%} clause.

The following example checks if a feed item has an author. If it does, it outputs the author's name (or if not present, email address or URL), wrapped in a mailto: link if the author's email address has been given.

{%?CHANNEL-METADATA% author}                test if the channel has specified an author
    {%?CHANNEL-METADATA% author/email}      test if the author's email address was given
        <a href="mailto:{%@%}">               yes - start the mailto: link
    {%ENDIF%}
        {%CHANNEL-METADATA% author}         insert the author's name/email/URL
    {%?CHANNEL-METADATA% author/email}      test if the author's email address was given
        </a>                                  yes - close the mailto: link
    {%ENDIF%}            
{%ELSE%}
    No author was specified!                insert this if no channel author was specified
{%ENDIF%}

{%@%} is a shorthand for the parameter evaluated in the previous {%?xxx%} tag.

Parameter encoding

There is one small problem in the example above. If the author's name contains a < character, the generated output might look something like this:

<a href="mailto:joe@blow.com"> Joe<Blow </a>

and the < character will cause problems in an HTML browser.

Awasu automatically handles this by checking the extension of the output file and encoding values appropriately. However, there are some cases where the default handling is not enough and so you can force encoding by adding encode and chars attributes to the template parameter. For example:

    {%CHANNEL-METADATA% author encode=sgml chars=<&"}

This insert the channel's author but SGML-encodes the three special characters specified.

The encode attribute may have the values sgml, percent or none. For SGML encoding, the default characters encoded are < and & while for percent encoding, only the % character is encoded by default.

The example above also suffers from the same problem when generating the mailto: link if the email address contains a " character. The code below shows how both these issues can be fixed:

{%?CHANNEL-METADATA% author}
    {%?CHANNEL-METADATA% author/email}
        <a href="mailto:{%@% encode=sgml chars=<&\"}">
    {%ENDIF%}
        {%CHANNEL-METADATA% author encode=sgml chars=<&\"}
    {%?CHANNEL-METADATA% author/email}
        </a>
    {%ENDIF%}            
{%ELSE%}
    No author was specified!
{%ENDIF%}

Repeating sections

Templates often need to repeatedly generate the same bit of output. For example, channel summary pages need to loop through each feed item being shown, inserting the content and other details for each one into the page. This is done by using the {%REPEAT% xxx} tag.

Similarly, feed items can have more than one author. The example above doesn't use the {%REPEAT% xxx} tag and so just shows the first author. To show all the authors, the code must be wrapped in a {%REPEAT% xxx} tag like this:

{%?CHANNEL-METADATA% author}
    {%REPEAT% author}
        {%?CHANNEL-METADATA% author/email}
            <a href="mailto:{%@% encode=sgml chars=<&\"}">
        {%ENDIF%}
            {%CHANNEL-METADATA% author encode=sgml chars=<&\"}
        {%?CHANNEL-METADATA% author/email}
            </a>
        {%ENDIF%}            
    {%ELSE%}
        No author was specified!
    {%/REPEAT%}
{%ENDIF%}

Awasu repeatedly tests if there is another author metadata value, outputting each author's name, wrapped in a mailto: link if an email address was provided.

Include files

Templates can include other files using the {%INCLUDE%} directive. Awasu uses this feature heavily, putting the bulk of the template code in a separate file that is then just included by whoever needs it. For example, the Rusty.template file looks like this:

<html>

<head>
    {%INCLUDE% includes/StandardHead.include}
    <style>
        {%INCLUDE% Rusty.css}
        {%INCLUDE% Rusty.user.css isOptional}
    </style>
</head>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<body>
    {%INCLUDE% includes/StandardBody.include}
</body>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

</html>

The {%BASE-DIR%} template parameter is adjusted each time to point to the directory that the template file currently being processed lives in. This allows template files to reference external resources such as images e.g. from Rusty.css:

.banner
{
    background-image: url( "file://{%BASE-DIR%}/images/Rusty/banner.png" ) ;
    background-repeat: repeat-x ;
    border: 3px double ;
    padding: 10px ;
    color: #fff ;
}