How to write a theme

Intended audience

This manual is designed for people who are going to write themes for a Coefficient platform. This manual assumes that the author has an installation of Coefficient up and running. It also assumes that the author has a basic understanding of HTML and style sheets.


Coefficient supports different output themes for the presentation layer. This allows Coefficient to have a different "look and feel" with each installation.

Besides having a theme for a given Coefficient installation, each project can also have a theme associated with it. So, for example, a project which has to do with Mexico might have a bright yellow and red theme, whereas a project which has to do with water purity may have a soothing blue and white theme.


The following definitions will be used in this documentation:

$COEFFICIENT_SRC_DIR The directory containing all of the Coefficient source materials including all the modules, ant build scripts, libraries, and Java sources

Java module

All themes for Coefficient are hot-deployable modules. The sources for all the hot-deployable modules can be found in the directory:


Just as a matter of interest, Coefficient comes standard with two themes which are not hot-deployable and always exist. Those two themes, defaultTheme and printerUtilTheme are found in the directory:


Any themes which you wish to write should be placed in the


Getting started

The easiest way to write a new theme is to copy an existing theme and make appropriate changes.

The following steps can be used to make a simple copy of a theme with minor changes. We will talk about major theme changes later.

  1. Copy the entire directory (with its subdirectories)

    to a new directory which has the name of your new theme. For example:

  2. Change the line in the and files to reflect this new name:

    At this time, you should also make any other changes to the properties which are particular to your installation such as the coefficient.path property and the jboss.dir property.

  3. Change the application.xml file to reflect this new name. For example:
    	<description>This is my new theme for Testing</description>
  4. Change the name of the subdirectory:


  5. Rename the file:


  6. Edit the file making the following changes:
    1. Change the package identifier to reflect the new package:
    2. There are 5 xdoclet tags that need to be changed. These are just before the class definition itself. They should look something like:
      	 * @pojo2ejb.class
      	 *   name="MyNewTheme"
      	 *   jndi-prefix="za/org/coefficient/themes/"
      	 *   interface-extends=""
      	 *   interface-local-extends=""
      	 * @web.resource-env-ref
      	 *   name="za/org/coefficient/themes/MyNewTheme"
      	 *   type=""
      	 * @web.resource-env-ref
      	 *   name="MyNewTheme"
      	 *   type=""
    3. Change the class defintion to reflect the new classname:
      	public class MyNewTheme extends theme {
    4. Change the name of the constructor to reflect the new theme name:
      	public MyNewTheme {
    5. Change the call to the init function so that it initialises the correct theme:
  7. Move into the directory:

    and make the following changes:

    1. Rename the file

    2. Modify the file header.vm and change the href to the style sheet to reflect this new theme name:
      	<Link href="images?image=/za/org/coefficient/themes/myNewTheme/resource/styles.css" 
      		rel="stylesheet" type="text/css">
    3. Now just modify the theme a bit by editing the file north.vm and changing the message Welcome to Coefficient to something identifiable:
      	<FONT SIZE="3">
      	This is my new theme for Coefficient
  8. At this stage, you should now be able to compile and install this new theme (although it will still look like the original plain white theme. You can do this by moving into the directory:

    and executing

    	ant clean deploy
  9. At this stage, your new theme should be visible to your running Coefficient installation. Log in as an administrator (the default is user admin with password admin). Select the Change Theme menu option. A list of valid theme will be displayed. Your new theme should be listed at this stage. Click on it and it should become the theme for the installation.

Page Layout

A theme basically consists of 3 rows which consists of the following:

  1. The first row consists of the heading which usually spans entire across the page. This is referred to as the north section.
  2. The second row consists of all the data. It typically has three columns known as west, center and east.
  3. The third row consists of a footer which usually spans the bottom of the entire page. This is referred to as the south section.


The properties file,, gives you some flexibility in defining how large these sections are and which modules are placed in which sections.

There are reasonable defaults for most of the properties on the Theme base class; however, you can define the following:

HEADER The name of the Velocity macro file which defines header information such as the style sheet.
NORTH The name of the Velocity macro file which defines the look and feel of the north section of the screen.
SOUTH The name of the Velocity macro file which defines the look and feel of the south section of the screen.
EAST The name of the Velocity macro file which defines the look and feel of the east section of the screen.
WEST The name of the Velocity macro file which defines the look and feel of the west section of the screen.
WESTPERCENTAGE The horizontal percentage which the west section should take of the screen.
EASTPERCENTAGE The horizontal percentage which the east section should take of the screen.
CENTERPERCENTAGE The horizontal percentage which the center section should take of the screen.
CELLPADING The cellpading used in the center section.
CELLSPACING The cellspacing used in the the center section.

Take some time now to experiment with the percentages. Change the percentages to other values. Ensure that the sum of the percentages is 100%. Recompile and deploy your theme by merely executing:


You can limit the width of the table with an entry such as:


In such a case, the display area of the theme will be limited to that size. The width will not grow or shrink if the user maximises or minimises the browser.

Background colors for the sections can also be indicated.

By default, any module which the theme encounters will be placed in the center position. This can be changed by specifying the module name and its position. For example:


places the voting module in the east section if it exists. If more than one module is placed in the same section, you can optionally specify an order. For example:

	MostActiveDiscussions=WEST, 3

indicates the the MostActiveDiscussions module will be the third item in the west section.

Modules which you want to ignore, can be set to NULL. For example:


will not display that module in this theme.

Style sheets

The style sheet that is used for the theme is indicated in the header.vm file.

	<Link href="images?image=/za/org/coefficient/themes/myNewTheme/resource/styles.css" 
		rel="stylesheet" type="text/css">

This is a normal style sheet. Most of the colour schemes, highlighting, and box enclosures are defined on the style sheet. Of primary interest are the following definitions:

navBlock The top line of navigation blocks
Highlight buttons when moused
Highlight navigation menus when moused






These eight fields are used together to draw a box around a group of information


As mentioned earlier, the entire theme can be considered to have three rows. The north.vm is a Velocity macro file which defines the first row of the table. For example:

	<TR><TD colspan="3">
	<FONT SIZE="+3">
	My new theme for coefficient

In this example, note the colspan entry set to 3. This indicates that west, center and east will each have one data column and that the tile will span over all columns.


The file west.vm is a Velocity macro file which defines the left columns of the presentation. For example:

	<td width="$width" valign="top">

The field $width will be filled in with the WESTPERCENTAGE value from the properties file. It is possible to add more columns to the left area. If that is done, then you will probably want to change the colspan entry in the north.vm file so that the heading spans over all columns.


The file east.vm is a Velocity macro file which defines the right columns of the presentation.

	<td width="$width" valign="top">


The south.vm file defines the last row of the presentation. For example:

	Copy right goes here

It will probably have the same colspan value as in the north.vm file.

Overriding methods

For more advanced features, methods from the base Theme class can be overwritten.

For more examples

For more examples and information on how to do images, refer to the source and resource files for the defaultTheme.