This version (2014/04/14 11:52) is a draft.
Approvals: 0/1

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 ## 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_

[more…?]

Additional Resources


Navigation
Toolbox