Greenstone tutorial exercise

Back to wiki
Back to index
Sample files:
Devised for Greenstone version: 3.06
Modified for Greenstone version: 3.10

Customizing your home page

This tutorial demonstrates how to change the home page of your Greenstone3 installation, including how to use XSL to add certain features (like an up-to-date list of collections and the cross-collection search box).

  1. Start up your Greenstone server (Start → All Programs → Greenstone3.10 → Greenstone3 Server) and click the Enter Library button. This will take you to your library home page, which we will be replacing with our custom home page.

Changing the library's home page

  1. By default, the library's home page is dictated by the home.xsl file in Greenstone3 → web → interfaces → default → transform → pages. We want to be able to easily revert back to the default home page, so we won't make changes to this file directly. Instead, we're going to tell the interface to use a new, different file to create the home page.

    To do this, open the interfaceConfig.xml file found in Greenstone3 → web → interfaces → default in a text editor, and change:

    <subaction name="home" xslt="pages/home.xsl"/>

    To this:

    <subaction name="home" xslt="pages/home-tutorial.xsl"/>

  1. Restart the server by clicking the Restart Library button in the small Greenstone Server window. (Any time you make changes to an interfaceConfig.xml file, you must restart the server for the changes to take effect.) When the server restarts, look at your home page again. Because home-tutorial.xsl does not yet exist, you should see:

    Couldn't find and/or load the stylesheet "pages/home-tutorial.xsl" for a=p, sa=home, in collection.

  1. Copy the folder tutorialbliss from sample_files → custom to Greenstone3 → web → interfaces → default → style → themes. This is a free CSS template that our new home page will use.

  1. Copy home-tutorial.xsl from sample_files → custom to Greenstone3 → web → interfaces → default → transform → pages. It contains the following text:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <xsl:stylesheet version="1.0"
    extension-element-prefixes="java util"
    exclude-result-prefixes="java util">

    <xsl:template match="/">
    <meta name="keywords" content="" />
    <meta name="description" content="" />
    <title>My Greenstone Library</title>


    <div id="footer">
    <p>2013 | Photo by <a href="">Leagoon</a> | Design by <a href="" rel="nofollow"></a>.</p>
    <!-- end #footer -->


  1. Refresh you library home page. You should now have a nice, new home page. Basically, the entire contents of the file index.html in sample_files → custom → tutorialbliss were copied (after some modifications) in between the <xsl:template match="/"> and </xsl:template> tags of home-tutorial.xsl. The following modifications were made:

    Changed the text to be Greenstone-related
    Removed escape characters (&nbsp;, &copy;, etc.) that are not currently supported in GS3
    Ensured every tag had a closing tag (or was self-closing)
    Corrected the paths for the CSS stylesheet and image
    Added in links to certain Greenstone pages (like the Login, Help, and Preferences pages).
    Added a page icon.

  1. Adding links to specific pages is relatively straightforward. If you want to link to the backdrop collection, for instance, you could simply add in <a href="{$library_name}/collection/backdrop/page/about">backdrop</a> ({$library_name} is a variable that, in this case, will become "library" -- you will learn more about library names in later tutorials). However, if you have many collections, this is time consuming, and the home page would have to be modified every time you added or removed a collection. Instead, we can use XSL to insert appropriate HTML into our page for each collection in our library. First, we will define a template that does this, and then we will call this template in the right spot in our HTML.

Adding the list of collections

  1. Open home-tutorial.xsl in a text editor. Copy the the highlighted text into the area indicated (this, and all other text excerpts can be copied from gs3-hompage.txt in sample_files → custom):

    <!-- end #footer -->

    <xsl:template name="collectionsList">
    <xsl:for-each select="./page/pageResponse/collectionList/collection">
    <xsl:variable name="collectionName" select="@name"/>
    <a href="{$library_name}/collection/{$collectionName}/page/about">
    <xsl:value-of select="displayItemList/displayItem[@name='name']"/>


  1. Then, find the section below, and change this:

    <h2>Select a Collection:</h2>
    <li><a href="#">Collection 1</a></li>
    <li><a href="#">Collection 2</a></li>
    <li><a href="#">Collection 3</a></li>
    <li><a href="#">Collection 4</a></li>
    <li><a href="#">Collection 5</a></li>

    To this:

    <h2>Select a Collection:</h2>
    <xsl:call-template name="collectionsList"/>

  1. Save this file, and refresh your library homepage. The right side bar should now contain a list of all of your collections. Click on one to make sure the link works correctly, and then return to the home page.

Adding a cross-collection search box

  1. The current search box does not actually work. We are going to replace this with a search box that will search all collections in our library.

    First, add the following template before the final </xsl:stylesheet>:

    <xsl:template name="searchBox">
    <xsl:for-each select="//page/pageResponse/serviceList/service[@name='TextQuery']">
    <form name="QuickSearch" method="get" action="{$library_name}">
    <input type="hidden" name="a" value="q"/>
    <input type="hidden" name="rt" value="rd"/>
    <input type="hidden" name="s" value="{@name}"/>
    <input type="hidden" name="s1.collection" value="all"/>
    <input type="text" name="s1.query" size="20" id="search-text" value="" />
    <input type="submit" id="search-submit">
    <xsl:attribute name="value">
    <xsl:value-of select="util:getInterfaceText($interface_name, /page/@lang, 'home.quick_search')"/>

  1. Then, find the following section:

    <form method="get" action="#">
    <input type="text" name="s" id="search-text" value="" />
    <input type="submit" id="search-submit" value="" />

    And replace it with this:

    <xsl:call-template name="searchBox"/>

  1. Save home-tutorial.xsl, and refresh your home page. You now have a working cross-collection search box. Search for "economy" to see that it works, and then return to the home page.

Login Links

  1. Under the heading "Library Links" in the left sidebar of your home page, you will notice that there are several links. However, we don't want all of these links to appear all of the time. "Login" should only appear when the user is not logged in, while "admin" (Account Settings), "Register as a new user", "Administration", and "Logout" should only appear when a user is logged in.

  1. We will define and call a template that will display the correct links depending on whether a user is logged in or not.

    Add the following template before the final </xsl:stylesheet>:

    <xsl:template name="loginButton">
    <xsl:variable name="username" select="/page/pageRequest/userInformation/@username"/>
    <xsl:variable name="groups" select="/page/pageRequest/userInformation/@groups"/>

    <xsl:when test="$username">
    <xsl:if test="contains($groups,'admin')">
    <li class="login"><a href="{$library_name}/admin/AddUser">Add user</a></li>
    <li class="login"><a href="{$library_name}/admin/ListUsers">Administration</a></li>
    <li class="login"><a href="{$library_name}/admin/AccountSettings?s1.username={$username}">Logged in as: <xsl:value-of select="$username"/></a></li>
    <li class="login"><a href="{$library_name}?logout=">Logout</a></li>
    <li class="login">
    <a href="{$library_name}?a=p&amp;sa=login&amp;redirectURL={$library_name}%3Fa=p%26sa=home">Login
    <xsl:attribute name="title">
    <xsl:value-of select="util:getInterfaceText($interface_name, /page/@lang, 'login_tip')"/>

  1. Then, find the following section:

    <li><a href="?a=p&amp;sa=login&amp;redirectURL={$library_name}%3Fa=p%26sa=home">Login</a></li>
    <li><a href="{$library_name}/admin/AccountSettings?s1.username=">Account Settings</a></li>
    <li><a href="{$library_name}/admin/AddUser">Register a new user</a></li>
    <li><a href="{$library_name}/admin/ListUsers">Administration</a></li>
    <li><a href="{$library_name}?logout=">Logout</a></li>

    And replace it with this:

    <xsl:call-template name="loginButton"/>

  1. Save home-tutorial.xsl, and refresh your home page. If you are logged in, click "Logout" to view the homepage in logged out mode. If you are not logged in, click "Login" and enter your username and password to view the homepage in logged in mode.

Adding your library's site name

  1. In home-tutorial.xsl, replace the first two occurrences of "A New Home Page" with <xsl:call-template name="siteName"/>.

    Save home-tutorial.xsl, and refresh your home page. The name of the browser window and the page's main header should now be "My Greenstone Library". By using this template, you can ensure your library's name is consistent across your entire library. If you decide to change your library name, you only need to make the change in one place. The following section demonstrates how to do this.

Changing your library's site name

  1. To change the name of your library, open the siteConfig.xml file located in Greenstone3 → web → sites → localsite in a text editor. Near the start of the file, find the line:

    <displayItem name="siteName" lang="en">My Greenstone Library</displayItem>

    And replace "My Greenstone Library" with another name, like "The Best Digital Library". Then save and close the file.

  1. For changes to siteConfig.xml to take effect, the site must be reconfigured. To do this, you can either restart the server, or, in a browser window, navigate to http://localhost:8383/greenstone3/library?a=s&sa=c (replace 8383 if you are running the Greenstone3 server on another port, like 8080 or 8088). Wait for the page to reload, which may take a while if there are many collections in your digital library. Navigate back to your home page (by clicking the link in the upper left corner). The page title and header should now be your new library name. Enter one of your collections and you should see that your library name (in the top left corner) has changed here, as well.

Copyright © 2005-2019 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.”