Part of the Greenstone Beginner's Guide
Customizing the look of your Greenstone library and collections
requires you to know how and where to make the changes that you want. This page
provides some insight, telling you where to go if you want to make changes to the layout,
the style, the display of your documents and lists, etc.
There are a few pages that, though not directly concerned with customization, can be very useful during the process:
Sites and interfaces contain the content and presentation information, respectively, for the digital library.
A site is comprised of a set of collections (and possibly some site-wide services). A site can be seen as a collection of collections. You can have multiple separate sites in a single Greenstone3 installation.
An interface is a set of images, Css and Javascript along with a set of XSLT files used for translating XML output from the library into an appropriate form – HTML generally. XSLT (and therefore every Greenstone interface) is built around things called templates, which will tell Greenstone how to display pages depending on the content for that page (e.g. a document's metadata, the names of the collections in your site, what browsing classifier have been defined, etc.).
A library is a combination of one site with one interface - in technical terms, each library is a servlet.
You can create any number of interfaces in your Greenstone3 installation, which is especially useful for when you want to present the same content in different ways. In addition, multiple sites can make use of the same interface. The servlet configuration determines which libraries will be presented.
If all of that sounds really confusing, don't worry! Unless you want to make extreme changes to an interface (or define your own), you can largely avoid XSLT.
While the interfaces (i.e. the files that dictate how each page looks) themselves are separate from the content, you can override any part of the interface on either the site or collection level. In fact, Greenstone3 provides some features to make modifying or overriding an interface easier:
gsf syntax is XML-based. (If you don't know XML, don't worry; it looks and acts very similarly to HTML.)Now that you know the basics of using and customizing Greenstone, there are a few other features, functions, and resources you should be aware of. The final section of this Beginner's Guide presents additional Greenstone topics.
Customization can be done at either collection level or library level. Any changes made in the GLI will only effect the current collection (though, you can copy formatting into future collections by basing them on another collection). Other methods of customization can be enacted on a collection or library basis.
The content of a Greenstone collection is handled by format statements,
which can be modified in the GLI (under Format → Format Features). So, if you want to change how documents appear
in browsing pages, search results, and on individual document pages, format statements are where
to make changes.
Greenstone2 is built on macros, which look like _this_ and basically stand for
a block of text or code.
A large part of Greenstone 2's security against cross-site scripting (XSS) is implemented in Greenstone 2.87+ in the macros files. This means that if you are customising it by reusing macros such as in new forms or paragraphs, you will need to be aware of how to do so in a secure way.
Every macro variable now has additional variants of itself: variants that are safe to use in an HTML context, in an HTML attribute context, CSS context, URL context, JavaScript context and SQL context.
The additional variants of each variable are denoted by the suffixes:
Htmlsafe, Attrsafe, Csssafe, Urlsafe, Jssafe, Sqlsafe
The variable name suffixes of these additional variants' indicate the context in which each is to be used.
For example, the _cgiargq_ variable has the following variants:
_cgiargqHtmlsafe_ _cgiargqAttrsafe_ _cgiargqCsssafe_ _cgiargqUrlsafe_ _cgiargqJssafe_ _cgiargqSqlsafe_
In reusing existing macros when you want to customise Greenstone 2 macro files, carefully select the appropriate variant of the variable you want depending on the context in the file where that variable needs to be used.
In some cases, this can be straightforward: if it is going into an HTML attribute, use the Attrsafe variant. If it's going to be (part of) a URL, use the Urlsafe version. If it goes into regular JavaScript code, use the Jssafe version, etc.
An example of a more complex case would be where Javascript produces HTML. If the variable is part of the HTML page produced by some JavaScript code, you need to use the Htmlsafe variant instead of the Jssafe variant.
If you make your customisations consciously and sensibly, your modified macro files will continue to keep Greenstone 2's security intact.
For more information:
Now that you know the basics of using and customizing Greenstone, there are a few other features, functions, and resources you should be aware of. The final section of this Beginner's Guide presents additional Greenstone topics.