Greenstone tutorial exercise

Back to wiki
Back to index
Sample files: interfaces.zip
Devised for Greenstone version: 3.06
Modified for Greenstone version: 3.09

Designing a new interface: Part 1

This tutorial series demonstrates how to create a new interface using the default interface as a base. In this first tutorial, we will set the stage by creating a barebones interface, defining a library that uses the interface, and gathering the various Javascript, CSS, and image files that will be used by the new interface.

Creating a new interface

  1. In a file browser, navigate to the interfaces folder of your Greenstone3 installation (C: → Users → <user-name> → Greenstone3 → web → interfaces).

    Create a new folder (in the right-click menu, select New → Folder) and call it perrin. The name of this folder (perrin) determines the name of your new interface.

  1. From sample_files → interfaces → aybara folder, copy the interfaceConfig.xml file into the perrin folder. Open the file perrin → interfaceConfig.xml in a text editor. The interface configuration file is used to specify the languages the interface is available in, certain options, and what "actions" are available. Actions create the web pages for the library and specify what XSL file should be used for each. For example, if you completed the Home Page Tutorial, you changed the home subaction to point to home-tutorial.xsl instead of home.xsl.

    We are going to make one important change to this file. Our new interface is going to borrow heavily from the default interface. We will be reusing many of the XSL files, Javascript, and images. We could copy all of these files into our new interface, however, there are a few drawbacks to this solution:

    • we will end up with duplicates of a large number of files
    • there are many files in the default interface that we won't need
    • it will be difficult to keep track of which files are different/unique to our new interface

    A better solution is to base our new interface on the default interface. A base interface is used by Greenstone as a kind of backup. If Greenstone can't find a file in our interface, it will then try to find it in the base interface. To assign default as base interface, in perrin → interfaceConfig.xml, change the second line from this:

    <interfaceConfig>

    To this:

    <interfaceConfig baseInterface="default">

  1. Save and close interfaceConfig.xml.

Defining a new library

  1. Now, let's define a library that uses the new interface. In Greenstone3 → web → WEB-INF open servlets.xml, and add the following (the exact location doesn't matter, just put it with the other servlets):

    <servlet>
    <servlet-name>golden</servlet-name>
    <description>A new library with my new interface!</description>
    <servlet-class>org.greenstone.gsdl3.LibraryServlet</servlet-class>
    <init-param>
    <param-name>library_name</param-name>
    <param-value>golden</param-value>
    </init-param>
    <init-param>
    <param-name>site_name</param-name>
    <param-value>localsite</param-value>
    </init-param>
    <init-param>
    <param-name>interface_name</param-name>
    <param-value>perrin</param-value>
    </init-param>
    <init-param>
    <param-name>receptionist_class</param-name>
    <param-value>DefaultReceptionist</param-value>
    </init-param>
    <init-param>
    <param-name>default_lang</param-name>
    <param-value>en</param-value>
    </init-param>
    </servlet>

    This defines a new library called "golden" that uses "localsite" and our new "perrin" interface. Now, near the bottom of the file, add in a servlet mapping to tell the server where our new library should be located:

    <servlet-mapping>
    <servlet-name>golden</servlet-name>
    <url-pattern>/golden/*</url-pattern>
    </servlet-mapping>

  1. Save servlets.xml. Start up your Greenstone server (Start → All Programs → Greenstone3 → Greenstone3 Server) and click the Enter Library button. This will take you to the default library's home page.

    Navigate to http://localhost:8383/greenstone3/golden. This library is using the perrin interface. However, since perrin contains no files except its configuration file, Greenstone is borrowing everything from default, perrin's base interface.

Gathering files

  1. To change how the perrin interface looks, we will be adding some key XSL files (home.xsl, header.xsl, and main.xsl). However, before we do that, we want to gather all of the new CSS, Javascript, and image files we will be using with our new interface.

    Since designing web pages is quite challening in itself, we will be taking advantage of free CSS templates that can be downloaded and modified. There are many websites that offer high quality web page designs, often for free. (Always be sure to read the license information fully to ensure you do not violate the usage agreement in any way.)

  1. Visit http://www.os-templates.com/free-website-templates/news-magazine and click the Download This Template button. In the popup window, select Save File and click OK. This will download a file with a 7z (7zip) extension. If you have 7zip installed, then you can extract the file in place. If not, you can either download the free utility, 7zip, from the web, or alternatively use an online service to convert it to a zip file that Windows can extract.

    To do the latter, visit https://convertio.co/uz-zip/ or https://onlineconvertfree.com/convert-format/7z-to-zip/. (If conversions don't work on Microsoft Edge, try another web browser like Firefox, if you have it installed. Or you can search the web for alternative free online zip conversion services.) The general proccess is the same: Upload your .7z file. Make sure the output format is set to zip and, once your file has been uploaded, you'll be presented with a convert button which you need to press. Once the conversion process has finished, a Download button will appear. Press it to download the .zip file onto your machine. (Such sites may also furnish you with a button by means of which you can clear your uploaded files from their servers.)

    On Windows, your converted zip version of the template will have been saved in your Downloads folder. This template is free to use and modify, but the Copyright and link information must remain intact in files and in the footer of every page. The template cannot be distributed (modified or otherwise) without express permission from OS-Templates. (The full license is provided in the license.txt file included with the template).

    In an Explorer window, navigate to your Downloads folder (C:\Users\<user-name>\Downloads). Right-click on the downloaded zip file containing the template, select Extract All... and, in the popup window, click Extract.

  1. In the newly extracted folder, open the layout subfolder and copy the styles, scripts, and images folders into Greenstone3 → web → interfaces → perrin. Also copy the file license.txt from the extracted folder into the same location. Move the javascript files (files that end with a js extension) that are in the new perrin → scripts → galleryviewthemes folder into perrin → scripts. Move the perrin → scripts → galleryviewthemes → themes into perrin → images, and rename this themes folder to galleryviewthemes. If you wish, you can now delete the perrin → scripts → galleryviewthemes folder.

    In the new perrin → images folder, delete all the images, because we will not be using any of these.

  1. In the perrin → styles folder, open layout.css in a text editor and delete the following line:

    @import url("tables.css");

    Save and close layout.css.

  1. Now, from the sample_files → interfaces → aybara folder, copy the styles, images, and transform folders, as well as the index-GS3.html file into Greenstone3 → web → interfaces → perrin. (If a popup window asks whether you want to merge the images and styles folders, select "Yes".)

    Next, copy the two javascript files in sample_files → interfaces (jquery.galleryview-2.1.1.js and especially jquery.galleryview.2.1.1.min.js) to Greenstone3 → web → interfaces → perrin → scripts, replacing any existing files of identical name. These two javascript files are modified versions to cope with an update to jquery. The modified files are necessary for the next tutorial's image slider to show up and work.

    We have now gathered all of the Javascript, CSS, and images our new interface will use.

    Double click on perrin → index-GS3.html to open it in a browser window. This file isn't used by the new interface, but provides a preview of how the interface will look.

    In the next tutorial, we will begin changing how our interface looks, starting with the home page.


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