Customizing collections

I've added a new type of classification to my collection. How do I create and add the navigation bar images?
Visit this page and follow the instructions.

How can I customize the appearance of my Greenstone collection?
Since version 2.63, Greenstone has moved from a table-based layout to using CSS (Cascading Style Sheets). The default stylesheet is specified in the style.css file in the "images" directory of your installation, and any change you make there will affect all collections, as well as the home page.

If you want to specify a different style file for a collection, you need to overwrite the "cssfilelink" macro from the style.dm macro file for your collection. There are two ways to do this:

1. Modify (or create) the collection-specific macro file called "extra.dm" in the collection's "macro" directory. (You may need to create this directory). In this file, put the following lines: package Style _cssfilelink_ {/url/to/style/file.css}

2. Since greenstone 2.63, you can set macros on a per-collection basis in the collect.cfg file, with a line such as: collectionmacro Style:cssfilelink "/url/to/style/file.css"

For the URL, you can use greenstone's "_httpimg_" macro to refer to the installation's image directory, or "_httpcollection_" to refer to the collection directory. This means that you can create a directory called "styles" in your collection's directory, put a file in there called "mystyle.css", and set the macro to point to "_httpcollection_/styles/mystyle.css".

If you override the Style:cssfilelink macro, greenstone will still set the background image for several of the HTML page's elements. To completely override all the default style-related settings, you need to specify your own HTML for the "Style:cssheader" macro. For example, in the collect.cfg file: collectionmacro Style:cssheader '   '

An example collection demonstrating how the appearance of a collection can be modified just by changing the CSS is online at http://puka.cs.waikato.ac.nz/cgi-bin/library?a=p&c=style-e&p=about ; you can copy the stylesheets used in that collection - blue and red.

What are the formatting options available for my collection?
Section 2.3 of the Greenstone Developer's Guide discusses how to format the output of your collection. However, the list of options is incomplete. The full list of formatting options is shown here. But for more information about how to use these options, the developer's guide is the place to go.

How can I hyperlink individual metadata elements?
[contributed by Axel Schild] When a metadata element has only one value, it is easy to make a hyperlink out of the value. In the format statement, you just put an  tag around the metadata item, for example:
 *  [dc.Subject] 

When the metadata item has multiple values, and you want to link each one separately, it is a bit more difficult. The following is Axel's solution to his particular problem: display all the Creator elements, each one hyperlinked to a search of that Creator in the Creators index.

Use the format string below in the collect.cfg file (in this case, as part of the "format DocumentText" statement)


 * {If}{[dc.Creator],      Authors:       _httpquery_;[cgisafe:sibling(All:\' ;\'):dc.Creator];[sibling(All:\'_\'):dc.Creator]       }

This statement includes a label definition with the name "AuthorField". "_httpquery_" is a macro which resolves into the http-address of the query page of the collection. "[cgisafe:sibling(All:\' ; \'):dc.Creator]" displays all Creators, separated by ; and with any special characters escaped for use within a web address. [sibling(All:\'_\'):dc.Creator] produces a similar string without escaping the special characters. Notice the different separation symbols, these are needed later on.

Additional changes have to be made in order to make this whole thing work. You further need to change the _header_ or _textheader_ macro in the package of the page the format string will be displayed in (in this case the document package). The change is that _htmlhead_ has to be parametrized with _htmlhead_(onload="ExtractAuthors;"), where ExtractAuthors; is a Javascript function that is called on loading the corresponding page (the document display page). Since you do not want to mess in the standard macro files, create an extra.dm file (in gsdl/collect/ /macros) and override the chosen macro with a collection specific macro. In this example this is done by the code sequence


 * package document  ###document display    ###HTML-Page Header  _textheader_ [c=exacol] {_cgihead_ _htmlhead_(onload="ExtractSubjects;ExtractAuthors;")        }

Now all that is missing is the Javascript function which has to be included into the _pagescriptextra_ macro of the same package. Copy this macro out of the corresponding standard macro file and paste it into your extra.dm file. Make the necessary modification which is in this case


 *  ### Self-made Javascript functions _pagescriptextra_{ function ExtractAuthors \{  var res;  a = AuthorField.outerText.split(";");  resolver = a[0]+"&q=";  b = a[1].split("+%3b+");  c = a[2].split("_");  res = "";  for (i = 0; i < b.length ;i++)    \{       res = res + "" + c[i] + "   ";    \}  AuthorField.outerHTML = res;  \} }

This Javascript function evaluates the string of the defined label, splits it into several strings and composes a string out of those values, which is then set to the "outerHTML" element of the label. "&h=dd0" indicates which index to search in; dd0 should be replaced with the name of the appropriate index. The file gsdl/collect/ /index/build.cfg gives the names of the various indexes.

[update from Katherine Don] I have just tried this with version 2.72, and I needed to make a few changes. Here are my versions of the format statement and extra.dm file (this worked in Mozilla):

Format statement:
 * <p style="background:white;">{If}{[dc.Creator],    <td align=right valign=top>  Authors:      <td align=left valign=bottom><label name=AuthorField id=AuthorField> _httpquery_:[cgisafe:sibling(All:\':\'):dc.Creator]:[sibling(All:\'_\'):dc.Creator]       }

Extra.dm:
 * <p style="background:white;">package document # header overridden for text pages _textheader_ {_cgihead_ _htmlhead_(onload="ExtractAuthors;") _startspacer_         _globallinks_     _imagecollection_        _pagebannerextra_   }  ### Self-made Javascript functions _pagescriptextra_{ function ExtractAuthors \{   var res;   var author = document.getElementById("AuthorField");    a = author.innerHTML.split(":");    resolver = a[0]+"&q=";   b = a[1].split("%3a%5c");   c = a[2].split("_");   res = "";   for (i = 0; i < b.length ;i++)      \{         res = res + "<a href=" + resolver + b[i]+ "&h=dd0&t=0>" + c[i] + "</a> ";      \}   author.innerHTML = res;  \} }

How can I hide the dummy text "This document has no text"?
Instead of [Text] in the DocumentText format statement, use
 * <p style="background:white"> {If}{[Text] ne 'This document has no text. ',[Text]}

If you have installed Greenstone in a different language, then you need to put the correct language string into the If statement. (Since version 2.62.)

How do I suppress the link to the Greenstone text version of a document?
Files such as Word and PDF get converted to HTML during processing, and the original file is stored as an associated file. The default display for search results and browsing lists is two icons: a "text" icon, linking to the Greenstone version of the document, and a pdf or word icon, linking to the original file.

In format statements,
 * [link][icon][/link]</tt> links to the greenstone version
 * [srclink][srcicon][/srclink]</tt> links to the original file

The default VList format statement starts off like
 * <p style="background:white">&lt;td valign=top&gt;[link][icon][/link]&lt;/td&gt; &lt;td valign=top&gt;[srclink][srcicon][/srclink]&lt;/td&gt;</tt>

To suppress either of the icons, you can delete the relevent line from the format statement.

If you are suppressing the link to the original, then remove
 * <p style="background:white">&lt;td valign=top&gt;[srclink][srcicon][/srclink]&lt;/td&gt;</tt>

from the format, and you are done.

If you want to suppress the link to the greenstone version, there are a few complications. Firstly, bookshelf nodes in classifiers must have [link][icon][/link]</tt> to display the bookshelf. And secondly, you may want to display different icons for different document types.

Here are a few scenarios, and the appropriate format to replace the two lines specified above. (For PDF documents, you can substitute any that get converted)


 * Collection with only PDF documents, linking to the original only, and no bookshelves in classifiers:


 * <p style="background:white">&lt;td valign=top&gt;[srclink][srcicon][/srclink]&lt;/td&gt;</tt>


 * Collection with only PDF documents, and bookshelves in classifiers:


 * <p style="background:white">&lt;td valign=top&gt;{If}{[numleafdocs],[link][icon][/link] ,[srclink][srcicon][/srclink]}&lt;/td&gt;</tt>


 * Collection with PDFs for which you want to suppress the text link, and other types where you want to show the text link, and classifiers with bookshelves. The first option will only work if the other document types don't have srcicon metadata.


 * <p style="background:white">&lt;td valign=top&gt;{If}{[srcicon],[srclink][srcicon][/srclink], [link][icon][/link]}&lt;/td&gt;</tt>


 * <p style="background:white">&lt;td valign=top&gt;{If}{[FileFormat] eq "PDF",[srclink][srcicon][/srclink],[link][icon][/link]}&lt;/td&gt;</tt>

How do I add cover images for my documents?
To add a cover image for a document, you need to create the image and add it to the collection in the same folder as the document. It must be a JPEG file (with file extension .jpg) and have the same name as the document. For example, the cover image for farming.doc must be named farming.jpg. Greenstone automatically looks for jpg files of the same name to assign as cover images. (To disable this, you need to add the -no_cover_image option to the plugins.)

Once you have the cover images, setting the format statement DocumentImages</tt> to true</tt> (or enabled in GLI) will result in them being displayed on the document page.

You can also use them as thumbnails in search results and browsing lists, by replacing [icon]</tt> with something like the following in the appropriate format statement:
 * <img src='[DocImage]' height='40'/></tt>

How do I link to other sections of my document?
The _httpdocument_</tt> macro is used to provide a link to a document. For example, if xxx is a document identifier, then the following would link to it: &lt;a href="_httpdocument_&d=xxx"&gt;...&lt;/a&gt; [DocOID]</tt> gives the OID of the current section, while [DocTopOID]</tt> gives the top level OID of the document. For documents without internal sections, these two format elements return the same Identifier. (Note, [DocTopOID] available from version 2.72)

So, <tt>_httpdocument&d=[DocOID]</tt> links to the current section of the document, and <tt>_httpdocument_&d=[DocTopOID]</tt> links to the top section of the document.

Document identifiers can be used in conjunction with some modifiers to get different parts of the document. Modifiers include:
 * .pr parent
 * .rt root (top level) (from 2.72)
 * .ns next sibling
 * .ps previous sibling
 * .fc first child
 * .pc previous child

Here are some examples:

How do I link to the next or previous search result in a document page?
Since Greenstone 2.72

Important Note: Important Note: This option was inoperative in version 2.72 due to a bug in this release. It has been fixed for subsequent releases.

Enable the links Or format DocumentSearchResultLinks true
 * In GLI -> Format Panel -> Format Features -> Choose Feature
 * select DocumentSearchResultLinks
 * click the Add Format button
 * tick the Enabled checkbox
 * In your collection's collect.cfg (in GSDLHOME/collect/your_collection/etc)
 * add

Format the links
 * In document.dm (in GSDLHOME/macros)
 * the next and previous search result link are defined in _nextsearchresult_ and _prevsearchresult_ correspondingly, you can put them wherever you want in a document page and customize their apprearance in style.css (in GSDLHOME/images)
 * the text for those links are defined in _textnextsearchresult_ and _textprevsearchresult_ in english.dm. Add your corresponding language entries in your_language.dm for languages other than English

How do I add a Facebook Like button to a document page?
Add the following to the _content_ macro <iframe src="http://www.facebook.com/plugins/like.php?href=_httpdocument&d=[DocOID]" scrolling="no" frameborder="0" style="border:none; width:450px; height:80px">
 * In document.dm (in GSDLHOME/macros)