Write %MACROS in pure topic markup language


This plugin allows to implement a %MACRO in pure TML (topic markup language). Normally, you'd have to write a perl extension for each extension and call the internal Foswiki::Func::registerTagHandler() to register a perl handler to be called for this %MACRO.

Using this plugin you can do the same but register a TopicFunction to be executed. This is a way to create convenient shortcuts of parametrized %INCLUDEs.

See the related discussion at Foswiki:Development/ParameterizedVariables


For example, create a topic GreetUser with the following content:


Hello %user%, have a nice day.


Then you can make use of this TopicFunction writing
%INCLUDE{"GreetUser" user="Ralph"}%

and get a

Hello Ralph, have a nice day.

With EasyMacroPlugin, you can now register the GreetUser as a macro:
%REGISTERMACRO{"GREETUSER" topic="GreetUser" param="user" user="Rebeka"}%

and simply write

to do the same. The unnamed parameter to %GREETUSER is user. When the user parameter is not specified, it defaults to Rebeka. So a


will greet Rebeka instead.

The EASYMACROS preference setting

A complete set of TopicFunctions can be registered using the preference variable EASYMACROS. So add

   * Set EASYMACROS = GreetUser

to your WebPreferences, SitePreferences or user topic. This is a list of all macros to be registered for all of the scope of the preference variable. Each listed TopicFunction must have a registration section containing the %REGISTERMACRO statement to establish the new macro. So our GreetUser TopicFunction will be completed using:


Hello %user%, have a nice day.



%REGISTERMACRO{"GREETUSER" topic="GreetUser" param="user" user="Rebeka"}%



Parameter DescriptionSorted descending Default
web="..." web containing the topic current web
topic="..." topic implementing the MACRO; can't be used togther with format current topic
warn="on/off" set this to off to surpress the warning message when trying to redefine an already known %MACRO or preference variable
param="..." name of the variable to bind the unnamed parameter of the MACRO to, e.g. with a %REGISTERMACRO{"MACRO" format="... $VAR ..." param="VAR"}% a call like %MACRO{"foo"}% will bind VAR=foo to the format expression  
"<name>" name of macro to be registered  
format="..." format string to define the MACRO inline; can't be used together with topic  

REGISTERMACRO can be called in two modes

  1. format-mode
  2. topic-mode

In format-mode the new MACRO is implemented within the format parameter of the REGISTERMACRO itself. This is usefull for small implementations. In topic-mode, REGISTERMACRO is called with a topic parameter to specify which topic implements the macro. Note, that variables in format are expanded using a $VAR notation, wherease in topic-mode real variables are instantiated using the %VAR% notation.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.


Many thanks to the following sponsors for supporting this work:

Author(s): Foswiki:Main/MichaelDaum
Copyright ©: 2009-2014, Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 1.24
Version: 1.24
Change History:  
02 Jun 2014: Item12929: fixed incorrectly passed parameters with a zero
18 Jul 2011: Item10981: delete _DEFAULT from params when constructing the easy-macro call
12 Feb 2010: Item8510: forward compatibility for Foswiki >= 1.1
12 Nov 2009: Item8325: unregistering easy-macros in persistent perl environmens; made persistent macros an optimization flag
10 Nov 2009: Item2343: fixed registration of macros defined in other webs
03 Nov 2009: initial release
Dependencies: None
Home page: Foswiki:Extensions/EasyMacroPlugin
Support: Foswiki:Support/EasyMacroPlugin

This topic: System > EasyMacroPlugin
Topic revision: 10 Feb 2015, BodoRiedigerKlaus