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.

Introdution

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.

Definitions

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:

	$COEFFICIENT_SRC_DIR/modules

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:

	$COEFFICIENT_SRC_DIR/src/za/org/coefficient/themes

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

	$COEFFICIENT_SRC_DIR/modules

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) 
    	$COEFFICIENT_SRC_DIR/modules/plainWhiteTheme

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

    	$COEFFICIENT_SRC_DIR/modules/myNewTheme
  2. Change the project.name line in the build.properties and build.properties.sample files to reflect this new name: 
    	project.name=MyNewTheme

    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: 
    <application>
	<display-name>MyNewTheme</display-name>
	<description>This is my new theme for Testing</description>
	<module>
		<ejb>MyNewTheme-ejb.jar</ejb>
	</module>
</application>
  4. Change the name of the subdirectory: 
    	$COEFFICIENT_SRC_DIR/modules/myNewTheme/src/za/org/coefficient/themes/plainWhiteTheme

    to

    	$COEFFICIENT_SRC_DIR/modules/myNewTheme/src/za/org/coefficient/themes/myNewTheme
  5. Rename the file: 
    	$COEFFICIENT_SRC_DIR/modules/myNewTheme/src/za/org/coefficient/themes/myNewTheme/PlainWhiteTheme.java

    to

    	$COEFFICIENT_SRC_DIR/modules/myNewTheme/src/za/org/coefficient/themes/myNewTheme/MyNewTheme.java
  6. Edit the file MyNewTheme.java making the following changes:
    1. Change the package identifier to reflect the new package: 
      	package za.org.coefficient.themes.myNewTheme;
    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="za.org.coefficient.interfaces.ThemeIf"
	 *   interface-local-extends="za.org.coefficient.interfaces.ThemeLocalIf"
	 *
	 * @web.resource-env-ref
	 *   name="za/org/coefficient/themes/MyNewTheme"
	 *   type="za.org.coefficient.themes.myNewTheme.MyNewTheme"
	 * @web.resource-env-ref
	 *   name="MyNewTheme"
	 *   type="za.org.coefficient.themes.myNewTheme.MyNewTheme"
	 */
    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: 
      	init("MyNewTheme");
  7. Move into the directory: 
    	$COEFFICIENT_SRC_DIR/modules/myNewTheme/src/za/org/coefficient/themes/myNewTheme/resource

    and make the following changes:

    1. Rename the file 
      	PlainWhiteTheme.properties

      to

      	MyNewTheme.properties
    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
	</FONT>
  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: 
    	$COEFFICIENT_SRC_DIR/modules/myNewTheme

    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.

Properties

The properties file, MyNewTheme.properties, 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:

	ant

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

	TABLEWIDTH=800

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:

	Vote=EAST

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:

	Vote=NULL

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
button
mousedbutton
 Highlight buttons when moused
link1
linkMove1
 Highlight navigation menus when moused
linkgroupheading
linkgroupleft

linkgroupright

linkgroupbottom

linkgrouptopleft

linkgrouptopright

linkgroupbottomleft

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

north.vm

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">
	<CENTER>
	<FONT SIZE="+3">
	My new theme for coefficient
	</FONT>
	</CENTER>
	</TD>
	</TR>

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.

west.vm

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

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

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.

east.vm

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

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

south.vm

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

	<TR>
	<TD COLSPAN="3">
	<CENTER>
	Copy right goes here
	</CENTER>
	</TD>

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.