EasyMacroPlugin

Write %MACROS in pure topic markup language

Description

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

Example

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

%STARTINCLUDE%

Hello %user%, have a nice day.

%STOPINCLUDE%

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

%GREETUSER{"Ralph"}%

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

%GREETUSER%

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:

%STARTINCLUDE%

Hello %user%, have a nice day.

%STOPINCLUDE%

%STARTSECTION{"registration"}%

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

%ENDSECTION{"registration"}%

Syntax of REGISTERMACRO

Parameter	Description	Default
"<name>"	name of macro to be registered
format="..."	format string to define the MACRO inline; can't be used together with topic
topic="..."	topic implementing the MACRO; can't be used togther with format	current topic
web="..."	web containing the topic	current web
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
warn="on/off"	set this to off to surpress the warning message when trying to redefine an already known %MACRO or preference variable

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.

Dependencies

None

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