Templates

Renao uses a templating system to make your content visible to your site visitors.  The form fields you fill out in Renao for your articles, files and so forth do not exist as pages to be viewed or files to be downloaded until the moment a visitor requests it.  At that point Renao pulls the information about your resource, looks for a suitable template, and ‘fills in’ the blanks in the template with your resource’s information.  The result is an html page, or a thumbnail version of that image you uploaded, or an rss feed your visitor can subscribe to.

Renao comes with a set of default templates that should handle most common use cases.  Most of them are used to create html pages for your resources.  You are probably here because you’ve decided that something about these default templates doesn’t quite meet your needs, or that you are looking to completely change your site design.

Before you go any further, you might want to explore if working with stylesheets will give you the results you are looking for.  The default html templates for Renao are written with the goal of being highly modifiable through CSS alone.  Indeed, this is how the theme system works.

how renao chooses templates

When a site visitor requests a resource from your site, how does Renao figure out which template to use?  There are four major factors:

• What kind of resource is it?
• Are they actually asking for a list of that type of resource, rather than an individual resource (for example, search results)?
• What collection is the resource in?
• Is there a specific extension on the url?

What kind of resource is it?

Templates are named to match the type of resource they’re intended to render.  So a template intended to render an Article will have a name that begins with ‘article’.  An Image will use a template prefixed with ‘image’. And so on.

Some resource types are a more specific kind of another resource.  Specifically, any Image is also a File.  So if Renao can’t find an appropriate template that starts with ‘image’, it will look for one prefixed with ‘file’ instead.  Any resource that cannot find an appropriately named template will look for one that is prefixed with ‘resource’, as the fall-back of last resort.

What collection is it in?

You may very well want to use different templates depending on what collection a resource is in, in order to lend a different design to each area of your site.  Renao will look to see if you have created a folder in the templates folder with the same name as the collection in question.  If it finds such a folder it will first apply the above type-matching and plurality-matching criteria in that folder.  If that fails, it will move up a folder level (and hence, a collection level) and try all over again, until it reaches the top level templates folder.

Is there a specific extension on the url?

The last criteria Renao uses for template-finding is whether the url is suffixed with a particular extension.  For example, you would want a url that ended in ‘.html’ to return an html page, and an ‘.rss’ url to return an RSS feed, even if they both represented the same underlying resource.  To that end Renao will look for templates with a matching suffix, so ‘.html’ requests are matched with ‘.html’ templates, and so on.

Not all urls are required to have an extension.  An extension-free url will look for an extension free template.  However, if one is not found, it will assume that the ‘default’ representation for your resource is html, and will then try again, looking for ‘.html’ suffixed templates.

Renao provides a number of differently suffixed templates as part of its default set, including html,rss,xml and json.  You are free to create templates with other extensions to fulfill your site's needs.

the templating language

Renao uses the Template Toolkit, a popular templating language developed by Andy Wardley.  The full documentation for the language can be found on the Toolkit's site.  There is also a book available. We will look very briefly at a basic example here to help you get the flavor of the language, but to get a full understanding you will want to spend some time learning from the Toolkit's own documentation.  There are also plenty of examples to study under the 'templates' tab in the design section of your Renao site.

a simple example

Templates are a mix of html and specially marked template directions (templates can be something other than html, but to keep our example simple we'll stick with the most common case).  These directions are wrapped inside a pair of special brackets, like so:

[% directive_goes_here %]

Here is a basic example of a complete template file which could be used to show an article and any resources related to it (the line numbers are not part of the template):

 1  [% WRAPPER 'wrappers/site.t' %]
 2  <div id=”content”>
 3  <h1>[% resource.name %]</h1>
 4  [% resource.body %]
 5
 6  <h3>you may also like:</h3>
 7  <ul id=”related”>
 8  [%
 9      FOREACH related IN resource.related;
10      %]<li><a href=”[% related.makelink() %]”>[% related.name %]</a></li>[%
11      END;
12  %]
13  </ul>
14
15  [%
16      IF resource.commentable;
17          PROCESS 'comment_form.html';
18      END;
19   %]
20  </div>
21  [% END %]

You'll notice the mix of html markup (in blue) and the template directives (in gray).  The markup sits in the places in the file relative to where they will appear in the final output.  The directives either include other templates (lines 1 and 17), add information from your resource (for example, lines 3 and 4), or generate more html (as they do on lines 9 - 11).

Including other templates

The first advantage of using a templating system is that you can take bits of your design that show up over and over on your site and move them into their own template files.  Then when that footer or that menu that you use absolutely everywhere needs to change, you only need to modify the footer or menu file, and all the templates using them will automatically include the updates.

Line 1 uses a WRAPPER directive, followed by a filename.  A wrapper is a template which includes the output of the current template somewhere in the middle of its own output (indicated in the wrapper template with the special [% content %] variable).  The END directive on line 21 is the end of the WRAPPER.

Line 17 uses a PROCESS directive to include the output of the named template (comment_form.html) in its stead.  This is conceptually the opposite of the WRAPPER directive.  Instead of wrapping our template's output inside another template, we are instead wrapping some other template's output inside our own.

Adding information from your resource

Getting information out of your resource and into the template is as simple as saying the information’s name.  The resource at hand is stored in a variable named ‘resource’ (lines 3,4,9 and 16).  Properties of that resource are represented using a syntax called dot-notation.  You can see this on lines 9 ( .related indicating the ‘related resources’ property) and 16 (.commentable indicating the ‘commentable’ property on the publishing tab).

Beyond the resource variable there are also some functions you can call.  Some of these are attached directly to the resource variable (such as makelink() on line 10) and some are used independently.  For a complete list please see the Template Toolkit documentation on vmethods, and the section below on renao-specific functions and variables.

Generating more HTML

In some cases the html you need to produce will depend on the resource you are rendering.  The IF statement on line 16 (closed by the END directive on line 18) instructs the template to only run the PROCESS directive if the resource’s commentable property is true.  This is a basic control directive known more generally as a conditional statement.  Depending on the value of the variable after the IF directive, it may or may not run the template directives within.

The FOREACH directive on line 9 (terminated on line 11) is an example of a loop.  A loop takes the items from a list ( in this case, resource.related ).  One at a time, it uses these items within the block between the loop declaration (line 9) and the loop’s termination (line 11).

the _components folder

The top level templates folder, and any you create which match the name of one of your collections, hold templates that Renao expects to use directly to display your site's content.  As your design and site mature, you will probably have code snippets that you would like to use in multiple templates via the WRAPPER and PROCESS directives.

That is what the special '_components' folder is for.  You'll notice that there are already some template snippets present.  If you open them you will find that they are not complete html templates, but rather they are injectable 'components', ready to be used by your main templates.  You can add any of your own component templates here as well.

Additionally, when you do include these component templates in your other templates (or in each other), you can leave the '_components' prefix off of the file path.  Renao knows to check for

 _components/wrappers/site.html

when you write

wrappers/site.html

renao-specific functions and variables

In addition to the features provided by the Template Toolkit, there are variables and functions specific to Renao available in your templates.  These have primarily to do with displaying the resource or resources that the site visitor requested

Variables

The variables Renao provides to you in the template all pertain to your site's content and the request made by the visitor.

uri

This variable is the url the visitor requested

request

This variable holds information about the request the visitor made of your site.  It is actually a CGI::Simple object.  You will probably be most interested in the param() method, which lets you retrieve parameters that are in the request's query string, like so:

given a url of http://mysite.com/about?which=foo

you can get the value of the 'which' parameter like so:

[% request.param('which') %]

resource or resources

If the visitor requested a url that represents a single resource, then the resource variable will be available.  If they requested a url which represents a list of resources, then the resources variable will be available.  The resources variable is actually a list, which can be looped through in a fashion similar to the FOREACH loop on line 9 of the example above.

type

The type variable stores information about the properties of the resource or resources requested.  An idiom for displaying that information in your template is this:

<pre>[% USE Dumper; Dumper.dump( type.definition.properties ) %]</pre>

site

This variable holds information about your site, including things such as the site navigation and homepage info.  You can see a list of fields available by using the Dumper example above, but substitute site.definition.properties for type.definition.properties.

collection

This variable represents the collection that contains the current resource or resources.  Again you can get information about the collection's properties with the Dumper idiom above.

Functions

makelink()

This function is appended to a resource to do just what it says.  It generates a url for the resource which you can display or embed in a link tag.  Using this function is preferable to hand-coding the link because it will take care of changing the link if you move or re-alias the resource. any named arguments you pass into the function will be appended to the link's query string, with two exceptions:

<a href="[% resource.makelink( view = 'xml', path='foo/bar', q='example' ) %]" >

results in:

<a href="/myresource/foo/bar.xml?q=example" >

The path argument is appended to the url's path and the view is appended as an extension to the end of the path.

headers()

This function lets you set or get information about the HTTP response headers that will be sent back to the visitor.  The common use case for this function is setting the Content-type header for templates that generate something other than HTML.  Refer to the documentation here for the types of values you can pass into the function.

Plug-ins

A number of Renao’s features are exposed as Template Toolkit Plugins

• Resources Plugin
  
• Download Plugin
  
• Theme Plugin