Dave Johnson on open web technologies, social software and Java
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.
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:
Following the theme meta-data is the stylesheet declaration, including all of the required 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:
And here are the elements that must be included in a :
After the template elements, we include the one
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.
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.
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:
This is just one entry in the weblog Blogging Roller. You may want to visit the main page of the weblog
Below are the most recent entries in the category Roller, some may be related to this entry.