Greenstone tutorial exercise

Back to wiki
Back to index
Prerequisite: Designing a new interface: Part 1
Sample files: interfaces.zip
Devised for Greenstone version: 3.06
Modified for Greenstone version: 3.08

Designing a new interface: Part 2

In this tutorial, we will be adding home.xsl and header.xsl files to the perrin interface. Modifying XSL files must be done with care. If the XSL is ill-formed or invalid, the page will not display properly. This tutorial attempts to highlight some of the common mistakes that might result in errors. Whenever you are editing XSL files, remember to save very often, and then refresh your browser to see if there is an error.

  1. Start up your Greenstone server (Start → All Programs → Greenstone3 → Greenstone3 Server) and click the Enter Library button and navigate to http://localhost:8383/greenstone3/golden in the web browser, which still looks identical to the home page of the default interface.

Changing the home page content

  1. From the sample_files → interfaces → aybara folder, copy home.xsl into Greenstone3 → web → interfaces → perrin → transform → pages. In the browser, refresh the library home page. The content of the page should now be only "HOME PAGE CONTENT GOES HERE". Open home.xsl in a text editor and take a look at it.

  1. In a previous tutorial, we created a home page that was completely different than the rest of our library's pages. This time, however, the home page will share a large portion of its layout and style with the rest of the library's pages. So, we're only going to change the home page's content by modifying the /page/pageResponse template. We will be adding three sections to our home page: an image slider, a section that can contain featured content, and a list of all of the collections in the library, along with their descriptions.

    Replace HOME PAGE CONTENT GOES HERE with the following:

    <div class="content">
    <div id="featured_slide">
    <ul id="featurednews">
    <xsl:call-template name="collSlider"/>
    </ul>
    </div>
    </div>

  1. Save home.xsl and refresh your web browser. DON'T PANIC! You should now see an Apache Tomcat error. This is because we are calling a template (collSlider) that doesn't exist. Now add the following before the final </xsl:stylesheet>:

    <xsl:template name="collSlider">
    <xsl:for-each select="./collectionList/collection">
    <xsl:variable name="collectionFolder" select="@name"/>
    <xsl:variable name="collectionName" select="displayItemList/displayItem[@name='name']"/>
    <xsl:variable name="homeImage">
    <xsl:choose>
    <xsl:when test="displayItem[@name='smallicon']">
    sites/<xsl:value-of select="$site_name"/>/collect/<xsl:value-of select="$collectionFolder"/>/images/<xsl:value-of select="displayItem[@name='smallicon']"/>
    </xsl:when>
    <xsl:otherwise>
    interfaces/<xsl:value-of select="$interface_name"/>/images/default.jpg
    </xsl:otherwise>
    </xsl:choose>
    </xsl:variable>

    <li><img src="{$homeImage}" alt="" />
    <div class="panel-overlay">
    <a href="{$library_name}/collection/{$collectionFolder}/page/about">
    <h2><xsl:value-of select="$collectionName"/></h2>
    </a>
    </div>
    </li>
    </xsl:for-each>
    </xsl:template>

  1. Save home.xsl and refresh your web browser. You should no longer have an error. For every collection in your library, you should now see an image followed by the collection's name. In a moment, we will add in the Javascript that will turn these into a slider, but first, let's consider what the collSlider template is doing.

    Basically, for every collection in your library (<xsl:for-each select="./collectionList/collection">), it is creating a list item that includes an image and the collection's name, which links to the collection's about page. If the collection has a Home page image (the "smallicon"), this will be displayed. Otherwise a backup image (default.jpg, which is located in perrin → images) will be displayed.

  1. Now, add Javascript files that will turn these list items into an image slider. Before the final </xsl:stylesheet>, add the following:

    <xsl:template name="additionalHeaderContent">
    <script type="text/javascript" src="interfaces/{$interface_name}/scripts/jquery.easing.1.3.js"><xsl:text> </xsl:text></script>
    <script type="text/javascript" src="interfaces/{$interface_name}/scripts/jquery.timers.1.2.js"><xsl:text> </xsl:text></script>
    <script type="text/javascript" src="interfaces/{$interface_name}/scripts/jquery.galleryview.2.1.1.min.js"><xsl:text> </xsl:text></script>
    <script type="text/javascript" src="interfaces/{$interface_name}/scripts/jquery.galleryview.setup.js"><xsl:text> </xsl:text></script>
    </xsl:template>

    Save home.xsl and refresh your web browser. All of the images and collection names should now be condensed into an image slider. (It is still missing some style, because we haven't added links to our CSS files yet.) This additionalHeaderContent template is "called" in the header.xsl file, which we will see later in this tutorial.

  1. Add the next section of the home page's content. In the /page/pageResponse template, insert the highlighted section where indicated:

    <xsl:call-template name="collSlider"/>
    </ul>
    </div>
    </div>
    <div class="column">
    <ul class="latestnews">
    <li>
    <p><strong><a href="#">Highlighted Item 1</a></strong><br/>This is a place where you can put information about an item you would like to highlight in your collection, with or without an accompanying image.</p>
    </li>
    <li><img src="interfaces/{$interface_name}/images/80x80.jpg" alt="" />
    <p><strong><a href="#">Highlighted Item 2</a></strong><br/>This is a place where you can put information about an item you would like to highlight in your collection,with or without an accompanying image.</p>
    </li>
    <li class="last"><img src="interfaces/{$interface_name}/images/80x80.jpg" alt="" />
    <p><strong><a href="#">Highlighted Item 3</a></strong><br/>This is a place where you can put information about an item you would like to highlight in your collection, with or without an accompanying image.</p>
    </li>
    </ul>
    </div>
    <br class="clear" />

    </xsl:template>

    Save home.xsl and refresh your web browser. This section will be an area where you can add in your own content. Notice the file paths for the image files begin with interfaces/{$interface_name}. As its name suggests, {$interface_name} becomes the name of the interface, in this case "perrin".

  1. Finally, add in the highlighted section:

    <br class="clear" />

    <div id="hpage_cats">
    <xsl:call-template name="collectionsList"/>
    </div>

    </xsl:template>

    And add the following templates before the final </xsl:stylesheet>:

    <xsl:template name="collectionsList">
    <xsl:for-each select="./collectionList/collection">
    <xsl:choose>
    <xsl:when test="position() mod 2 = 1">
    <div class="fl_left">
    <xsl:call-template name="collDescription"/>
    </div>
    </xsl:when>
    <xsl:otherwise>
    <div class="fl_right">
    <xsl:call-template name="collDescription"/>
    </div>
    <br class="clear" />
    </xsl:otherwise>
    </xsl:choose>
    </xsl:for-each>
    </xsl:template>

    <xsl:template name="collDescription">
    <xsl:variable name="collectionFolder" select="@name"/>
    <xsl:variable name="collectionName" select="displayItemList/displayItem[@name='name']"/>
    <xsl:variable name="aboutImage" select="displayItemList/displayItem[@name='icon']"/>
    <xsl:variable name="collDesc" select="displayItemList/displayItem[@name='description']"/>
    <xsl:variable name="numDocs" select="metadataList/metadata[@name='numDocs']"/>

    <h2><a href="{$library_name}/collection/{$collectionFolder}/page/about"><xsl:value-of select="$collectionName"/></a></h2>
    <xsl:if test="$aboutImage">
    <img src="sites/{$site_name}/collect/{$collectionFolder}/images/{$aboutImage}" alt="{$collectionName}" />
    </xsl:if>

    <xsl:choose>
    <xsl:when test="$collDesc">
    <p class="justify"><xsl:value-of select="$collDesc" disable-output-escaping="yes"/></p>
    </xsl:when>
    <xsl:otherwise>
    <p class="justify">Welcome to the <xsl:value-of select="$collectionName"/> collection. This collection contains <xsl:value-of select="$numDocs"/> documents.</p>
    </xsl:otherwise>
    </xsl:choose>
    </xsl:template>

    These templates are more complicated, but a basic explanation follows (don't worry if you don't understand it). You can skip ahead to Step 9 if you'd like.

    First look at the collDescription template. It creates a header that links to the collection's about page (<h2><a href="{$library_name}/collection/{$collectionFolder}/page/about"><xsl:value-of select="$collectionName"/></a></h2>). Then, if there is an About page image for the collection, this is displayed. Finally, if the collection has a description (<xsl:when test="$collDesc">), it will display this description. Otherwise, it will display a generic sentence stating the collection's name and how many documents it contains.

    Now, let's look at the collectionsList template. Basically, for every collection in the library (<xsl:for-each select="./collectionList/collection">), it is calling the collDescription template, i.e. doing everything explained in the previous paragraph. However, the CSS we will be using requires that our div's alternate between class "fl_left" and class "fl_right" or the page won't display correctly. So, if the collection is an odd number in the list (<xsl:when test="position() mod 2 = 1">), the collection description will be in a <div class="fl_left">, otherwise (i.e. when it is an even number in the list) the collection description will be in a <div class="fl_right">. Once we link our CSS, this will make our descriptions fall into two nice columns.

  1. Save and close home.xsl and refresh your web browser, which should now include the names and descriptions (and, accompanying images if any of your collections have an About page image) for each collection in your library.

    We have now made all of our changes to home.xsl. Next, we will add a new header.xsl file, where the HTML header content is located.

Changing the HTML header content

  1. From the sample_files → interfaces → aybara folder, copy header.xsl into Greenstone3 → web → interfaces → perrin → transform → layouts. (Be aware that the destination now is the layouts folder and not the pages folder whereto you had previously copied home.xsl) Refresh your web browser: nothing should have changed.

  1. Now open header.xsl in a text editor. It contains only one template called "create-html-header", which was copied directly from the default interface's header.xsl. We are going to remove the links to the CSS files used by the default interface, and add in the links to our new CSS files. Scroll down and replace the following lines:

    <xsl:choose>
    <xsl:when test="/page/pageResponse/interfaceOptions/option[@name = 'cssTheme']/@value">
    <!-- Get the theme from the interfaceConfig.xml file -->
    <link rel="stylesheet" href="{/page/pageResponse/interfaceOptions/option[@name = 'cssTheme']/@value}" type="text/css"/>
    </xsl:when>
    <xsl:otherwise>
    <link rel="stylesheet" href="interfaces/{$interface_name}/style/themes/main/jquery-ui-1.8.16.custom.css" type="text/css"/>
    </xsl:otherwise>
    </xsl:choose>
    <link rel="stylesheet" href="interfaces/{$interface_name}/style/core.css" type="text/css"/>

    With this:

    <link rel="stylesheet" href="interfaces/{$interface_name}/styles/layout.css" type="text/css" />
    <link rel="stylesheet" href="interfaces/{$interface_name}/styles/gs3-core-min.css" type="text/css" />

  1. Save header.xsl and refresh your web browser. The page should have changed drastically. We removed the links to the default CSS, which removed all of the old style. But, since we added in links to our new CSS, all of the content we just added to the home page should now be styled much better.

    Near the bottom of header.xsl, you will see this line: <xsl:call-template name="additionalHeaderContent"/>. For the home page, this is where the four <script> elements from Step 6 above will be placed.

    Close header.xsl. In the next and final tutorial on designing an interface, we will add and modify main.xsl.


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.”