Greenstone Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
======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 ''$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.

==== 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:
<code>
<xsl:template match="/page">
....
   <xsl:call-template name="coll-description"/>
</xsl:template>

<xsl:template name="coll-description">
  <gslib:collectionDescriptionTextAndServicesLinks/>
</xsl:template>
</code>

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,
<code>
<?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>
</code>

==== 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 ''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.


===== Creating a new interface=====
{{ :en:exampleinterface.png?direct&400|}}
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 [[#Interface configuration file|''interfaceConfig.xml'']] file. From this point, you have two options:
  * Creating an independent interface
  * Using a "base" interface

==== Independent 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.

==== Base interface ====

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:

<code xml>
<interfaceConfig baseInterface="default">
</code>

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

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.
==== 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 ([[en:developer:web_services|more about servlets]]):

<code xml>
	<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>
</code>

\\
Near the bottom of the file, add the following text:

<code xml>
    <servlet-mapping>
	<servlet-name>mylibrary</servlet-name>
	<url-pattern>/home/*</url-pattern>
    </servlet-mapping>
</code>

 The Tomcat server must be restarted for this to take effect.


===== Additional Resources =====
  * [[en:user:gs3_sample_interface_modifications|sample interface modifications]]
  * [[http://wiki.greenstone.org/wiki/images/7/71/Skins_Doc.pdf|Greenstone 3 Interface Transformations Library: Basic Documentation]] //Maxime Roüast//
  * Tutorials on creating a new interface:
    * [[http://wiki.greenstone.org/gsdoc/tutorial/gs3-current/en/new_interface1.htm|Designing a new interface: Part 1]]
    * [[http://wiki.greenstone.org/gsdoc/tutorial/gs3-current/en/new_interface2.htm|Designing a new interface: Part 2]]
    * [[http://wiki.greenstone.org/gsdoc/tutorial/gs3-current/en/new_interface3.htm|Designing a new interface: Part 3]]
    * [[en:user:expanding_on_gs3_customisation_tutorials|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