Table of Contents
Customizing the Greenstone 3 interface
Format statements in the collection configuration files provide a way to change small parts of the collection display. For large scale customizations to a collection, or ones that apply to a site as a whole, a second mechanism is available. The interface is defined by a set of XSLT files that transform the page data into HTML. Any of these files can be overridden to provide specialized display, on a site or collection basis.
The first section looks at customizing the existing interface, while the second section looks at defining a whole new interface. The last section describes how to add a new language translation of an interface.
Modifying an existing interface
Most of an interface is defined by XSLT files, which are stored in
interfaces/<interface-name>/transform. These can be changed and the changes
will take effect straight away. If changes only apply to certain collections or sites,
not everything that uses the interface, you can override some of the files by putting
new ones in a different place. XSLT files are looked for in the following order:
collection, site, interface, default interface. (This currently only apples to sites,
and therefore collections, that reside in the same Greenstone installation as the
Sites and collections can have a transform directory, which is where customized
XSLT files should go. Any XSLT files in here will be used in preference to the
interface files when using this collection. For example, if you want to have a
completely different layout for the about page of a collection, you can put a new
about.xsl file into the collection's transform directory, and this will be used instead. This is what we do for the Gutenberg sample collection.
This also applies to files that are included from other XSLT files. For example
query.xsl for the query pages includes a file called
querytools.xsl. To have
a particular site show a different query interface either of these files may need to
be modified. Creating a new version of either of these and putting it in the site
transform directory will work. Either the new
query.xsl will include the default
querytools.xsl, or the default
query.xsl will include the new
xsl:include directives are preprocessed by the Java code and full paths added
based on availability of the files, so that the correct one is used.
Note that you cannot include a file with the same name as the including file.
query.xsl cannot include
query.xsl (it is tempting to want to
do this if you just want to change one template for a particular file, and then include
the default but you can't).
You can add the argument
o=xml to any URL and you will be returned the XML
before transformation by a stylesheet. This shows you the XML page source. It
can be useful when you are trying to write some new XSLT statements.
How to change just one template
You might like to make changes to the interface, but restrict them to a subset of the library. There are different ways to change a template. For example, suppose we wanted to change what gets displayed on the about page for the collection description. If we look at the transform/pages/about.xsl, we find some templates:
<xsl:template match="/page"> .... <xsl:call-template name="coll-description"/> </xsl:template> <xsl:template name="coll-description"> <gslib:collectionDescriptionTextAndServicesLinks/> </xsl:template>
We might decide that we don't want the default behaviour for the coll-description template and we want to change it.
- Edit the XSL file in web/interfaces/default/transform - if we edit the template directly in the main pages/about.xsl file, then the change will apply to all collections in our library.
- Edit the XSL file in web/sites/<sitename>/transform - if we have multiple sites, we can make a new pages/about.xsl in the site's transform folder, and it will apply to only those collections in that site.
- Edit the XSL in web/collect/<collname>/transform - we can make a new pages/about.xsl file in the collection's transform folder. Any changes we make here will only affect this collection.
The new about.xsl file doesn't have to implement everything in the old version. You can add in only the templates that you want to change.
For example, this might be the collection's about.xsl. We are only changing 1 template. The rest of the about page templates will come from the defualt XSL file: web/interfaces/default/transform/pages/about.xsl,
<?xml version="1.0" encoding="ISO-8859-1"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:java="http://xml.apache.org/xslt/java" xmlns:util="xalan://org.greenstone.gsdl3.util.XSLTUtil" xmlns:gslib="http://www.greenstone.org/skinning" extension-element-prefixes="java util" exclude-result-prefixes="java util"> <xsl:template name="coll-description"> <xsl:value-of select="/page/pageResponse/collection/displayItemList/ displayItem[@name='description']" disable-output-escaping="yes"/> <h4>This collection has <xsl:value-of select="/page/pageResponse/collection/ metadataList/metadata[@name='numDocs']"/> docs.</h4> </xsl:template> </xsl:stylesheet>
Changing the interface language
The interface language can be changed by going to the preferences page, and choosing a language from the list, which includes all languages into which the interface has been translated.
It is easy to add a new interface language to Greenstone. Language specific
text strings are separated out from the rest of the system to allow for easy incorporation of new languages. These text strings are contained in Java resource bundle
properties files. These are plain text files consisting of key-value pairs, located in
$GSDL3HOME/WEB-INF/classes. Each interface has one named
(where 'name' is the interface name, for example,
interface_classic.properties). Each service class has one with the same
name as the class (e.g.
GS2Search.properties). To add another language all of
the base .properties files must be translated. The translated files keep the same
names, but with a language extension added. For example, a French version of
interface_default.properties would be named
Keys will be looked up in the properties file closest to the specified language.
For example, if language
fr_CA was specified (French language, country Canada),
and the default locale was
en_GB, Java would look at properties files in the following order,
until it found the key:
XXX_en.properties, and finally the default
These new files are available straight away. To use the new language, add e.g.
l=fr to the arguments in the URL. To get Greenstone to add it in to the list of
languages on the preferences page, an entry needs to be added into the languages
list in the
interfaceConfig.xml file. Modification of this file
requires a restart of the Tomcat server for the changes to be recognized.
Creating a new interface
Instead of modifying an existing interface, you can also create a new interface. Creating a new interface will allow modifications to be made while leaving the original one intact. Creating a new interface is also useful if you want to display the same site in different ways.
A new interface needs a directory in
Greenstone3 → web → interfaces, the name of
this directory becomes the interface name. This folder must
have an ''interfaceConfig.xml'' file. From this point, you have two options:
- Creating an independent interface
- Using a "base" interface
If you are creating an independent interface, the interface folder needs images and
transform directories. It will need a full set of XSLT files to dictate the presentation of
each page type in the library. (It might be helpful to use the structure and contents of the
default interface as a guide.)
A benefit of this route is that your interface will basically be self-contained; all of the files the interface uses and relies upon will be within the interface's folder.
You can set a base interface on the second line of the
Interface configuration file
The interface configuration file
interfaceConfig.xml lists all the actions that the interface knows about at the start (other ones can be loaded dynamically). Actions create the web pages for the library: there is generally one Action per type of page. For example, a query action produces the pages for searching, while a document action displays the documents. The configuration file specifies what short name each action maps to (this is used in library URLs for the a, i.e. action, parameter) e.g. QueryAction should use
a=q. If the interface uses XSLT, it specifies what XSLT file should be used for each action and possibly each subaction. This makes it easy for developers to implement and use different actions and/or XSLT files without recompilation. The server must be restarted, however.
It also lists all the languages that the interface text files have been translated into. These have a
name attribute, which is the ISO code for the language, and a
displayElement which gives the language name in that language (not that this file should be encoded in UTF-9=8). This language list is used on the Preferences page to allow the user to change the interface language. Details on how to add a new language to a Greenstone3 library are shown below.
optionList element can be used to disable or enable some optional functionality for the interface. Currently, there are three options that can be enabled:
- highlightQueryTerms: Whether search term highlighting is available or not
- berryBaskets: Whether berry basket functionality is available or not
- displayAnnotationService: Whether any annotation services (specified in the site config file) should be displayed with a document or not.
Using the new interface
To use a new interface, the
$GSDL3HOME/WEB-INF/web.xml file must be edited:
either change the interface that a current servlet instance is using, or add another
servlet instantiation to the file (more about servlets):
<servlet> <servlet-name>mylibrary</servlet-name> <description>My new GS3 interface</description> <servlet-class>org.greenstone.gsdl3.LibraryServlet</servlet-class> <init-param> <param-name>library_name</param-name> <param-value>home</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>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>
Near the bottom of the file, add the following text:
<servlet-mapping> <servlet-name>mylibrary</servlet-name> <url-pattern>/home/*</url-pattern> </servlet-mapping>
The Tomcat server must be restarted for this to take effect.
- Tutorials on creating a new interface:
- Expanding on the GS3 Customisation tutorials to add support for collection groups, the depositor, add links for search forms, add a dropdown for search levels