Differences

This shows you the differences between two versions of the page.

--- en:user:list_of_format_options [2015/03/09 01:16] – external edit 127.0.0.1
+++ en:user:list_of_format_options [2016/05/12 01:56] (current) – removed kjdon
@@ Line 1: / Line 1: @@
-====== List of Format Options ======
-The full list of formatting options is shown here.
-See also the description of [[en:user:format_statements|format statements]], and some [[en:user:sample_format_statements | sample format statements]] for miscellaneous tasks.
-<TABAREA tabs="Greenstone3,Greenstone2">
-<TAB>
-^Greenstone3 format statement items^^^
-^Format Statement^Greenstone2 equivalent^Description^
-|     |||
-^//Templates//^^^
-|''<gsf:template match="documentNode"></gsf:template>''|  |Templates are the containers that hold all format statements. The value of ''match'' determines which part of the page content the template applies to.|
-^//Links//^^^
-|''<gsf:link></gsf:link>'' or \\ ''<gsf:link type='document'></gsf:link>''|''[link][/link]''|The HTML link to the Greenstone version of the 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)|
-^//Icons//^^^
-|''<gsf:icon/>'' or \\ ''<gsf:icon type='document'/>''|''[icon]''|An appropriate icon for the document (e.g. book or page icon)|
-|''<gsf:metadata name="srcicon"/>''|''[srcicon]''|An appropriate icon for the original file e.g. Word, PDF icon, if available|
-|''<gsf:icon type='classifier'/>''|  |Bookshelf icon (generally used for classification nodes)|
-|''<gsf:metadata name="thumbicon"/>''|  |Thumbnail for images  (default width 100px, which can be modified in ImagePlugin options)|
-|''<gsf:metadata name="screenicon"/>''|  |For images, a decent-sized version (width of 500px) for displaying the image in a webpage|
-^//Text and Metadata//^^^
-|''<gsf:text/>''|''[Text]''|The document's text|
-|''<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'.|
-^//Conditional//^^^
-|''<gsf:choose-metadata><gsf:metadata name='dc.Title'/><gsf:metadata name='dls.Title'/><gsf:metadata name='Title'/></gsf:choose-metadata>''|''[Or}{[dc.Title], [dls.Title], [Title]}''|A choice of metadata. Will select the first existing one. The metadata elements can have the select, separator and multiple attributes like normal.|
-|''<gsf:choose-metadata> <gsf:metadata name='Title' select='parent'/><gsf:metadata name='Title'/></gsf:choose-metadata>''|''[If}{[parent:Title],[parent:Title], [Title]}''|A choice of metadata. Will select the first existing one.|
-|''<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, 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, has the same attributes as normal.|
-^//Iteration//^^^
-|''<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:metadata attributes =====
-^gsf: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|
-^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.|
-^separator|Any character(s)|when there are multiple values for a metadata field for a document, they are separated by a ", " by default; this allows you to select whatever separator you would like|
-^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'.|
-===== 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|
-^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|
-</TAB>
-<!-- ##################################################################
-########################################################################
-########################################################################
-########################################################################
-##################################################################-->
-<TAB>
-=====Site-wide formatting options=====
-These should be placed in //gsdl/etc/main.cfg//.
-Syntax: **SiteFormat <option-name> <option-value>**
-^Item^Description^
-|HomePageCols int|Set the number of columns used to display collections on the home page. Default: 3|
-|HomePageType pulldown |Display the collection list on the home page as a pulldown menu, rather than using the default table of collection images. This alters the html that appears in the dynamically generated _homeextra_ macro. You can then move this macro around in home.dm. Default: not set|
-=====Collection-specific formatting options=====
-These should be placed in gsdl/collect/<collname>/etc/collect.cfg.
-Syntax: **format <option-name> <option-value>**
-^Item^Description^
-|DocumentImages true/false|If true, display a cover image at the top left of the document page Default: false|
-|DocumentTitles true/false|If DocumentImages is false, and this is true, use DocumentHeading to display the title. Default: true|
-|DocumentHeading formatstring|This is used for a document heading at the top left if DocumentImages is false and DocumentTitles is true. Default: //<nowiki>{Or}{[parent(Top):Title],[Title],untitled}</nowiki>//|
-|DocumentContents true/false| Display table of contents (if document is hierarchical), or next/previous section arrows and "page k of n" text (if document is paged) Default: true|
-|DocumentButtons string|Controls the buttons that are displayed on a document page. Valid options are Detach, Highlight, Expand Text, Expand Contents. Should be separated by <nowiki>|. Default: "Detach|Highlight"</nowiki>|
-|DocumentText formatstring|Format of the text to be displayed on a document page Default: //<nowiki><center> <table width=537> <tr><td>[Text]</td></tr> </table> </center></nowiki>//|
-|DocumentArrowsTop true/false|Display next/previous section arrows at top of document, underneath the navigation bar, on document page Default: false|
-|DocumentArrowsBottom true/false|Display next/previous section arrows at bottom of document page Default: true|
-|DocumentSearchResultLinks true/false|Display //next search result link/previous search result link// at top of a document page Default: false|
-|DocumentUseHTML true/false|If true, each document is displayed in a separate frame. The Preferences page will also change slightly, adding options applicable to a collection of HTML documents. Default: false|
-|NavigationBar pulldown|If set, provides a drop down list in place of the usual navigation bar (that contains search and classifier options). This alters the html that appears in the dynamically generated //_navigationbar_ macro//. Default: not set|
-|AllowExtendedOptions true/false|This allows the entire content of the document page to be controlled by format statements. Use DocumentHeading and DocumentText to format the document. This option prevents the other hard coded stuff (table of contents, buttons etc) from being output. It effectively disables the DocumentContents, DocumentButtons, DocumentImages format options. New format items are provided for use in format statements if AllowExtendedOptions is true (see table below) Default: false|
-|SearchTypes string | Controls whether plain and/or form search interfaces should be available for the collection (for mgpp and lucene collections only). Can be one or both of "plain" and "form". If both are listed, separate with ',', i.e. plain,form. The first one becomes the default search interface style, and the other one is selectable from the preferences page. Default: plain,form|
-|AllowUserComments true/false|Controls whether or not the User Comments area is displayed, where existing user comments on a document are displayed and where users can log in to add their comments to documents.|
-=====Formatting Lists=====
-The standard use of format statements is for the lists in search results, classifiers etc. Here is a list of the various lists available for format, and what they control. Note that classifiers are numbered from 1 upwards, in the order that they appear in the config file.
-^Item^Description^
-|VList|Applies to all vertical lists, unless overridden by a more specific format item. These include search results, classifier lists, and document table of contents|
-|HList|Applies to all horizontal lists. Horizontal lists are often used in classifiers, particularly AZ[Compact][Section]Lists|
-|DateList|Applies to all date lists - these are the vertical lists generated by a DateList classifier.|
-|SearchVList|The vertical list of search results|
-|DocumentVList|The document table of contents|
-|CL1VList|Applies only to the vertical list of classifier 1|
-|CL1HList|Applies only to the horizontal list of classifier 1|
-|CL1DateList|Applies only to the DateList in classifier 1|
-=====Formatstring items=====
-^Item^Description^
-|[link][/link]|Link to the document (Greenstone version)|
-|[href]|The href of the link to the document (Greenstone version), without the &amp;lt;a&amp;gt; tag|
-|[srclink][/srclink]|Link to the original document (only if the original was converted to another form)|
-|[equivDocLink][/equivDocLink]|Link to an associated document (only if the associated document was formed using the plugin option //associate_ext// or //associate_tail_re//).  See the documented example collection [[http://www.nzdl.org/gsdlmod?a=p&amp;p=about&amp;c=assocext-e|Associate File]] for more details.|
-|[icon]|An appropriate icon for a classifier/document node. E.g. bookshelf, book, chapter, page|
-|[srcicon]|An appropriate icon for the original source document. E.g. Word, PDF, PS icon.|
-|[equivDocIcon]|An appropriate icon for a document that has been associated using the plugin option //associate_ext// or //associate_tail_re//. See [equivDocLink] above.|
-|[num]|The document number (position in the search results - useful for debugging)|
-|[numleafdocs]|The number of documents below the current classifier node. This is often used as a test for classifier nodes, as numleafdocs will not be set for documents. This allows different formatting for classifier nodes and document nodes in a hierarchy.|
-|[Text]|The text of the current section|
-|[RelatedDocuments]|Related Documents info (if available). This is a vertical list of Titles (or Subjects if Titles aren't available) that link to the related documents. It is based on "relation" metadata, which is a space separated list of collection,OID pairs.|
-|[highlight][/highlight]|These are used for 'highlighting' (actually bolding) the selected section in a hierarchical table of contents, and the selected node in a classifier. Apart from those two cases, this has no effect. If you actually want to highlight/bold/italicise something in a list, and have it apply to all items in the list, then either use actual html tags, like <nowiki><b></b>, <u></u> and <i></i></nowiki>, or use the //_starthighlight_// and //_endhighlight_// macros (defined in //macros/base.dm//).|
-|[Summary]|Displays Summary metadata if available, otherwise displays a short summary created on the fly.|
-|[DocOID]|The internal identifier of the current section of the document|
-|[DocTopOID]|The (top level) internal identifier of the current document (available 2.72)|
-|[DocRank]|The rank of the current document - used in search results|
-|[DocImage]|The URL to the cover image of the document|
-|[collection]|The directory name of the collection this document is from - useful in cross-collection searching. (version 2.61)|
-|[collection:meta-name]|A collection metadata for the collection this document is from - useful in cross-collection searching. E.g. [collection:collectionname]. This will display in the current language if an appropriate version is available. (version 2.61)|
-|[metadata-name]|The value of this metadata element for the document|
-=====Extended metadata names=====
-There are a few options for displaying metadata. The basic way is to specify e.g. [Title] or [dc.Title]: this displays the value of that particular metadata element for the current document/section. Metadata names can be prefixed by parent: or sibling. The following examples all use Title or Subject metadata, but any metadata could be used, including ones with namespaces (e.g. dc.Title). Any metadata name can also be prefixed by "cgisafe:". This results in the value being formatted so that it is safe to put in a URL.
-^Item^Description^
-|[parent:Title]|The Title of the immediate parent section|
-|[parent(Top):Title]|The Title of the topmost parent section|
-|[parent(All):Title]|All Titles of the parent sections, separated by nothing|
-|[parent(All': '):Title]|All Titles of the parent sections, separated by ": " (or whatever appears inside the ' ')|
-|[child:Subject]|The Subjects of all child nodes of the current node, separated by ' '. (child modifier avilable from version 2.61)|
-|[child(All'xxx'):Subject]|The Subjects of all child nodes of the current node, separated by xxx|
-|[child(2):Subject]|The Subject of the second child of the current node. Child numbering starts from 1.|
-|[child(last):Subject]|The Subject of the last child of the current node. 'first' is also a valid option.|
-|[sibling:Subject]|All Subjects of the current section, separated by " ". This is used for displaying metadata where there is more than one value. [Subject] will just display the first value.|
-|[sibling(All'<nowiki> </nowiki>'):Subject]|All Subjects of the current section, separated by <nowiki> </nowiki>.|
-|[sibling(2):Subject]|The second Subject metadata value for the current node. Numbering starts from 1.|
-|[sibling(last):Subject]|The last Subject metadata value for the current node. 'first' is also a valid option.|
-|[parent:sibling:Subject]|sibling can be combined with parent to give all (or specific) values for the parent node(s). All parent and sibling qualifiers can be used. (since version 2.61)|
-|[child:sibling:Subject]|sibling can be combined with child to give all (or specific) values for the child node(s). All parent and child qualifiers can be used. (since version 2.61)|
-|[cgisafe:parent(Top):Title]|The Title of the topmost parent section, made safe for URLs.|
-|[cgisafe:sibling(All'<nowiki> </nowiki>'):Subject]|All Subjects of the current section, separated by <nowiki> </nowiki>, made safe for URLs.|
-|[format:Date]|A nicely formatted version of Date metadata. Namepsaces are ignored, so can be used with e.g. dc.Date. The dates need to be in yyyymmdd format. |
-|[format:Language]| Turns two letter language codes into their English name, e.g. en becomes English. Namespaces are ignored, so can be used with e.g. dc.Language. |
-=====Extended Formatstring items=====
-These items are only available if AllowExtendedOptions is true.
-^Item^Description^
-|[DocumentButtonDetach]|The Detach button|
-|[DocumentButtonHighlight]|The Highlight button|
-|[DocumentButtonExpandText]|The Expand Text button|
-|[DocumentButtonExpandContents]|The Expand Contents button|
-|[DocTOC]|The table of contents for a hierarchical document, or the next/previous and go to page x bits for a paged document.|
-=====Conditional expressions in formatstrings=====
-^Item^Description^
-|{If}{[metadata], action-if-non-null, action-if null}|If there is a value for this metadata element, then output the first clause, otherwise output the second clause. Either clause is optional: if empty, nothing will be done for that case.This is useful for displaying classifier nodes differently to document nodes: {If}{[numleafdocs],format for classifier,format for document}|
-|{Or}{[metadata], [metadata2], [metadata3]...}|Each metadata is evaluated in turn, and the first one that exists is output Useful for cases where there are different namespaced version of the same metadata, e.g. {Or}{[dc.Title],[dls.Title],[Title],Untitled}. The last item can be plain text.|
-|nested If/Or|{Or} can have another conditional as its final option, eg {Or}{[BookTitle],[Title],{If}{[XXX],aaa,bbb} }. The following is not valid: {Or}{[BookTitle],[Title]{If}{[XXX],aaa,bbb} }. {If} can have nested conditionals at either true/false option. eg. {If}{[numleafdocs],[Title],[BookTitle]{If}{[Subject],[Subject],unclassified} } |
-|{If}{[metadata] op value, action-if-true, action-if-not-true}|Can do tests on metadata values. These can be string comparisons, or numeric comparisons. Valid operators are:|
-^String^Numeric^Meaning^
-|eq|==|equals|
-|ne|!=|not equals|
-|gt|>|greater than|
-|ge|>=|greater than or equal to|
-|lt|<|less than|
-|le|<=|less than or equal to|
-|sw| |starts with|
-|ew| |ends with|
-//Note that only eq and ne are available for Greenstone versions 2.60 and earlier.//
-</TAB></TABAREA>