Blogging Roller

• How to create a Roller 4.0 theme, part 1: directory structure and required files
• How to create a Roller 4.0 theme, part 2: the theme.xml file

In part one I explained how to create a theme directory and add the required template and resource files. Now I'll wrap things up by explaining what goes into a theme.xml theme definition file and how to deploy your new theme.

Create a theme.xml file

The example1 theme that I discussed in part one has a preview image, a Stylesheet Override file, a weblog template, a _day template, a custom template that displays an about page and a single image called aquadot.jpg. The theme.xml theme definition file below includes each of those items.

<?xml version="1.0" encoding="UTF-8"?>
<weblogtheme>    
  <id>example1</id> 
  <name>Example1: minimal theme</name>
  <author>Dave Johnson</author>     
  <preview-image path="preview.jpg" />

  <stylesheet>
    <name>Override</name>
    <description>Stylesheet override</description>
    <link>override.css</link>
    <templateLanguage>velocity</templateLanguage>
    <contentsFile>override.css</contentsFile>
  </stylesheet>

  <template action="weblog">
    <name>Weblog</name>
    <description>Main template of weblog</description>
    <link>weblog</link>
    <navbar>false</navbar>
    <hidden>true</hidden>
    <templateLanguage>velocity</templateLanguage>
    <contentType>text/html</contentType>
    <contentsFile>weblog.vm</contentsFile>
  </template>

  <template action="custom">
    <name>_day</name>
    <description>Displays one day of entries</description>
    <link>_day</link>
    <navbar>false</navbar>
    <hidden>true</hidden>
    <templateLanguage>velocity</templateLanguage>
    <contentType>text/html</contentType>
    <contentsFile>day.vm</contentsFile>
  </template>

  <template action="custom">
    <name>About</name>
    <description>About this weblog...</description>
    <link>about</link>
    <navbar>true</navbar>
    <hidden>false</hidden>
    <templateLanguage>velocity</templateLanguage>
    <contentType>text/html</contentType>
    <contentsFile>about.vm</contentsFile>
  </template>

  <resource path="images/aquadot.jpg" />   
</weblogtheme>

Now I'll break it down and explain each element.

Inside <weblog-theme>

The root element of the XML file contains some theme meta-data, an optional stylesheet, one or more templates and zero or more resources. Here's a run-down of the meta-data you must include in each theme:

• <id> - the unique ID, by convention this is the same as directory name
• <name> - name of the theme
• <author> - name of theme author
• <preview-image path="path/to/image"> - path to image preview file, relative to theme directory

The <stylesheet> override

Following the theme meta-data is the stylesheet declaration, including all of the required elements:

• <name> - name of stylesheet
• <description> - description of stylesheet
• <link> - value used in stylesheet URI (e.g. ~http://example.com/../page/styles.css)
• <templateLanguage> - in 4.0, this must be 'velocity'
• <contentsFile> - path to theme file containing stylesheet, relative to theme directory

The <template> elements

Next are the template elements, one for each page template. Each element must have an 'action' attribute that declares on which action the template will be invoked. Here are the possible values of the action attribute:

• weblog: Each theme must have a weblog template, which displays the main page of the blog
• permalink: (optional) template which will be used when displaying individual entries
• searchIndex: (optional) template to be invoked to display search results
• tagsIndex: (optional) template to be used when displaying entries by tag
• custom: (optional) You can add as many custom templates as you want.

And here are the elements that must be included in a <template>:

• <name> - name of the template
• <description> - description of template
• <link> - value used in stylesheet URI (e.g. ~http://example.com/../page/mypage)
• <navbar> - true if page should be include in navigation menus generated by standard macros
• <hidden> - true if page not to be called directly and only used as an include
• <templateLanguage> - in 4.0, this must be 'velocity'
• <contentType> - the content-type to be generated by the template
• <contentsFile> - path to theme file containing template, relative to theme directory

Including resources

After the template elements, we include the one <resource> element we need for the one image that is included in the theme. The path is relative to the theme directory.

Deploying your theme to Roller

To make your theme available to Roller, copy the theme directory into the Roller themes directory. Restart Roller and watch the logs to see that your theme is deployed correctly. If there is an error in your theme.xml file you should see an XML parser error in your roller.log file. You can also turn on additional theme debugging by adding the following to your roller-custom.properties override file.

log4j.category.org.apache.roller.weblogger.business.themes=DEBUG

If you want to share your theme with an even wider audience, then consider contributing it to the Roller Support project, a site that hosts additional themes that are not included in the official Apache Roller release because Roller ships with only four core themes.

That's all

I think that covers all the bases. Let me know if it works for you or what parts of the doc could be improved. I hope to get this into the next rev of the Roller Template Guide (which you can get from the Roller download page in PDF form).

Here's the example1 theme that I discussed in this post:

• example1-theme.tar
• example1-theme.zip