greenstone.org
greenstone wiki
greenstone trac
planet greenstone

# All about macros

### From GreenstoneWiki

[edit]

## What is a macro

- 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.

[edit]

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

[edit]

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

[edit]

## 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 disply results on the web page.

[edit]

## Macros used on a general page

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

[edit]

## Learn more about macros using the expand_macros.pl script

Thanks to Jens Wille

- get a list of all macros and where they are defined (in order to have macros defined in the c++ source included as well, you may specify the path to your greenstone source directory; see the usage information of the script for details):

     expand_macros.pl -s '.*'

- get definition of _query:pagescriptextra_

     expand_macros.pl _query:pagescriptextra_

output:

     *** macro: query:pagescriptextra ***

     * query:pagescriptextra [v=0] (/usr/local/gsdl/stable/macros/query.dm, line 68)
       { _If_("_cgiargqt_" eq "1", _formpagescriptextra_, _selectpagescriptextra_) _If_("_cgiarghd_" ne "0",_historypagescriptextra_) } }

- get macros that are used by _query:pagescriptextra_ ('-s' for short output, omit for display of definitions; '-d' for depth, increase to see more levels):

     expand_macros.pl -s -d 2 _query:pagescriptextra_

output:

     *** macro: query:pagescriptextra ***

     * query:pagescriptextra [v=0] (/usr/local/gsdl/stable/macros/query.dm, line 68)
       * query:formpagescriptextra [v=0] (/usr/local/gsdl/stable/macros/query.dm, line 76)
         * query:formfunctions [v=0] (/usr/local/gsdl/stable/macros/query.dm, line 178)
         * query:searchfunctions [v=0] (/usr/local/gsdl/stable/macros/query.dm, line 478)
         * preferences:standardfunctions [v=0] (/usr/local/gsdl/stable/macros/pref.dm, line 82)
         * query:standardfunctions [v=0] (/usr/local/gsdl/stable/macros/query.dm, line 143)
       * query:historypagescriptextra [v=0] (/usr/local/gsdl/stable/macros/query.dm, line 101)
       * query:selectpagescriptextra [v=0] (/usr/local/gsdl/stable/macros/query.dm, line 71)
         * query:dummypagescriptextra [v=0] (/usr/local/gsdl/stable/macros/query.dm, line 72)
         * query:formpagescriptextra [v=0] (/usr/local/gsdl/stable/macros/query.dm, line 76)

- get macros that use "any" _pagescriptextra_ ('-r' for reverse search):

     expand_macros.pl -r _pagescriptextra_

output:

     *** macro: pagescriptextra (reverse) ***

     * Style:globalscripts [v=0] (/usr/local/gsdl/stable/macros/style.dm, line 142)
       { <script> <!-- _imagescript_ _pagescriptextra_ // --> </script> } }

     * homepref:pagescriptextra [v=0] (/usr/local/gsdl/stable/macros/home.dm, line 198)
       { _preferences:pagescriptextra_} }

- get macros whose definitions contain "blank.gif" (a search in the definition contents will be performed if the argument doesn't start, and end, with an underscore (actually, it's a bit more complicated, but that should suffice for the moment); is actually treated as full perl regular expression):

     expand_macros.pl "blank.gif"

output:

     *** query: blank.gif ***

     * collector:iconblank [v=0] (/usr/local/gsdl/stable/macros/collect.dm, line 42)
       { <img src="_httpimg_/blank.gif">} }

- get a macro that is defined in the c++ code (you need to extract a greenstone source archive and point to its base location, either via the '--source' parameter or via a GSDLSOURCE environment variable):

     expand_macros.pl --source=/usr/local/gsdl/src/stable/ _collector:pagescriptextra_

output:

     *** macro: collector:pagescriptextra ***

     * collector:pagescriptextra [v=0] (SERVER: /usr/local/gsdl/src/stable/src/src/recpt/collectoraction.cpp, line 1058)
       { "_" + collector_page + "scriptextra_" }

- additionally, you can use expand_macros.pl to explore macros interactively ('-i' or '-b' for "interactive", or "browse", mode)

     expand_macros.pl -i

output:

     entered 'expand_macros.pl' in ***interactive browse mode*** (v0.22)
     [you can get help at any time by typing '.h', '.?', or '.help']

     enter macro name (without package specification) [leave empty to quit]
     > pagescriptextra

     select package for macro 'pagescriptextra' [leave empty to return]
       [1]    Style
       [2]    browse
       [3]    collector
       [4]    homepref
       [5]    preferences
       [6]    query
     > 6

     * query:pagescriptextra [v=0] (/usr/local/gsdl/stable/macros/query.dm, line 68)
     { _If_("_cgiargqt_" eq "1", _formpagescriptextra_, _selectpagescriptextra_)
     _If_("_cgiarghd_" ne "0",_historypagescriptextra_) } }

     [press key to continue]

     select macro [leave empty to return]
       [1]    formpagescriptextra
       [2]    historypagescriptextra
       [3]    selectpagescriptextra
     > 1

     select package for macro 'formpagescriptextra' [leave empty to return]
      [1]    query
     > 1

     * query:formpagescriptextra [v=0] (/usr/local/gsdl/stable/macros/query.dm, line 76)
     { // query scripts generated by \_query:pagescriptextra\_
     _standardfunctions_
     _formfunctions_
     _searchfunctions_
     function getsearchargs () \{
       var args="";
       args = "&fqa=0&fqv="+argfqv+"&fqf="+argfqf;
      _If_(_cgiargqf_,args += "&fqk="+argfqk+"&fqs="+argfqs+"&fqc="+argfqc;)
     return args;
     \}
     function getqueryargs () \{
       return "&fqa=1"+"&q="+argq+"&fqv="+argfqv+"&fqf="+argfqf+
         "&fqk="+argfqk+"&fqs="+argfqs+"&fqc="+argfqc ;
     \}
     } }

     [press key to continue]

     select macro [leave empty to return]
      [1]    formfunctions
      [2]    searchfunctions
      [3]    standardfunctions
     >

     select package for macro 'formpagescriptextra' [leave empty to return]
      [1]    query
     >

     select macro [leave empty to return]
      [1]    formpagescriptextra
      [2]    historypagescriptextra
      [3]    selectpagescriptextra
     >

     select package for macro 'pagescriptextra' [leave empty to return]
      [1]    Style
      [2]    browse
      [3]    collector
      [4]    homepref
      [5]    preferences
      [6]    query
     >

     enter macro name (without package specification) [leave empty to quit]
     >

[edit]

## 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...?]

[edit]

### 'I'm feeling lucky' facility

There is a _useifeellucky_ macro in query.dm;

- - if you set this to "_ifeellucky_" then there will be an "I'm feeling lucky" checkbox in the search form.
  - If you tick this then "&ifl=1" goes into the search URL, and code in the C++ redirects you to the first matching document rather than the normal search results page.

(Thanks Michael)

Retrieved from "http://greenstonewiki.cs.waikato.ac.nz/wiki/index.php/All_about_macros"

##### Views

- Article
- Discussion
- Edit
- History

##### Personal tools

- Go to greenstone.org
- Log in
- Create an account

##### Search

##### Toolbox

- What links here
- Related changes
- Upload file
- Special pages
- Printable version