User Tools

Site Tools


en:user:gs3_list_of_format_options

This is an old revision of the document!


List of Greenstone3 Format Items

This page describes all the things that can go into the <format> element in the collectionConfig.xml file - or can be added in the Format→FormatFeatures pane in GLI.

Format items include options, parameter defaults, and templates. Templates can include standard XSL, but we have defined a set of gsf elements which are shortcuts to XSL.

<gsf:xxx/> formatting items are converted to XSLT by the web/interfaces/default/transform/config_format.xsl file.

See also the description of format statements, and some sample format statements for miscellaneous tasks.

Top Level Elements

There are three main types of format items: options, parameter defaults, and templates. Options give you a switch to turn something on/off or change the look, parameter defaults let you change the default value of eg search parameters (stemming, casefolding etc) while templates let you describe what output you want.

Options

There are a few options available. They are specified by adding <gsf:option name="xxx" value="yyy"/> to the appropriate format element in GLI, or in the collectionConfig.xml file.

Option nameValuesFormatDescription
hideStatustruesearchIf set to true, will hide the line 'displaying 0 to 20 of 40 documents' in the search results
RSStrue If set to true, will add a RSS Feed link to the collection
turnstyleClassifiersfalsebrowseBy default, bookshelves display a plus icon to open up that section of the classifier in place. <gsf:link> will also use ajax to open the current section. If turnstyleClassifiers is set to false, then the plus icon is not displayed and <gsf:link> will open a new page for just that section of the classifier.
mapEnabledtruedisplay,search,browse
mapEnabledOpenLayers ?? header.xsl
panoramaViewerEnabledtruebrowse,search
facetTableRowsintegersearch
sectionExpandCollapsetruedisplay? check if on when true or false
backToTopLinks display?
sideBarfalse displayIf false will not display any of the right side bar features, including cover image, search term highlighting checkbox, table of contents etc
disableZoomtruedisplay
disableSearchTermHighlightingtruedisplayIf set to true, will not highlight search terms in the text, and will not display the on/off button for highlighting
coverImagetruedisplay
TOCtruedisplay
viewSelectionfalsedisplayIf false, will not show the text/image/default view selector for paged image documents.
slideShowfalsedisplayIf false, will not display the slideshow option for paged image documents
allowUserCommentstruedisplayIf set to true, will allow users to add comments to public collections. Users need not have editing permissions for a collection they wish to add comments to. They just need to have an account on that Greenstone Digital Library. (was AllowUserComments prior to 3.10)
allowDocumentEditingtruedisplayIf set to true (or is absent), will allow authenticated users (that have been assigned the correct group) the ability to edit document text and metadata through the web site. Set this to false to disable document editing. (since 3.09, was AllowDocumentEditing for 3.09)
allowMapGPSEditingtruedisplayIf set to true (or is absent), will allow authenticated users (that have been assigned the correct group) the ability to add and edit GPS data through the web site. Set this to false to disable the Map GPS editing controls. (since 3.10)

Parameter Defaults

Inside a format element you can set default values for parameters, using the following syntax

<paramDefault name="matchMode" value="all"/>

You can use this to set things like:

  • turn stemming on by default for mgpp collections:
    <paramDefault name="stem" value="1"/>
  • return all hits in one page instead of paging the results:
    <paramDefault name="hitsPerPage" value="-1"/>

To see what parameters you have that you can change, you can look at the page source for a query page and see what names and values the form elements have.

These can be added inside the <search> and <display> format statements using GLI or directly editing the collectionConfig.xml file).

Templates

Templates are the containers that hold all format statements. The value of match determines which part of the page content the template applies to. For example, <gsf:template match="documentNode">template definition </gsf:template> matches a documentNode element.

What can go inside a template?

Format ElementGreenstone2 equivalentDescription
<gsf:link></gsf:link> or
<gsf:link type='document'></gsf:link>
[link][/link]The HTML link to the Greenstone version of the current document
<gsf:link OID='xxx'></gsf:link> Link to document with identifier xxx
<gsf:link OIDmetadata='xxx'></gsf:link> Link to document whose identifier is specified by the xxx metadata value of the current document.
<gsf:link type='source'></gsf:link>[srclink][/srclink]The HTML link to the original file for documents that have been converted, e.g. Word,PDF, PS
<gsf:link type='classifier'></gsf:link> A link to a classification node (use in classifierNode templates)
<gsf:link type='classifier' style="static|javascript"></gsf:link> A link to a classification node (use in classifierNode templates). Static will make it a link to a new page for that particular bookshelf. javascript will make the link use javascript to open up that section of the classifier in the current page. Without a style attribute, the default behaviour will be 'javascript' in a VList, and 'static' in an HList.
<gsf:link type='query' [@name='FieldQuery']><params>s1.query=cats&amp;s1.index=TI</params></gsf:link> a link to a search with the specified parameters. Will link to TextQuery search unless the optional name attribute is used. Add qs=1 to link to a quicksearch page rather than the full search page. You can see what parameters are used in a search by going to the search page and submitting a search. The parameters appear in the URL.
<gsf:link type='web'></gsf:link> [weblink][/weblink] Make a link using the weblink and /weblink metadata values
<gsf:link type='page' page='about'></gsf:link> Link to a collection page, in this case the about page
<gsf:link type='rss'></gsf:link> Link to the collection's RSS feed
<gsf:link … target='_blank'> Open the link in a new tab
<gsf:link … title='a tooltip'/> Add a tooltip to a link using the title attribute
<gsf:link … titlekey='key'/> Add a tooltip to a link using the key specified. It will look up the key in the colname.properties file in the collection's resources folder (where colname is the collection's short name). Use this if you wish to translate the tooltip into different languages.
<gsf:link type='equivdoc'/> Link to equivalent documents

Icons and Images

Format ElementGreenstone2 equivalentDescription
<gsf:icon/> or
<gsf:icon type='document'/>
[icon]An appropriate icon for the document (e.g. book or page icon)
<gsf:icon type='classifier'/> Bookshelf icon (generally used for classification nodes)
<gsf:icon type='web'/> Outputs the value of the webicon metadata
<gsf:icon file='xxx.jpg' [select='site']/> Displays the xxx.jpg image from the current interface's images folder
<gsf:icon file='xxx.jpg' select='collection'/> Displays the xxx.jpg image from the current collection's images folder
<gsf:metadata name="srcicon"/>[srcicon]An appropriate icon for the original file e.g. Word, PDF icon, if available
<gsf:metadata name="thumbicon"/> [thumbicon] Thumbnail for images (default width 100px, which can be modified in ImagePlugin options) (uses thumbicon metadata value)
<gsf:metadata name="screenicon"/> [screenicon] For images, a decent-sized version (width of 500px) for displaying the image in a webpage (uses screenicon metadata value)
<gsf:image type='thumb'/> <img src='[Thumb]'/> Thumbnail of an image
<gsf:image type='screen'/> <img src='[Screen]'/> Screen size version of an image
<gsf:image type='source'/> <img src='[SourceFile]'/> Displays the original image
<gsf:image type='cover'/> <img src='[DocImage]'/> Displays the document's cover image (if there is one)
<gsf:image type='cover' height='40'/> [<img src='[DocImage]' height='40'/> <gsf:image> can take any html img attributes - they will be copied to the resulting <img> element.

Text and Metadata

Format ElementGreenstone2 equivalentDescription
<gsf:text/>[Text]The text of the current section
<gsf:OID/>[OID]The current document or section's identifier
<gsf:rank/>[rank]The rank of the current document/section (in search results)
<gsf:metadata name='Title'/> or
<gsf:metadata name='Title' select='current'/>
[Title]The value of a metadata element for the current document or section, in this case, Title
<gsf:metadata name='Title' select='select-type' [separator='; ' pos='first']/> A more extended selection of metadata values. The select field can be one of those shown in the table below. There are two optional attributes: separator gives a String that will be used to separate the fields, default is "“,"“, and pos selects one particular value.
<gsf:metadata name='Title' select='parent' />[parent:Title]The Title of the parent of the current document/section
<gsf:metadata name='Title' select='ancestors'/>[parent(All):Title]The Title of all of the parent documents/sections, separated by a comma
<gsf:metadata name='Title' select='root' />[parent(Top):Title]The Title of the top-level document (i.e. in a sectioned document, the Title of the document itself)
<gsf:metadata name='Title' select='ancestors' separator=': ' />[parent(All': '):Title]The Title of all of the parent documents/sections, separated by ": "
<gsf:metadata name='Title' separator=': ' />[sibling(All': '):Title]The Title of all of the current document's/section's siblings, separated by ": "
<gsf:metadata name='dc.Date,Date'/> All dc.Dates and Dates (in the order that they come out of the database.
<gsf:metadata name='dc.Date,Date' pos='classifiedBy'/> The actual date (dc.Date or Date) that was used to classify the document into its current position in the classifier (List -metadata dc.Date,Date)
<gsf:metadata name='Date' format='formatDate'/> The value of a metadata element for the current document, formatted in some way. formatDate turns '20040201' into '01 February 2004' (in a language dependent manner).
<gsf:metadata name='Language' format='format-Language'/> The value of a metadata element for the current document, formatted in some way. format-Language: turns language code into language name, e.g. 'en' into 'English'.

gsf:metadata modifiers

By default, gsf:metadata displays all values of the specified metadata field, for the current page or section of a document. You can change which page or section's metadata is output using the select attribute. And you can choose just a single value using the pos attribute. Or you can set type='collection' to retrieve collection level metadata.

gsf:metadata AttributePossible ValuesDescription
select Select a different node or set of nodes, relative to the current node. Only valid for documentNode templates, not in classifierNodes.
currentThe current section (this is the default type; if select is not specified, the current section is assumed)
parentThe immediate parent section
ancestorsAll the parents back to the root (topmost) section
rootThe root or topmost section
siblingsAll the sibling sections
childrenThe immediate child sections of the current section
descendentsAll the descendent sections (NOT YET IMPLEMENTED)
posfirst, last or any number (1,2,3,etc.) gsf:metadata by default displays all values of a metadata field for a document; this allows you to select which one you want (e.g. the first, second, 8th one listed)
classifiedByIf the document has multiple values for the metadata element that you have classified on, this allows you to select the value that was used to classify the document into its current position in the classifier. Only useful in documentNode templates for a classifier.
typecollectionGets collection level metadata rather than document level. select attributes not useful with this type

Formatting multiple values

When multiple values are to be displayed, they are separated by ", ", by default. You can change this using separator, suffix and prefix. These can be attributes to the gsf:metadata element, or child nodes. Attributes may only contain plain text, whereas the child nodes can contain HTML. The attribute version takes precedence over the child node version: only the attribute will be used if both are present. See here for an example using prefix and suffix.

ModifierExampleDescription
separator<gsf:metadata separator=": "/>Puts colon space between metadata values
<gsf:metadata><separator><br/></separator></gsf:metadata>will break each value with a new line
prefix<gsf:metadata prefix="+++"/>Puts +++ in front of each metadata value
<gsf:metadata><prefix>subject: </prefix></gsf:metadata>Puts subject: in front of each metadata value
suffix<gsf:metadata suffix="+++"/>Puts +++ after each metadata value
<gsf:metadata><prefix>(xxx)</prefix></gsf:metadata>Puts (xxx) after each metadata value

Some metadata values can have added formatting applied.

gsf:metadata AttributePossible ValuesDescription
formatformatDateturns '20040201' into '01 February 2004' (in a language dependent manner)
formatLanguageturns language code into language name, e.g. 'en' into 'English'.

Hidden metadata

Finally, you may want to retrieve the metadata from the server, but not display it directly in the page. Maybe it will be processed by Javascript later on. The page XML will contain metadata values dependent on which gsf:metadata elements are in the XSLT for the page. You can add a hidden metadata to get the value into the page XML.

gsf:metadata AttributePossible ValuesDescription
hiddentrueIf true, then the metadata will be retrieved from the server, but not displayed at that point.

Text Strings

Format ElementGreenstone2 equivalentDescription
<gsf:displayText name='xxx'/> Will display the xxx displayItem from the collection's collectionConfig.xml file. If that is not found, will try to look for xxx from the interface's property file.
<gsf:displayItem name='xxx'/> Display the xxx displayItem from the collection's collectionConfig.xml file.
<gsf:interfaceText name='xxx'/> Display the xxx interface text string (from interface_default.properties in web/WEB-INF/classes)
<gsf:collectionText name='xxx'/> Display the xxx from the current collection's colname.properties file (found in resources folder inside the collection)

Miscellaneous Things

Format ElementGreenstone2 equivalentDescription
<gsf:cgi-param name='query'/> _cgiargq_The value of a cgi param (in this case will get s1.query from the cgi arguments)
<gsf:variable name='xxx'>value</gsf:variable> Will output an <xsl:variable> into the transform result. Also, sets gs.variables.xxx = value, which is available for use in javascript code.
<gsf:html>&lt;li&gt;</gsf:html> <li>Sometimes you want to output some HTML that is not valid XML in the config file. For example, adding <li> and </li> as prefix and suffix to a list of metadata values. In the final HTML it will be valid XML, but in the template it won't be. So use escaped < and > and enclose the text in <gsf:html> tags.

Conditional

Format ElementGreenstone2 equivalentDescription
<gsf:choose-metadata><gsf:metadata name='dc.Title'/><gsf:metadata name='dls.Title'/><gsf:metadata name='Title'/><gsf:default>Untitled</gsf:default></gsf:choose-metadata>[Or}{[dc.Title], [dls.Title], [Title], Untitled}A choice of metadata. Will select the first existing one. The metadata elements can have the select, separator and multiple attributes like normal. <gsf:default> gives output if none of the metadata elements are defined.
<gsf:if-metadata-exists><gsf:metadata name="abstract"/><gsf:if>output this if there is an abstract</gsf:if><gsf:else>output this if there is no abstract</gsf:else></gsf:if-metadata-exists> {If}{[abstract],output this if there is an abstract,output this if there is no abstract}A simpler version of a switch based on whether a metadata value exists or not
<gsf:switch><gsf:metadata name='Subject'/><gsf:when test='exists'><td><gsf:metadata name='Subject'/></td></gsf:when></gsf:switch>[If}{[Subject],<td>[Subject]</td>}Switch on the existence or value of a particular metadata - the metadata is specified in gsf:metadata, and has the same attributes as normal.
<gsf:switch preprocess='preprocess-type'>
<gsf:metadata name='Title'/>
<gsf:when test='test-type' test-value='xxx'>…</gsf:when>
<gsf:when test='test-type' test-value='yyy'>…</gsf:when>
<gsf:otherwise>…</gsf:otherwise>
</gsf:switch>
Switch on the value of a particular metadata - the metadata is specified in gsf:metadata, and has the same attributes as normal.

Preprocess Options

The preprocess attribute specifies something to do to the metadata value before performing the test. For example, you may want to lower case the value before comparing it to your text string. That way you don't need to worry about handling case variation in the metadata value.

Preprocess Description
toLower Make the value lower case
toUpper Make the value all upper case
tidyWhiteSpace Replace all sequences of white space with a single space character.
stripWhitespace Remove all whitespace characters
formatDate Converts 20020101 to 01 January 2002 (language dependent)
formatLanguage Converts 'en' to 'English' (language dependent)
cgiSafe Replace space with %20
formatBigNumber ???

Test options

Sometimes you may want to output different things depending on the value of the metadata element. There are many tests you can make on the metadata value, listed below, which are specified using the test attribute. They all take a second parameter, specified using the test-value attribute, which is the value to compare to (with the exception of exists, which needs no test value). The preprocessing option, if specified, is carried out first, before performing the test.

Test Description
equals Returns true if the metadata value equals the specified test value
notEquals Returns true if the metadata value does NOT equal the specified test value
exists Returns true if there is a value for the metadata field
contains Returns true if the test value can be found inside the metadata value
startsWith Returns true if the metadata value starts with the specified test value
endsWith Returns true if the metadata value ends with the specified test valu
lessThan Returns true if the metadata value is lexicographically less than the test string
lessThanOrEquals Returns true if the metadata value is lexicographically less than or equal to the test string
greaterThan Returns true if the metadata value is lexicographically greater than the test string
greaterThanOrEquals Returns true if the metadata value is lexicographically greater than or equal to the test string
oidIsMatchOrParent Used for comparing OIDs. Returns true if the metadata value equals the test value, or is a parent of it. For example, b17mie.1.2 is a parent of b17mie.1.2.1

Note, these preprocessing and test options are defined in greenstone3/src/java/org/greenstone/gsdl3/util/XSLTUtil.java.

Iteration

Format ElementGreenstone2 equivalentDescription
<gsf:foreach-metadata name='Subject'>
<b><gsf:meta-value/></b>
</gsf:foreach-metadata>
Iterate over metadata values and output each one. Use this instead of <gsf:metadata> if you want to put HTML around each value, which you can't do using a separator. <gsf:meta-value/> is a placeholder for where the metadata value is to go in the output.
<gsf:foreach-metadata name='Subject'>
<gsf:sort/>
<b><gsf:meta-value/></b>
</gsf:foreach-metadata>
Iterate over each sorted metadata item. For a basic sort, use @sort='true' in the <gsf:foreach-metadata> element. For a more specific sort, use the <gsf:sort> element which mirrors the <xsl:sort> element. For attributes, see below.

gsf:foreach-metadata attributes

gsf:foreach-metadata AttributePossible ValuesDescription
selectcurrentThe current section (this is the default type; if select is not specified, the current section is assumed)
parentThe immediate parent section
ancestorsAll the parents back to the root (topmost) section
rootThe root or topmost section
siblingsAll the sibling sections
childrenThe immediate child sections of the current section
descendentsAll the descendent sections
typecollectionCollection level metadata rather than document level metadata
separatorAny character(s)This will be output between each value
sorttrueSort the metadata values (alphabetically, ascending order)

gsf:sort attributes

gsf:sort AttributePossible ValuesDescription
selectExpressionDefines the sort key. The default is the string value of the node. Not so useful in this context.
orderascending/descendingDefines sort order
case-orderupper-first/lower-firstDefines whether upper-case letters are to be sorted before or after lower-case letters. Default is language dependent.
langlanguage codeDefines the language whose sorting conventions are to be used
data-typetext/number/data-type nameDefines whether values are sorted alphabetically, numerically, or using a user-defined data type

Utility Functions

There are many utility functions defined in src/java/org/greenstone/gsdl3/util/XSLTUtil.java. Some of these are used behind the scenes, as part of gsf elements. For example, ….

They can be called explicitly using

<xsl:value of select="util:fname(args)"/>

args is a comma separated list of args. They can be XSLT variables, numbers, strings, XSLT elements/attributes.

For example:

   <xsl:variable name="raw_date"><gslib:collectionMeta name="buildDate"/></xsl:variable>
   The collection was last built on <xsl:value-of select="util:formatTimeStamp($raw_date, 0, 0, /page/@lang)"/>

This code is getting the buildDate timestamp from collection metadata. Then it is formatting it using the formatTimeStamp function. This function takes 4 arguments:

  • the timestamp - here we use the raw_date variable we have just made
  • an integer for timestamp type - 0 is seconds, 1 is milliseconds
  • an integer for output format tupe - 0 is date, 1 is time, 2 is date and time, 3 is days ago
  • the language code for which language you want the output in - here we use the attribute from the page element.

We could change this output to days ago: The collection was last built <xsl:value-of select="util:formatTimeStamp($raw_date, 0, 3, /page/@lang)"/> days ago.

Additional Notes

Some of these options (<gsf:html>; using <gsf:metadata> inside the parameters for a search link) are not available in the 3.07 release. If you are using 3.07, you can download an updated config_format.xsl file. Rename your current greenstone3/web/interfaces/default/transform/config_format.xsl (so that you can put it back if something goes wrong), and copy this one into its place.

en/user/gs3_list_of_format_options.1571694085.txt.gz · Last modified: 2019/10/21 21:41 (external edit)