====== 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 [[en:user:gs3_format_statements|format statements]], and some [[en:user:gs3_sample_format_statements | 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 name^Values^Format^Description^
| ||||
|hideStatus|true|search|If set to true, will hide the line 'displaying 0 to 20 of 40 documents' in the search results|
|[[rss|RSS]]|true| |If set to true, will add a RSS Feed link to the collection|
|turnstyleClassifiers|false|browse|By 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.|
|mapEnabled|true|display,search,browse| |
|mapEnabledOpenLayers| ?? header.xsl|
|panoramaViewerEnabled|true|browse,search| |
|facetTableRows|integer|search| |
|sectionExpandCollapse|true|display|? check if on when true or false|
|backToTopLinks| |display|?|
|sideBar|false |display|If false will not display any of the right side bar features, including cover image, search term highlighting checkbox, table of contents etc |
|disableZoom|true|display| |
|disableSearchTermHighlighting|true|display|If set to true, will not highlight search terms in the text, and will not display the on/off button for highlighting|
|coverImage|true|display| |
|TOC|true|display| |
|viewSelection|false|display|If false, will not show the text/image/default view selector for paged image documents. |
|slideShow|false|display|If false, will not display the slideshow option for paged image documents |
|[[user_comments|allowUserComments]]|true|display|If 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)|
|[[en:user_advanced:web_editor|allowDocumentEditing]]|true|display|If 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)|
|[[en:user_advanced:web_editor|allowMapGPSEditing]]|true|display|If 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
<code>
<paramDefault name="matchMode" value="all"/>
</code>

You can use this to set things like:
  * turn stemming on by default for mgpp collections: <code><paramDefault name="stem" value="1"/></code>
  * return all hits in one page instead of paging the results: <code><paramDefault name="hitsPerPage" value="-1"/></code>

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? =====
==== Links ====

^Format Element^Greenstone2 equivalent^Description^
|     |||
|''<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 Element^Greenstone2 equivalent^Description^
|     |||
|''<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 Element^Greenstone2 equivalent^Description^
|     |||
|''<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 Attribute^Possible Values^Description^
|select| |Select a different node or set of nodes, relative to the current node. Only valid for documentNode templates, not in classifierNodes.|
|:::|current|The current section (this is the default type; if ''select'' is not specified, the current section is assumed)|
|:::|parent|The immediate parent section|
|:::|ancestors|All the parents back to the root (topmost) section|
|:::|root|The root or topmost section|
|:::|siblings|All the sibling sections|
|:::|children|The immediate child sections of the current section|
|:::|descendents|All the descendent sections (NOT YET IMPLEMENTED)|
|pos|first, 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)|
|:::|classifiedBy|If 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.|
|type|collection|Gets 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 [[en:user:gs3_sample_format_statements|here]] for an example using prefix and suffix.

^Modifier^Example^Description^
|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 Attribute^Possible Values^Description^
|format|formatDate|turns '20040201' into '01 February 2004' (in a language dependent manner)|
|:::|formatLanguage|turns 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 Attribute^Possible Values^Description^
|hidden|true|If true, then the metadata will be retrieved from the server, but not displayed at that point. |


==== Collection/Interface Text Strings ====

These will be displayed in the current interface language (if available), otherwise in the default language.

^Format Element^Greenstone2 equivalent^Description^
|     |||
|''<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:interfaceText name='xxx' propertyFile='file_name'/>'' | | Display the xxx string from the //<file_name>.properties// file (in web/WEB-INF/classes) (Greenstone version 3.10 and later)|
|''<gsf:collectionText name='xxx'/>''|  |Display the xxx from the current collection's //interface_custom.properties// file (found in resources folder inside the collection) |
|''<gsf:collectionText name='xxx' propertyFile='file_name'/>''|  |Display the xxx from the current collection's //<file_name>.properties// file (found in resources folder inside the collection) |

==== Miscellaneous Things ====
^Format Element^Greenstone2 equivalent^Description^
|     |||
|''<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 Element^Greenstone2 equivalent^Description^
|     |||
|''<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 Element^Greenstone2 equivalent^Description^
|     |||
|''<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 Attribute^Possible Values^Description^
|select|current|The current section (this is the default type; if ''select'' is not specified, the current section is assumed)|
|:::|parent|The immediate parent section|
|:::|ancestors|All the parents back to the root (topmost) section|
|:::|root|The root or topmost section|
|:::|siblings|All the sibling sections|
|:::|children|The immediate child sections of the current section|
|:::|descendents|All the descendent sections|
|type|collection|Collection level metadata rather than document level metadata|
|separator|Any character(s)|This will be output between each value|
|sort|true|Sort the metadata values (alphabetically, ascending order)|

=== gsf:sort attributes ===

^gsf:sort Attribute^Possible Values^Description^
|select|Expression|Defines the sort key. The default is the string value of the node. Not so useful in this context.|
|order|ascending/descending|Defines sort order|
|case-order|upper-first/lower-first|Defines whether upper-case letters are to be sorted before or after lower-case letters. Default is language dependent.|
|lang|language code|Defines the language whose sorting conventions are to be used|
|data-type|text/number/data-type name|Defines 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
<code>
<xsl:value of select="util:fname(args)"/>
</code>
args is a comma separated list of args. They can be XSLT variables, numbers, strings, XSLT elements/attributes.

For example:
<code>
   <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)"/>
</code>

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.