Greenstone tutorial exercise

Back to wiki
Back to index
Sample files:
Devised for Greenstone version: 2.70
Modified for Greenstone version: 2.87

Customization: macro files and stylesheets

The appearance of all pages produced by Greenstone is governed by macro files, which reside in the folder Greenstone → macros, and images and CSS stylesheets reside in Greenstone → web → style.

A macro takes the form _macroname_ {macro value}. Macro names start and end with underscores (_), and the macro value is enclosed in curly brackets ({}). Macro values can be text or HTML, and can include other macros.

Macros are grouped into packages, and different packages control the appearance of different pages. For example, the home, help, preferences, query, document packages control the home, help, preferences, query, and document pages, respectively. Some macro files contain macros for just one package, for example,,,, while others contain macros for many packages. contains macros used globally, controls the common style of each page,, and other language files contain the text fragments for the entire interface, in that language.

The output of the library program is a page of HTML which is viewed in a web browser. CSS (Cascading Style Sheets) are often used alongside HTML pages to control the formatting, such as layout, colour, font etc. The default Greenstone stylesheet is Greenstone → web → style → style.css.

In this exercise, we customize the macros, images and stylesheets to change the appearance of our library.

Collection specific customisation

Macros can be used to customize single collections by adding them to a file called in the macros directory of a collection.

We use the Word and PDF collection (from exercise A collection of Word and PDF files) as the example for this exercise, but it can be done with any collection. Open up this collection (reports) in the Librarian Interface.

  1. Go to the Format panel, and select Collection Specific Macros from the left hand list. This section allows you to edit the collection's macro file.

  1. First, we change the title of the About this collection section of the about page. Add the following text in the edit box (which can be copied from the file about_tweak.txt in the sample_files → custom folder):

    package about

    _textabout_ {
    <div class="section">
    <h3>Very Interesting Reports Collection.</h3>

    Preview the collection by pressing the <Preview Collection> button. The About page will have a new title underneath the search form.

  1. Next we add a footer to each page. Add the _footer_ macro to the end of the edit box (which can be copied from the file footer_tweak.txt in the sample_files → custom folder):

    package Style

    _footer_ {
    _pagefooterextra_ <center><small>Copyright 2010 My Awesome Digital Library</small></center> _endspacer__htmlfooter_

    The <center> and <small> HTML tags center the text, and make it a smaller size than the rest of the page.

  1. Preview the changes in a web browser. Each page should now have the new text at the bottom.

  1. Putting text in the main _footer_ macro adds it to all pages of this collection. To add a footer just to a particular page, use _pagefooterextra_ in the appropriate package. For example, lets add some more text to the footer, this time just on the About page.

    Add the following text immediately after the line package about :

    _pagefooterextra_ {Collection generated by Me.}

    Preview the About page in a web browser. The About page should now display the new text, while the other pages won't.

  1. Next we'll do some style customisations. Add the following text below the _footer_ macro (which can be copied from the file red_tweak.txt in the sample_files → custom folder)

    _collectionspecificstyle_ {
    <style type="text/css">
    /*clear the use of a background image */
    body.bgimage \{ background-image: none; \}
    /* set the background color to pink */
    body.bgimage \{ background: pink; \}
    /* clear the background image for the navigation bar, and set its color to red */
    div.navbar \{ background-image: none; background-color: red; \}
    a.navlink \{ background-image: none; background-color: red; \}
    /* clear the background image for the divider bars, and set their color to red */
    div.divbar \{ background-image: none; background-color: red; \}

    /*...*/ around a line signals a comment, and this style element will be ignored.

    Preview the collection. The reports collection will now have a pink background, and the navigation bar and divider bars will be red. These changes will only affect this collection.

Any macros from the general macro files can be copied into a collection's file and modified. Remember to include the package declaration to make sure that the macros get applied to the correct page(s).

The style modifications made above were minor. The collection still uses the majority of the standard style file. The style declarations in the _collectionspecificstyle_ macro get appended to the default ones. To completely change the appearance of a collection, we can use a new style sheet altogether.

  1. Add the following text (which can be copied from the file css_tweak.txt in the sample_files → custom folder) after the last modifications:

    _cssheader_ {
    <link rel="stylesheet" href="_httpcstyle_/style-blue.css" type="text/css"
      title="Blue Style" charset="UTF-8">

    Outside of the Librarian Interface, locate the collection folder Greenstone → collect → reports. Create a style folder inside this (if not already present), and copy the file sample_files → custom → style-blue.css into this folder.

    Preview the collection; the about page should look radically different. (If not, try restarting the Greenstone server and preview again.)

Changing the colour of the page title and page text

In the previous exercises we changed a single collection. Now we change all the pages in our Greenstone installation by modifying style and macro files outside the Librarian Interface. First, we format the page so that some other parts are blue. Preview any collection after each change to make sure that it has worked properly. On Windows, macro file changes may require a restart of the Greenstone local library server. Stylesheet changes may require a forced reload in the web browser.

Note, use any collection except the reports collection to preview the following changes. Because the reports collection has been modified to use its own custom stylesheet, changes to the main stylesheet won't have any effect on it.

  1. The majority of the style definitions reside in an external style file, Greenstone → web → style → style.css, and most style changes involve modifying that file. Open the style.css file in a text editor, e.g. WordPad (and save a .backup copy). Make the following modifications. You might want to preview after each one to see the effect.

    Change some of the colours:

    Preview the collection. You may need to force the browser to reload the page to see the changes in effect, or else may need to restart the Greenstone server. Now text in the page body is a light green color (teal), and the font of the collection title has changed from black to blue.

(If a collection title image is used, you won't see the change on the collection title.)
  1. Let's switch the positions of the HOME, HELP and PREFERENCES buttons and the collection name or image.

    The look of your library should now be substantially different. The HELP, HOME and PREFERENCES buttons are in the left upper corner whereas the collection title is switched to the right of the page. You will notice that the green boxes are now near the middle of the page. These are set in the file, and will be removed in Step 12.

  1. Now we will customize the default Greenstone header image and the background image. Two new images for this exercise can be found in sample_files → custom. Copy newbgimg.gif, newheadimg.gif from the custom folder into the Greenstone → web → images folder.

  1. Open the file Greenstone → macros → in a text editor. Find each occurrence of gsdlhead.gif in this file (there are two) and replace with newheadimg.gif. (If you are using WordPad, you can use Edit → Find to search for the text.)

    Save and close the file.

  1. Open the file Greenstone → macros → with the text editor. Locate the following part of the file (this is part of the _cssheader_ macro):

    <style type="text/css">
    body.bgimage \{ background-image: url("_httpimg_/chalk.gif"); scroll repeat-y left top; \}

    Use copy and paste on the body.bgimage line to make it look like this:

    <style type="text/css">
    /*body.bgimage \{ background-image: url("_httpimg_/chalk.gif"); scroll repeat-y left top; \}*/
    body.bgimage \{ background-image: url("_httpimg_/newbgimg.gif"); scroll repeat-y left top; \}

    Here we are changing the background image for the bgimage section of the body of the page to newbgimg.gif.

    Near the bottom of the _cssheader_ macro, you will see these lines, which set the two green boxes mentioned in Step 9:

    p.bannertitle \{background-image: url("_httpimages_/banner_bg.png"); \}
    p.collectiontitle \{background-image: url("_httpimages_/banner_bg.png"); \}

    Since we don't want these to appear anymore, we will simply comment out these lines like this:

    /*p.bannertitle \{background-image: url("_httpimages_/banner_bg.png"); \}
    p.collectiontitle \{background-image: url("_httpimages_/banner_bg.png"); \}*/

    Save and close the file.

  1. Preview the home page in a web browser. On Windows, if forcing the browser to reload the pages does not show the changes in effect, restart the Greenstone library server before reloading the pages in the browser. On unix systems, you may need to reload pages in order to see the changes take effect, as the browser may at first display cached versions of pages you'd already visited earlier. The header of the home page, and the background of every page of each collection (except reports, which uses a custom _cssheader_ macro) should now use the new graphics, and the green box background images are no longer present on the collection pages.

Make your own Greenstone home page

You can make radical changes to a page by changing the macro file completely. For example, here we use an alternative to the home page which we have prepared for you in advance and included in your Greenstone installation.

  1. Open the file Greenstone → etc → main.cfg in a text editor. Locate the macrofiles list:

    # The list of display macro files used by this receptionist
    macrofiles \

    Change the text to Save and close the file.

  1. Preview the newly structured home page in a web browser. (On Windows, force reload the browser or else restart the Greenstone library server before reloading the pages in the browser.) Look at the file macros/ in a text editor to see how these changes are expressed.

  1. Reverse this last change by changing back to in the file Greenstone → etc → main.cfg. You may also like to reverse the other changes you have made.

    The final part of this exercise looks at how we determined which images needed replacing, and which macro files should be edited.

How to determine which images to replace (advanced)

  1. In step 10 of this exercise we replaced the default background (chalk.gif) and header (gsdlhead.gif) images with new ones. To do this we needed to change the image names in the macro files. How did we know which images we were replacing and which macro files to edit? This exercise shows you how to find out.

  1. To find out the names of the images to replace, go to the home page of your digital library in a browser. Right-click on the header image ("Greenstone digital library software") and select "Save picture as". A dialog will pop up and will display the image name: gsdlhead.gif (or newheadimg.gif if you are using the new header). Click Cancel to close the dialog—you don't need to save the images. Do the same for the background image by right clicking on the green (or blue or orange) swirly bar to the left. This time choose "Save background as" to find the name: chalk.gif (or newbgimg.gif), then click Cancel.

    These instructions apply to Internet Explorer. Other browsers may have other options in the right-click menu. For example, Mozilla provides "View Image" and "View Background Image" options. Using these options will put the path to the image in the browser address box, and the name can be seen from this.

  1. Once you have identified the names of the images to be replaced, you need to find out where they occur in the macro files. To do this on Windows, you would search the macro files for the image names using the findstr program, which is run in a command prompt. Open a command prompt using Start → Programs → Accessories → Command Prompt, or Start → Run and enter cmd as the name of the program to run. If your Windows doesn't have a conventional Start menu, then press Ctrl+r to launch the Windows Run dialog, then type cmd.

    You can type findstr /? to see a description of the program and its arguments.

    To search the macro files for gsdlhead.gif type

    findstr /s /m /C:"gsdlhead.gif" "C:\Program Files\Greenstone\macros\*.dm"

    *.dm means all files ending in .dm (while /s tells it to search within subfolders and /m lists the files that matched). A list of all applicable macro files will be displayed, along with any matches. You will see that and both contain gsdlhead.gif. is the one you want to edit— is used for the home page when you export a collection to CD-ROM. On Linux systems, the equivalent command to run in a terminal would be:

    fgrep -rl "gsdlhead.gif" /full/path/to/your/greenstone/macros/

    Do the same thing for chalk.gif:

    findstr /s /m /C:"chalk.gif" "C:\Program Files\Greenstone\macros\*.dm" and are the only files that mention this image.

    Close the command prompt.

Copyright © 2005-2016 by the New Zealand Digital Library Project at the University of Waikato, New Zealand
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”