Greenstone 2 Macros

Macros define either strings on the interface or variables utilized in C++ codes. By using macros, users can easily customize the user interface without changing any C++ code.

The entire Greenstone user interface is controlled by macros which reside in the GSDLHOME/macros directory. They are written in a language designed especially for Greenstone, and are used run time to generate web pages. Translating the macro language into html is the last step in displaying a page. Thus changes to a macro file affect the display immediately, making experimentation quick and easy. All macro files used by Greenstone are listed in GSDLHOME/etc/main.cfg and are loaded every time it starts. One exception to this is when using the Windows Local Library; in this case it is necessary to restart the process.

Web pages are generated on the fly for a number of reasons, and the macro system is how Greenstone implements the necessary flexibility. Pages can be presented in many languages, and a different macro file is used to store all the interface text in each language. When Greenstone displays a page the macro interpreter checks a language variable and loads the page in the appropriate language (this does not, unfortunately, extend to translating document content). Also, the values of certain display variables, like the number of documents found by a search, are not known ahead of time; these are interpolated into the page text in the form of macros.

The macro file format

Macro files have a .dm extension. Each file defines one or more packages, each containing a series of macros used for a single purpose. Like classifiers and plugins, there is a basis from which to build macros, called base.dm ; this file defines the basic content of a page.

Macros have names that begin and end with an underscore, and their content is defined using curly brackets. Content can be plain text, html (including links to Java applets and JavaScript), macro names, or any combination of these. This macro from base.dm defines the content of a page in the absence of any overriding macro:

_content_ {<p><h2>Oops</h2>_textdefaultcontent_}

The page will read “Oops” at the top, and _textdefaultcontent_, which is defined, in English, to be The requested page could not be found. Please use your browsers 'back' button or the above home button to return to the Greenstone Digital Library, and in other languages to be a suitable translation of this sentence.

_textdefaultcontent_ and _content_ both reside in the global package because they are required by all parts of the user interface. Macros can use macros from other packages as content, but they must prefix their names with their package name. For example,

_collectionextra_ {This collection contains _about:numdocs_ documents. It was last built _about:builddate_ days ago.)

comes from english.dm, and is used as the default description of a collection. It is part of the global package, but _numdocs_ and _builddate_ are both in the about package—hence the about: preceding their names.

Macros often contain conditional statements. They resemble the format string conditional described above, though their appearance is slightly different. The basic format is _If_(x,y,z), where x is a condition, y is the macro content to use if that condition is true, and z the content if it is false. Comparison operators are the same as the simple ones used in Perl (less than, greater than, equals, not equals). This example from base.dm is used to determine how to display the top of a collection's about page:

_imagecollection_ {
       _If_( "_iconcollection_ " ne "",
                 <a href = "_httppageabout_ "> 
                         <img src = "_iconcollection_ " border = 0>
                         </a>,
                 _imagecollectionv_)
}

This looks rather obscure. _iconcollection_ resolves to the empty string if the collection doesn't have an icon, or the filename of an image. To paraphrase the above code: If there is a collection image, display the About this Collection page header (referred to by _httppageabout_) and then the image; otherwise use the alternative display _imagecollectionv_.

Macros can take arguments. Here is a second definition for the _imagecollection_ macro which immediately follows the definition given above in the base.dm file:

_imagecollection_[v=1]{_imagecollectionv_}

The argument [v=1] specifies that the second definition is used when Greenstone is running in text-only mode. The language macros work similarly—apart from english.dm, because it is the default, all language macros specify their language as an argument. For example,

_textimagehome_ {Home Page}

appears in the English language macro file, whereas the German version is

_textimagehome_ [l=de] {Hauptaseite}

The English and German versions are in the same package, though they are in separate files (package definitions may span more than one file). Greenstone uses its l argument at run time to determine which language to display.

package about
##############################################
# about page content
###############################################
_pagetitle_ {_collectionname_}
_content_ {
<center>
_navigationbar_
</center>
_query:queryform_
<p>_iconblankbar_
<p>_textabout_
_textsubcollections_
<h3>_help:textsimplehelpheading_</h3>
_help:simplehelp_
}
_textabout_ {
<h3>_textabcol_</h3>
_Global:collectionextra_
}

As a final example, Figure <imgref figure_part_of_the_aboutdm_macro_file> shows an exerpt from the macro file about.dm that is used to generate the “About this collection” page for each collection. It shows three macros being defined, _pagetitle_, _content_ and _textabout_.

Using macros

Macros are powerful, and can be a little obscure. However, with a good knowledge of html and a bit of practice, they become a quick and easy way to customise your Greenstone site.

For example, suppose you wanted to create a static page that looked like your current Greenstone site. You could create a new package, called static, for example, in a new file, and override the _content_ macro. Add the new filename to the list of macros in GSDLHOME/etc/main.cfg which Greenstone loads every time it is invoked. Finally, access the new page by using your regular Greenstone URL and appending the arguments ?a=p&p=static (e.g. http://servername/cgi-bin/library?a=p&p=static).

To change the “look and feel” of Greenstone you can edit the base and style packages. To change the Greenstone home page, edit the home package (this is described in the Greenstone Digital Library Installer's Guide). To change the query page, edit query.dm.

Experiment freely with macros. Changes appear instantly, because macros are interpreted as pages are displayed. The macro language is a useful tool that can be used to make your Greenstone site your own.

Where and how to define macros

Macros can be explicitly defined in a macro file which is a .dm file, in greenstone/macros
- english.dm and english2.dm contain all the text strings of the interface, in English. french.dm, spanish.dm etc contain the same in other languages.
- query.dm contains macros defining html utilized on the search pages.
Macros are grouped into packages in a macro file.
- eg. package Global, package home in the english.dm file
One macro can include other macros.
Macros can be generated during the run time by C++ codes.

Reference a macro

 _package:macroname_

eg. _home:textpagetitle_ The package name can be omitted if you are referencing a macro from the same package. Check a macro from the defined package. If this macro is not existing, a warning message "macro is not defined" is returned.

How macros work

Once an action (eg. a=p&p=home) is sent to cgi-bin/library, external macros used for all actions are firstly defined (eg. navigation bar). Then the internal macros of this paticular action is defined. All macros are stored in a kind of hash structure.
Set macro(macroname,package,content) when the action is executed.

OutputStream«converter«display«"macros+text"

Finally display results on the web page.

Macros used on a general page

_:header_
_:content_
optional dynamic content which is not set as macros, but output directly
_:footer_

Notes on using cgiarg macros

cgiarg macros are macros that store URL parameters. For instance, one of the URL parameters is c, which specifies a collection. When the collection is the Greenstone Demo collection, this URL parameter is seen in the URL as c=demo. The associated cgiarg macro for the c parameter is _cgiargc_. Similarly, the query value parameter is _cgiargq_ and is associated with the q parameter when a search has been performed.

Greenstone sets not only the cgiarg macros and the special _decodedcompressedoptions_, but also the web-encoded variants for each of these. The variants available for each of these macros are safely encoded for an HTML context, for HTML attributes, for Javascript, for URLs, for SQL and for CSS. The first four are the ones that tend to be used in macro files (the *.dm files in the macros folder). The suffixes for the variants are always: Htmlsafe, Attrsafe, Jssafe, Urlsafe, Sqlsafe, Csssafe.

For instance, if the plain cgiarg macro is _cgiargc_, then the encoded variants that Greenstone sets for this and which are available for you to use are: _cgiargcHtmlsafe_, _cgiargcAttrsafe_, _cgiargcJssafe_, _cgiargUrlsafe_, _cgiargcSqlsafe_, _cgiargcCsssafe_.

For web security reasons, if you're writing your own macros and will be dealing with cgiarg macros or the _decodedcompressedoptions_ macro, it is important to use the correct encoded variant of this. The one you choose depends on the context in which you place it, which can be HTML, HTML attribute, Javascript, URL, SQL or CSS. The rules for choosing which variant of the macro to use are explained at OWASP's XSS (Cross Site Scripting) Prevention Cheat Sheet.

For Greenstone-specific examples of how and when (in what contexts) to use the web-encoded variants of a cgiarg macro or the _decodedcompressedoptions_ macro, it is useful to look in a macro file and search for "cgiarg" in it.

Miscellaneous things

macro IF statement syntax

 _If_(_cgiargs_,_trueStatement_,_falseStatement_)

String comparison: (eq,ne,lt,gt,sw,ew)
- eg. _cgiargc_ eq "demo" (the collection is demo)
Numeric comparison (!=,==,<,>,>=,⇐)
Edit main.cfg file to load a new macro file
macroprecedence "c,v,l"

[more…?]

Frequently used macros:

_gwcgi_("/cgi-bin/library")

_httpprefix_("/gsdl")

_httpimg_("/images")

_gsdlhome_

_navigationbar_

_homeextra_

_thisOID_

_compressedoptions_

_cgiargc_