====== 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:

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

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,

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

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:

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

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:

<code>
_imagecollection_[v=1]{_imagecollectionv_}
</code>

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,

<code>
_textimagehome_ {Home Page}
</code>

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

<code>
_textimagehome_ [l=de] {Hauptaseite}
</code>

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.

<imgcaption figure_part_of_the_aboutdm_macro_file|%!-- id:714 --%Part of the //about.dm// macro file ></imgcaption>
<code>
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_
}
</code>



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 =====
<code>
 _package:macroname_
</code>
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 [[https://www.owasp.org/index.php/XSS_%28Cross_Site_Scripting%29_Prevention_Cheat_Sheet|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 
<code>
 _If_(_cgiargs_,_trueStatement_,_falseStatement_)
</code>
  * 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 =====

  * [[en:user:collection_specific_macros|Collections-specific macros]]
  * [[en:user_advanced:using_expand_macros_script|Using the expand_macros.pl script]]
  * [[en:user:sample_macros|Sample macros]]
    * [[en:user:sample_macros#Adding a new page to a Greenstone library]]
    * [[en:user:sample_macros#Adding a Language Selection Box to each page]]
    * [[en:user:sample_macros#Changing the logo on the front page of the library]]
    * [[en:user:sample_macros#Adding an 'I'm feeling lucky' facility]]
    * [[en:user:sample_macros#Add footer that sticks to the bottom of the page and has two columns]]
  * [[http://wiki.greenstone.org/wiki/images/c/cb/Customizing_GSDL.pdf|Easy Ways to Customize the Display of Greenstone Pages]] //K Rajasekharan// and //K M Nafala//