Customizing CLUMP

Creating a new theme

The easiest way to create a new theme is to copy the default theme directory to create the basis for your new theme and edit it till you get what you require.

If using Chrome or FireFox then you switch to your theme by using the following JavaScript code in your browser’s JavaScript console

setTheme('');

To switch back to the default theme enter

setTheme('default');

To switch to your new theme permanently alter lump.js in CLUMP’s html directory and change default in the following line to the name of your new theme’s directory.

var theme="default";

You will also want to change the theme entry in bibGrab in CLUMP’s cgi-bin directory to your new theme by changing ‘default’ in the following line to the directory name of your new theme.

my $THEME="default";

Altering wording

All the wording used by CLUMP is contained in the wordMappings.xml file in the theme’s directory.  The file contains a series of mappings, each mapping has a name and value.  The value contains the text that is displayed on the screen.

Altering the order that metadata is displayed for leaf nodes

The file metadataDisplayOrder.xml contains the order that metadata is displayed for different leaf nodes.  The file consists of a series of displayOrder entries which in turn contain the structuralUnitType and order to display the metadata.  If a metadata entry is not present in the order then it will not be displayed.

Altering how leaf nodes and citations are rendered

The file render.js contains the JavaScript that renders both leaf nodes and citations.  The renderLeafNode and renderCitation functions figure out what functions to call to render the structural unit provided.

Altering colours, borders, etc.

The file screen.css contains the style sheet used by CLUMP.  Google Chrome or Firefox + FireBug will make you life a lot easier for playing with the style sheets.

Altering Images

Each image used by CLUMP is contained in the relevant theme directory. To change the image simple replace the image file in your theme directory with the one you want to use. It is best to make sure that your image file is in the same format (Usually PNG).

Altering Allowed Inline HTML

The HTML that users can insert in their item’s metadata is controlled by the “validHTML.xml” white-list file in the theme.  The format is

<validHTML>
<tag>
<name>a</name>
<attr>
<value>href</value>
<validation>^(http|https)://</validation>
</attr>
<attr>
<value>alt</value>
<validation>[ws]*</validation>
</attr>
<attr>
<value>title</value>
<validation>[ws]*</validation>
</attr>
</tag>
.
.
.
</validHTML>

Every tag element requires a name element.  It can also have any number of attr elements for specifying valid attributes.

Each attr element requires a value element that contains the name of the valid attribute.  It can also have a validation element which contains a JavaScript regular expression that can be used to validate the content of the attribute.  If there is no validation pattern then the attribute will be added without any content (e.g. noshade on a hr tag).

It is important to remember that the allowed HTML is always a white-list.  If the validHTML.xml file doesn’t contain the tag it won’t be shown.  If it contains the tag but no attributes then only the tag will be shown.  If it contains the tag with it’s attributes but no validation for those attributes then the attributes will be included without any value.  This should make it a lot harder for rouge HTML entries in metadata to affect the way an entery is displayed.  It also makes XSS attacks a lot harder to implement.