« Blog server as socia... | Main | Off to the mountains »

How to create a Roller 4.0 theme, part 2

This is part two of a two part series:

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

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:

  • - the unique ID, by convention this is the same as directory name
  • - name of the theme
  • - name of theme author
  • - path to image preview file, relative to theme directory

The override

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

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

The