Customizing the Greenstone User Interface

By Allison Zhang
Washington Research Library Consortium
August 2003

This document explains how to customize your Greenstone collection user interface. Before you read this document, you should read the Greenstone Digital Library Developer’s Guide, install the system and build a collection. You should be familiar with the Greenstone structure, terminology, the default user interface, and have basic knowledge and skills on web design and HTML.

Finding the Files You Need to Work On

Working on Different Parts of the User Interface

  1. Title Image
  2. Top Navigation Buttons
  3. Header Images
  4. Navigation Bar Buttons
  5. Document Display

Putting Everything Together

Sample Configuration and Macro Files

Finding the Files You Need to Work On

In order to change the look and feel of the Greenstone user interface, you need to work on the following files:

·         Collect.cfg

This is the collection configuration file. You can find this file in the “etc” directory. Details about how to create this file can be found in the Developer’s Guide, “1.5 Collection configuration file” and “2.3 Formatting Greenstone output”.

·         Macro files

Macro files have an extension dm.  All macro files are stored in the “macros” directory. Details about how to create macros and macro files can be found in the Developer’s Guide “2.4 Controlling the Greenstone user interface”.

Each macro file defines one or more packages. Each package contains a series macros. A macro can be specified for a particular collection with [c=collection name], which will overwrite the default macro.  It is very important to define or create new macros in the correct package. For example, I created a new macro “imagecollect” for the “fenian” collection and I wanted it to work on all display screens. So I put this macro in the Global package.

package Global

_imagecollect_[c=fenian] {_gsimage_(_httppagecollect_,_httpiconccollectof_,_httpiconccollecton_,collect,_textimagecollect_)}

 Here is a list of the available packages and their roles. (The package names are case sensitive.)

Package Name

File Name

Roles

package Global

base.dm
english.dm

Contains macros that work for all display screens, if the [c=collection name] is not specified.

Package Style

style.dm

Controls the display style for all pages, if the [c=collection name] is not specified.

Package document

english.dm
document.dm

Contains macros for the document display.

Package query

query.dm
english.dm

Contains macros for the Search page display.

Package preferences

pref.dm
english.dm

Contains macros for the Preferences page display.

Package help

help.dm
english.dm

Contains macros for the Help page display.

Package about

about.dm
english.dm

Contains macros for the About page display.

Package browse

browse.dm
english.dm

Contains macros for the dynamic browsing interface.

·         Image files

All images files can be found in the “gsdl/images” directory.

·         Main.cfg

This file contains a list of all macro files you use for the user interface. If you created a new dm file, you need to add it to this file. The main.cfg file is stored in the "gsdl/etc/" directory.

Working on Different Parts of the User Interface

The Greenstone user interface is consisted of five parts as illustrated in Figure 1. To make changes in different part, you need to work on different files. Click on the part you want to change and learn how to do it.

 Figure 1

1. Title Image

You define the title image in the collect.cfg file, iconcollection using the following format:

iconcollection    "_httpprefix_/path to your image/image file name"

For example:

"_httpprefix_/collect/auhist/images/auhist.gif"

_httpprefix_ is the web address of the directory that Greenstone is installed in. You can use any image formats that can be displayed on the web, such as .gif, jpg, etc.

2. Top Navigation Buttons

2.1 Layout

The layout of the top navigation buttons is controlled by a macro called _javalinks_, which is defined in the package Global in the base.dm file.

_javalinks_ {_imagehome__imagehelp__imagepref_}

This macro displays three buttons HOME, HELP, and PREFERENCE horizontally on the top as showed in Figure 1.

The position of the buttons is controlled by the page layout macro _pagebanner_ in the macro file style.dm. To change the position of the buttons, you need to change the table layout in the _pagebanner_ macro. For example, the following Table displays the navigation buttons on the right of the header as illustrated in Figure 2.

_pagebanner_
{<!-- page banner (\_style:pagebanner\_) -->
<center>
<table width=_pagewidth_ cellspacing=0 cellpadding=0 border=0>
<tr>
<td colspan=3 height=6>
</td>
</tr>
<tr> 
<td width=373 valign=top height=106 align=right border=0>_imagecollection_</td> 
<td width=132 valign=top height=106 align=left border=0>_imagethispage_</td>   
<td width=90 valign=top height=106 align=right border=0>_javalinks_</td> 
</tr> 
<tr>          
<td colspan=3>_pagebannerextra_</td> 
</tr>
</table>
</center>
<!-- end of page banner -->}

Figure 2

Figure 2

This part of navigation buttons is very flexible. You can change the position of the buttons, add new buttons, delete buttons, or do not display them at all.

To add a new button, do the following:

1)      Create a new image macro in the package Global in the base.dm file, following the same format as the other image macros. For example,

_imagecollect_ {_gsimage_(_httppagecollect_,_httpiconccollectof_,_httpiconccollecton_,collect,_textimagecollect_)}

2)      Create a new httppage macro in the package Global in the base.dm file. This is the URL to open when the button is clicked. For example,

_httppagecollect_ [c=auhist] {http://www.aladin.wrlc.org/dl/}

3)       Create new httpicon macros, which define the locations of the images, in the package Global in the english.dm file as explained in the next section.

4)      Create a new text macro for the button. This is the “alt” text in the <img> tag for the button. For example,

_textimagecollect_ [c=auhist] {WRLC Special Collections}

5)      Create the images and put the images in the “images” directory.

6)      Add the image macro to the _javalinks_ macro, for example,

_javalinks_ {_imagehelp_<br>_imagehome_<Br>_imagecollect_}

This macro displays three buttons vertically with a break line in between as illustrated in Figure 2.

2.2 Image Locations

The location macros for the images of the top navigation buttons are defined in the package Global in the english.dm file, under icons. All these macros start with _httpicon followed by a “c” and the button name. I call the buttons as “C buttons”.Each button is made of a pair of images,  “on” image and “off” image, which can be different colors. When you point your cursor on the button, you will see the color change effect. To change the look of the buttons, you need to make two images.

## "HOME" ## top_nav_button ## chome ##
_httpiconchomeof_ {_httpimg_/chomeof.gif}
_httpiconchomeon_ {_httpimg_/chomeon.gif

## "HELP" ## top_nav_button ## chelp ##
_httpiconchelpof_ {_httpimg_/chelpof.gif}
_httpiconchelpon_ {_httpimg_/chelpon.gif}

To put the images in a directory other than the default directory in /gsdl/images/, you need to put the path in the curly brackets. 

# Collections 
_httpiconccollectof_ {_httpprefix_/collect/auhist/images/ccollectof.gif}
_httpiconccollecton_ {_httpprefix_/collect/auhist/images/ccollecton.gif}

3. Header Images  

The header image is controlled by a macro called _imagethispage_. You put this macro in the packages you want to display the header images. For example, you want to display a header for the Help page,

package help

_imagethispage_ [c=auhist] {_iconthispage_}_iconthispage_ [c=auhist] {<img src="_httpiconhhelp_" alt="_textHelp_" width=_widthhhelp_ height=_heighthhelp_>}

When you define the _imagethispage_, you also need to define _iconthispage_. These macros are default macros that are already in the dm files. There is no default header image for the document display pages. I modified the _imagethispage_  macro in the document package to display a Description header in the content page.

_imagethispage_ [c=auhist] {_If_("_iconthispage_" ne "", <img src= "_httpprefix_/collect/auhist/images/\h_desc.gif">,_iconthispage_)

The locations of the header images are defined in package document, icons. All these macros start with _httpicon followed by  “h_” and the button name.  I call them the “H images”. You name your H images as h_imagename. For example, h_title.gif, h_subj.gif, etc.

## "titles a-z" ## green_title ## h_title #
_httpiconhtitle_ {_httpimg_/h\_title.gif}
_widthhtitle_ {200}
_heighthtitle_ {57}

The width and the height are the number of pixels. You can change them if you changed the width and height of the image.

 To change the location of an image, you need to change the path to the image in the curly brackets.

# Title header
_httpiconhtitle_ {_httpprefix_/collect/auhist/images/h\_title.gif}
_widthhtitle_ {132}
_heighthtitle_ {106}

To change the look of the header images, you open an image in PhotoShop or a graphic editor, make the change, and save it with the same file name.

4.      Navigation Bar Buttons

4.1  Turn on the buttons

The buttons on the navigation bar, except the Search button, are controlled by the classifiers defined in the collect.cfg file. When you define a classifier in the collect.cfg file, the corresponding button will appear on the navigation bar. For example, the following classifiers will turn on the Title and the Subject buttons.

classify AZList -metadata Title
classify AZCompactList -mingroup 1 -metadata DC.Subject -buttonname Subject

The buttons are defined in the package Global, usually in the base.dm file. For example,

_imageTitle_ {_gsimage_(_httpbrowseTitle_,_httpiconttitlof_,_httpiconttitlon_,titles,_textimageTitle_)}
_imageCreator_ {_gsimage_(_httpbrowseCreator_,_httpicontauthof_,_httpicontauthon_,authors,_textimageCreator_)}

4.2 Locations of the images

The locations of the images are defined in the macros in the package Global, usually in the english.dm file.  All these macros start with _httpicon and followed by a “t” and the button name. I call them the “T buttons”.

A button on the navigation bar is made of three images, the “off” image, the “on” image, and the “gr” image. If you want to change the look of the buttons, you need to make three images.

## "titles AZ" ## nav_bar_button ## ttitl ##
_httpiconttitlgr_ {_httpimg_/ttitlgr.gif}
_httpiconttitlof_ {_httpimg_/ttitlof.gif}
_httpiconttitlon_ {_httpimg_/ttitlon.gif}
_widthttitlx_ {87}

## "authors AZ" ## nav_bar_button ## tauth ##
_httpicontauthgr_ {_httpimg_/tauthgr.gif}
_httpicontauthof_ {_httpimg_/tauthof.gif}
_httpicontauthon_ {_httpimg_/tauthon.gif}
_widthtauthx_ {110}

You also need to change the look of the space image put between the buttons. This space image is called “tspace.gif” and is defined in the package Global in the base.dm file

_httpicontspace_ {_httpimg_/tspace.gif}
_heighttspace_ {17}

The width of the images is the number of pixels. If you have a long text, say “Place Names”, and the button is wider than the other buttons, you put the width pixels in the curly brackets. When you build the collection, Greenstone will automatically calculate the spaces between the buttons and the tspace.gif will fill up the spaces.

4.3 Add New Buttons

There are two ways to add a new button: 1) use an existing button name and change the text on the images; 2) create new macros for the new button and create new button images.

4.3.1        Use an existing button name for a new button

For example, you need a button called “Places” and you decided to use an existing button called “From” for this new button.  Here is what you need to do:

·        Define a classifier in the collect.cfg file. You have to create a classifier for a new button. This is not as flexible as creating the top navigation buttons.

Classify AZCompactList -mingroup 1 -metadata DC.Coverage.spatial -buttonname From

·        In PhotoShop or a graphic editor, change the text “From” to “Places” on all three tfrom images, may be in different colors, and put them in the images directory.

tfromgr.gi
tfromof.gif
tfromon.gif

4.3.2        Created new macros for a new button

For example, you want to create a new button called “Museums”. Here is what you need to do. 

·        Create a classifier in the collect.cfg file

classify AZCompactList -mingroup 1 -metadata Museums -buttonname Museums

·        Create a new image macro in the package Global using the same format as the other image macros:

_imagemuseum_ {_gsimage_(_httpbrowseMuseum_,_httpicontMuseumof_,_httpicontMuseumon_,Museums,_textimageMuseum_)}

·        Define the locations of the images and the width of the images

# Museum
_httpicontmuseumgr_  {_httpprefix_/collect/auhist/images/tmuseumgr.gif}
_httpicontmuseumof_ {_httpprefix_/collect/auhist/images/tmuseumof.gif}
_httpicontmuseumon_ {_httpprefix_/collect/auhist/images/tmuseumon.gif}
_widthtmuseumsx_  {110}

·         Create three images and save them in the “images” directory.

5. Document Display

There are two kinds of document displays. They are controlled by the collect.cfg file.

5.1  The CL list display

The browse list display is controlled by the Format strings in the collect.cfg file. For example, the following format string displays the Title list, which is the first classifier, with a thumbnail and brief description, as illustrated in Figure 3.

Format CL1VList
‘<td valign=top align=center width=150>[ImageHTML]</td>
<td width=10> </td>
<td align=left valign=top>
<table border=0 width=435 cellpadding=2 cellspacing=0>
<tr><td width=100 align=left valign=top><b>Title:</b></td>
<td width=335 align=left valign=top>[link]<b>[Title]</b>[/link]</td></tr>
<tr><td width=100 align=left valign=top><b>Date:</b></td>
{If}{[DC.Date.text], <td width=335 align=left valign=top>[DC.Date.text]</td>,<td valigh=top>[DC.Date.created]</td>}</tr>
</table>
</td></tr>
<tr><td colspan=3><hr align=center size=1 noshade></td></tr>’

Figure 3

5.2  The document display

When you click on a title on the Title list, you see either a full-text page or a metadata record describing the digital object. The display of this page is controlled by Format DocumentHeading  and Format  DocumentText in the collect.cfg file.

Here is an example of the collect.cfg file that displays the result as illustrated in Figure 4.

Figure 4

Putting Everything Together

If you work with only one collection and you want the header graphics and the buttons look different from the default Greenstone design, you can simply edit the image files in a graphic editor. All images files are stored in the “images” directory. It is not hard to find the image you want to edit. As I mentioned before, the top navigation button image names all start with “c”, for example, chelpof.gif, chelpon.gif, etc. All files for the header images, the “H images”, start with “h_”, for example, h_subj.gif, h_title.gif, etc. And all files for the navigation bar images start with a “t”, for example, tsubjon.gif, tsubjof.gif, tsubjfr.gif, etc. Save the edited images with the same file names and you will see the changes right away.

If you work with multiple collections and you want personalize each collection with different flavors, you will need to do some work. Here are my suggestions.

·         Create a collection specified macro file and name it with the short collection name, for example, my collection short name is fenian, I would name this macro file as fenian.dm.

·         Put all macros you need to modify and all new macros you created in this file under different packages as instructed in the Developer’s Guide.

·         Specify each macro for this particular collection, for example,

# Search
_httpicontsrchgr_ [c=fenian] {_httpprefix_/collect/auhist/images/tsrchgr.gif}
_httpicontsrchof_ [c=fenian] {_httpprefix_/collect/auhist/images/tsrchof.gif}
_httpicontsrchon_ [c=fenian] {_httpprefix_/collect/auhist/images/tsrchon.gif}
_widthtsrchx_ [c=auhist] {74}

The macros with [c=collection name] will overwrite the default macros. In this way, you can have different designs for different collections, as what we have done with the WRLC Digital Collection, but not mess up with the default macros. When you create another collection, you can simply do a global change to replace the collection name with the new collection name. Here is an example of a macro file for the American University History Photographs Collection: auhist.dm file.

·         Put the collection specified images in a directory other than the default image directory in /GSDL/images/.

·         Add the new macro file to the main.cfg file.

·         Design your metadata carefully. Good metadata design helps a lot in good user interface display.

·         Create a mockup image in PhotoShop and cut it into parts for your need. Always keep the original psd file with layers for easy edit in the future.

Sample Configuration and Macro Files

File Name

 

View Collection

collect.cfg auhist.dm American University History Photograph and Print Collection
collect.cfg grant.dm Felix E. Grant Collection
View all WRLC Libraries Digital and Special Collections