Greenstone tutorial exercise

Back to wiki
Back to index
Sample files: custom.zip
Devised for Greenstone version: 2.70
Modified for Greenstone version: 2.70w

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, images, and CSS stylesheets, both of which reside in Greenstone → images.

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, home.dm, query.dm, document.dm, while others contain macros for many packages. base.dm contains macros used globally, style.dm controls the common style of each page, english.dm, french.dm and other language files contain the text fragments for the entire interface, in that specific 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 → images → style.css.

In this exercise, we customize the macros, images and stylesheets to change the appearance of our library. You will not need the Librarian Interface for this exercise.

Changing the background and header images

  1. Three new images for this exercise can be found in sample_files → custom. Copy chalk-blue.gif, gsdlhead-blue.gif and divb-blue.gif from the custom folder into the Greenstone → images folder.

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

    Save home.dm and close the file.

  1. Open the file Greenstone → macros → style.dm with the same program. 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"); \}

    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"); \}*/
    body.bgimage \{ background-image: url("_httpimg_/chalk-blue.gif"); \}

    /*...*/ around a line signals a comment, and this style element will be ignored. We use this to "comment out" the original line and replace it with a modified line. This way it is easy to revert back to the original if necessary. Here we are changing the background image for the bgimage section of the body of the page to chalk-blue.gif.

    Save style.dm and close the file.

  1. Preview the home page in a web browser. (On Windows, restart the Greenstone library server.) The page header and background should now use the new graphics, and be blue.

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

Changing the colour of the navigation bar, page title and page text

Now that the background image is a nice blue colour, lets format the page so that some other parts are blue too. Preview the collection after each change to make sure that it has worked properly. On Windows, macro file changes require a restart of the Greenstone library server. Stylesheet changes may require a force reload in the web browser.

  1. First, we'll change the colour of the navigation bar and green divider bars. These use an image as a background, specified in the same macro as the page background.

    Open Greenstone → macros → style.dm in a text editor, and find the _cssheader_ macro that you modified previously. Change the div.navbar and div.divbar parts to use divb-blue.gif instead of bg_green.png:

    /*div.navbar \{ background-image: url("_httpimg_/bg_green.png"); \}*/
    div.navbar \{ background-image: url("_httpimg_/divb-blue.gif"); \}
    /*div.divbar \{ background-image: url("_httpimg_/bg_green.png"); \}*/
    div.divbar \{ background-image: url("_httpimg_/divb-blue.gif"); \}

  1. The selected item on the navigation bar uses the same background, so change that too:

    /*a.navlink_sel \{ background-image: url("_httpimg_/bg_green.png"); \}*/
    a.navlink_sel \{ background-image: url("_httpimg_/divb-blue.gif"); \}

  1. Next, we get rid of the background green image on the page and collection titles. Comment out the p.bannertitle and p.collectiontitle parts:

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

The above style definitions were included in the macro file so that image paths could be dynamically generated. The majority of the style definitions reside in an external style file, Greenstone → images → style.css, and most style changes involve modifying that file.

  1. Open Greenstone → images → style.css in a text editor. Make the following modifications. You might want to preview after each one to see the effect.

    Change some of the colours:

  1. For fun, lets 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.

Adding a footer

  1. Next we add a footer to each page. Greenstone → macros → style.dm defines a header and footer for each page, and macro files for the different pages define the page content. Open the file Greenstone → macros → style.dm in a text editor.

  1. Locate the _footer_ macro:

    _footer_ {
    <!-- page footer (\_style:footer\_) -->
    _pagefooterextra__endspacer__htmlfooter_
    }

    After _pagefooterextra_ add some text or HTML. For example <center><small>Copyright 2006 My Awesome Digital Library</small></center>. The resulting macro will look something like:

    _footer_ {
    <!-- page footer (\_style:footer\_) -->
    _pagefooterextra_ <center><small>Copyright 2006 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.

    Save style.dm and close the file.

  1. Preview the changes in a web browser. (On Windows, restart the Greenstone library server.) Each page should now have the new text at the bottom.

  1. Adding text into the main _footer_ macro adds it to all pages. To add a footer just to a particular page, use _pagefooterextra_ in the appropriate macro file. For example, lets add some more text to the footer, this time just on the home page

    Open the file Greenstone → macros → home.dm in a text editor. After the line package home, add the following text:

    _pagefooterextra_ {Collections generated by Me.}

    Save home.dm and close the file.

    Preview the home page in a web browser. (On Windows, restart the Greenstone library server.) The home page should now display the new text, while the other pages won't.

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 a predefined alternative to the home page.

  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 tip.dm style.dm base.dm query.dm help.dm pref.dm about.dm \
               document.dm browse.dm status.dm authen.dm users.dm html.dm \
               extlink.dm gsdl.dm extra.dm home.dm collect.dm docs.dm \
               bsummary.dm gti.dm gli.dm nav_css.dm \
               english.dm english2.dm french.dm french2.dm spanish.dm \
               spanish2.dm russian.dm russian2.dm usability.dm

    Change the text home.dm to yourhome.dm. Save and close the file.

  1. Preview the newly structured home page in a web browser. (On Windows, restart the Greenstone library server.)

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

Collection specific customisation

Macros can also be used to customize single collections. They should be added to a file called extra.dm 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.

  1. Create a new macros folder for the collection: Greenstone → collect → reports → macros. Copy the file Greenstone → macros → extra.dm into the new folder.

  1. First, we change the title of the About this collection section of the about page. Add the following text to the extra.dm file:

    package about

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

    Save the file.

    Preview the collection. (On Windows, restart the Greenstone library server.) The about page will have a new title underneath the search form.

  1. Next we'll do some style customisations for this collection. Add the following text to extra.dm:

    package Style

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

    Preview the collection. (On Windows, restart the Greenstone library server.) 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 extra.dm 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 to extra.dm after the last modifications:

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

    Copy the file sample_files → custom → style-blue.css into the collection's images folder: Greenstone → collect → reports → images (you may need to create this folder).

    Preview the collection; it should look radically different.

How to determine which images to replace (advanced)

  1. In the first part 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 "gsdlhead-blue.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 left hand green (or blue) swirly bar. This time choose "Save background as" to find the name: "chalk.gif" (or "new_background.gif"), then click Cancel.

  1. 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, search the macro files for the image names using the find 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.

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

    To search the macro files for "gsdlhead.gif" type

    find "gsdlhead.gif" "C:\Program Files\Greenstone\macros\*.dm"

    *.dm means all files ending in .dm. A list of all macro files will be displayed, along with any matches. You will see that home.dm and exported_home.dm both contain gsdlhead.gif. home.dm in the one you want to edit—exported_home.dm is used for the home page when you export a collection to CD-ROM.

    Do the same thing for "chalk.gif":

    find "chalk.gif" "C:\Program Files\Greenstone\macros\*.dm"

    base.dm is the only file that mentions this image.

    Close the command prompt.