Greenstone tutorial exercise

Back to wiki
Back to index
Sample files: libraries.zip
Devised for Greenstone version: 3.06
Modified for Greenstone version: 3.11

Defining Libraries

Greenstone3 is built on the idea of sites and interfaces. Sites mainly contain content, i.e. they contain collections, which, in turn, contain documents and associated metadata. Sites are a convenient way to group collections.

Interfaces dictate the presentation -- e.g. the HTML, CSS, Javascript, etc. used to present the content. You can have multiple sites and interfaces.

Libraries combine content and presentation. To define a library, you select the site and the interface you want it to use. And, of course, you can have multiple libraries, and each site and interface can be used multiple times.

In this tutorial, we will become familiar with servlets.xml.in (where libraries are defined), create a new site, add an interface, and define a new library.

Note: The active version of this file is called servlets.xml and is located in Greenstone3 → web → WEB-INF → servlets.xml, but it is not to be manually edited. Each time the Greenstone 3 server is run, this file is automatically re-generated from its template file at Greenstone3 → resources → web → servlets.xml.in, which can be edited as we do in this tutorial.

Exploring libraries

  1. Start up your Greenstone server (Start → All Programs → Greenstone3.11 → Greenstone3 Server) and click the Enter Library button. This will take you to the default library's home page. This library uses the site called localsite and the interface called default.

    Change the url from http://localhost:8383/greenstone3/library to http://localhost:8383/greenstone3/halftone-library and reload the page. This is another library that is defined by Greenstone3. Again, the site it uses is localsite, but this library (called halftone-library) uses the halftone interface, which is based on the Greenstone2 layout. Let's take a look at where these libraries are defined.

  1. In a Windows Explorer, navigate to the Greenstone3 → resources → web folder and open the template file servlets.xml.in in a text editor. Find the following section:

    <servlet>
    <servlet-name>library</servlet-name>
    <description>The standard gsdl3 library program</description>
    <servlet-class>org.greenstone.gsdl3.LibraryServlet</servlet-class>
    <init-param>
    <param-name>library_name</param-name>
    <param-value>library</param-value>

    ...

    <init-param>
    <param-name>default_lang</param-name>
    <param-value>en</param-value>
    </init-param>
    </servlet>

    This library servlet defines the default Greenstone3 library (called library). As you can see, the library_name is library, the site_name is localsite, and the interface_name is default. If you look at the next servlet section, you will see that it has a library_name of halftone-library, uses localsite and the interface halftone. If you continue to scroll down, you will see several other library servlet definitions, albeit inactive as they're commented out. There are also other kinds of de-activeated servlets, such as gateway. These are beyond the scope of this tutorial.

  1. At the end of each library servlet definition, you will see a corresponding servlet mapping for it, looking something like this:

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

    Every servlet -- and, therefore, every library we define -- needs a servlet mapping, which tells the server at what URL the servlet should be located. (Notice that the servlet-name here is the same as above, and the url-pattern matches the library_name; this is required. The servlet-name does not have to match the library_name/url-pattern, but it is good practice to make them all the same.)

    Now that we've seen how libraries are defined in Greenstone3, let's take a look at where sites are located, how to create a new site, and how to define a new library that uses this site.

Creating a new site

  1. Sites are located in Greenstone3 → web → sites. In this folder, you will see two sites: gateway and localsite. (gateway is a bit different, and it won't be discussed in this tutorial.) Create a new folder in sites called mysite. This will be the name of your new site. In mysite, create a folder called collect. This is where all of this site's collections will be located. Finally, copy the siteConfig.xml file from the localsite folder into the mysite folder. (You can, of course, make modifications to the siteConfig.xml to configure your site, but, for simplicity's sake, we'll just use an exact copy.)

  1. You have now created a site called mysite. However, it has no content yet, and it would be nice to have at least one collection in your new site. From localsite → collect, copy the folder lucene-jdbm-demo, and paste it into mysite → collect.

Defining a new library

  1. Now, let's define a library that uses this new site. In servlets.xml.in, add the following (which can be copied from sample_files → libraries → def_libs.txt); The exact location doesn't matter, just put it with the other servlets:

    <servlet>
    <servlet-name>library2</servlet-name>
    <description>A new library with my new site!</description>
    <servlet-class>org.greenstone.gsdl3.LibraryServlet</servlet-class>
    <init-param>
    <param-name>library_name</param-name>
    <param-value>library2</param-value>
    </init-param>
    <init-param>
    <param-name>site_name</param-name>
    <param-value>mysite</param-value>
    </init-param>
    <init-param>
    <param-name>interface_name</param-name>
    <param-value>default</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 library2 that uses mysite and the default interface. Immediately after that, or else at 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>library2</servlet-name>
    <url-pattern>/library2/*</url-pattern>
    </servlet-mapping>

  1. Save servlets.xml.in. For the changes to take effect, we must first restart the server. Click the Restart Library button in the Greenstone Server window. When the new browser window opens, navigate to http://localhost:8383/greenstone3/library2 to see your newly defined library. Notice that only one collection appears -- the Lucene Demo Collection that we copied into mysite.

Adding and using a new interface

  1. Now that we know how to create and use a new site, let's add a new interface and define a library that uses it. Creating a new interface takes time (and is a tutorial all its own), so, for this tutorial, we are just going to use a pre-made interface. From the sample_files → libraries folder, copy the folder althor into the Greenstone3 → web → interfaces folder. In servlets.xml.in, define a new library that uses the althor interface:

    <servlet>
    <servlet-name>rand</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>rand</param-value>
    </init-param>
    <init-param>
    <param-name>site_name</param-name>
    <param-value>mysite</param-value>
    </init-param>
    <init-param>
    <param-name>interface_name</param-name>
    <param-value>althor</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>

    and provide the servlet mapping:

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

  1. Save servlets.xml.in, restart the server again and navigate to http://localhost:8383/greenstone3/rand, where you will see the rand library, which displays mysite using the althor interface.

    The althor interface was created using a free CSS template created by luiszuno.com. If any of your collections have a home page image, an image slider will appear on the home page of your library. (You can add a home page image to a collection in the General section of the Format panel in the GLI.)

Changing default settings for the Greenstone server and GLI

  1. When we restarted the server throughout this tutorial, Greenstone launched a browser window to http://localhost:8383/greenstone3/library, and we had to navigate to our new library's URL. When you are working in a particular library, you may want to go directly to its URL when the server starts. To do this, in the Greenstone Server window, go to File → Settings... and select your library (for example, rand) from the Servlet dropdown menu. Now, when you click Restart Library, a window will open to http://localhost:8383/greenstone3/rand.

  1. In the GLI, you can change the current library under File → Preferences → Connection. First, select the Site you want to work with (for example, mysite). The Servlet dropdown menu will then include all of the libraries that use mysite. Select one. Be sure to also change the Collect Directory to the mysite/collect folder. Click OK for the changes to take effect. Now, you will be adding and editing collections in the mysite site, and, when you click the Preview button, the selected library will be launched.

  1. As you begin using multiple libraries while using GLI, you should be aware of a couple of things. First, any changes you make in the GLI are collection-level, which means they will be consistent for this collection no matter what library you are using. However, changes may only take effect immediately in the current library. The server may need to be restarted for the changes to appear in other libraries. Second, switching between servlets -- or viewing a collection in a library other than the one currently being used by the GLI -- can create a lock on files in a collection, which will cause an error during collection building. To avoid this, if you use multiple libraries after launching the GLI, restart the server before rebuilding a collection.


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