Proposal: Theme XML Descriptor

(proposals should start with name Proposal)

Abstract

This is a proposal to create an xml based descriptor file for weblog themes starting in Roller 4.0.

Why a theme descriptor? A theme descriptor simply provides a more structured way of describing information about a packaged theme so we don't have to rely on implied conventions or hacks such as the use of Weblog.vm to represent the main weblog template. A theme descriptor also provides the additional ability to support some features of themes which currently are not possible, such as defining a custom template page with a specific link value.

Requirements

• Nothing really required per se, just that we don't break any existing theme functionality.

Design

<!-- weblog theme, name is required -->
<weblogtheme>
        <id>brushedmetal</id>
        <name>Brushed Metal</name>
        <author>Bryan Bell</author>

	<!-- theme preview image, required -->
	<preview-image path="theme-preview.jpg" />

	<!-- 1 or more templates, "weblog" is required -->
	<template action="weblog|custom">
		<name></name>
		<description></description>
		<link></link>
		<navbar>true/false</navbar>
		<hidden>true/false</hidden>
		<templateLanguage>velocity</templateLanguage>
                <contentType>text/html</contentType>
		<contentsFile>foo.vm</contentsFile>
	</template>

	<!-- 0 or more resources -->
	<resource path="my-image.jpg" />
	<resource path="styles/foo.css" />

</weblogtheme>

Theme names are no longer limited to short directory path style names, they can be given longer and more natural names now that they aren't read off the filesystem. All themes are required to have a name and the name will only be restricted to some reasonable character limit, such as 64 or 128?

All themes will be required to provide a preview image which is defined via a path to an image inside of the theme directory. Preview images will be used as the preview for theme selection when creating a new weblog and will not be copied to a weblog's resources folder when theme customization happens.

Themes may define 1 or more templates, and a "weblog" template is required. Each template is required to define a value for action, name, navbar, hidden, templateLanguage, and contentsFile. Optional attributes are description and link, which will be null if unset.

Themes may define 0 or more resources which can be any static resource such as images, css stylesheets, javascript, or anything else the theme may require. Each resource of a theme is copied to the same path in a users uploads directory when theme customization happens. NOTE: theme resources will be validated to ensure that themes are not allowed to specify paths to resources deeper than 1 folder, which is not supported by Roller.

Issues

Issues to be considered ...

Comments

Please comment on the Roller-dev mailing list.