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.

Most of an interface is defined by XSLT files, which are stored in $GSDL3HOME/ 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 interface.)

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 the 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 querytools.xsl. The 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. For example 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.

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.

1. 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.
2. 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.
3. 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>

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 interface_name.properties (where 'name' is the interface name, for example, interface_default.properties, or 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 interface_default_fr.properties. 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_fr_CA.properties, XXX_fr.properties, XXX_en_GB.properties, then XXX_en.properties, and finally the default XXX.properties.

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.

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.

A second option is to use a base interface. An interface may be based on an exiting one, for example, the classic interface is based on the default interface. This means that it will use any images, CSS, Javascript, template, etc. from the base one unless overridden in the current one. This is especially useful if your interface will be very similar to an existing interface. (Note that this does not necessarily mean visual similarity. Two interfaces that look very different can still share many of the same files.)

You can set a base interface on the second line of the interfaceConfig.xml file:

<interfaceConfig baseInterface="default">

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.

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

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.

• sample interface modifications
• Greenstone 3 Interface Transformations Library: Basic Documentation Maxime Roüast
• Tutorials on creating a new interface:
  • Designing a new interface: Part 1
  • Designing a new interface: Part 2
  • Designing a new interface: Part 3
  • 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