Delay Macro Plugin

Plugin delays expansion of Foswiki macros

Examples

This plugin enables the use of a more clear syntax when building applications where you need to delay the expansion of macros inside the format parameter of another macro which supports the tokens $percnt and $quot. The most typical usecase is inside the format of a SEARCH.

The classic example is the nested SEARCH

%SEARCH{
    "culture"
    web="System"
    format="   * $topic is referenced by:$n      * $percntSEARCH{ $quot$topic$quot format=$quot$dollartopic$quot nonoise=$quoton$quot separator=$quot, $quot }$percnt"
    nonoise="on"
}%

The DelayMacroPlugin can make this syntax much clearer minimizing the need to use tokens $percnt and $quot.

%SEARCH{
    "culture"
    web="System"
    format="   * $topic is referenced by:$n      * %DELAY{macro="SEARCH" "$topic" format="$dollartopic" nonoise="on" separator=", " }%"
    nonoise="on"
}%

Note that we still need to use $dollar to delay the expansion of $topic. The Delay Macro Plugin cannot know if the $topic should belong to the inner or outer loop. In this case we want it to belong to the inner loop and delay it as $dollartopic

Here is an example where we have a nested search and inside the inner loop we want to delay the ENCODE to run after the outer SEARCH is complete

%SEARCH{
    "culture"
    web="System"
    format="   * $topic is referenced by:$n      * $percntSEARCH{$quot$topic$quot format=$quot$dollarpercntENCODE{$dollarquot$dollartopic$dollarquot type=$dollarquoturl$dollarquot}$dollarpercnt$quot nonoise=$quoton$quot separator=$quot, $quot }$percnt"
    nonoise="on"
}%

and the same much simpler and much easier to get to work using this plugin

%SEARCH{
    "culture"
    web="System"
    format="   * $topic is referenced by:$n      * %DELAYSEARCH{"$topic" format="%DELAY{macro="ENCODE" delay="2" "$dollartopic" type="url"}%" nonoise="on" separator=", " }%"
    nonoise="on"
}%

Plugin Use

You can delay the expansion of any macro using DELAY

The syntax is simple

%DELAY{macro="MACRONAME" delay="depth" "default param for MACRONAME" param1="blabla" param2="blabla"}%

Ie. You replace the macro name you want to delay by DELAY and put the macro name as the parameter macro. The delay indicates how many times you want to delay the expansion. The default is 1 so if you have a nested SEARCH with a SEARCH within another SEARCH, you can ommit the delay parameter.

If you ommit the macro parameter DELAY will default to SEARCH.

The plugin supports the alias DELAYSEARCH which does exactly the same as DELAY. It is recommended to use DELAYSEARCH when you want to ommit the macro parameter and default to SEARCH. It makes the application you write easier to understand for yourself and for others. Ie. the example from above could be simplified to

%SEARCH{
    "culture"
    web="System"
    format="   * $topic is referenced by:$n      * %DELAYSEARCH{"$topic" format="$dollartopic" nonoise="on" separator=", " }%"
    nonoise="on"
}%

How does the plugin work?

The plugin has two modes depending on the value of delay

• When delay is not zero (1 or larger, or omitted) the DELAY/DELAYSEARCH returns itself with the leading and trailing %-sign replaced by $percnt and all quotes around its own parameters replaced by $quot. It does not replace the $-sign by $dollar as this would limit the use of the plugin. The delay parameter is decremented. If the delay parameter was omitted it is added with the value 0.
• When the delay reaches zero the DELAY/DELAYSEARCH replaces itself by the macro parameter (SEARCH by default) and removes the delay setting and without any replacement of %-sign and quotes. This way the delayed macro gets expanded normally.

Note that the use of the plugin gives a small performance hit compared to manually escaping with $percnt/$quot. However with a nested SEARCH with delay of 1 the DELAY macro is only expanded once while the resulting SEARCH may be expanded many many times. In comparison these searches will take magnitudes longer than the simple operation of the initial DELAY. You will most likely not notice the delay. But you will notice that it is much easier to get those nasty nested searches right.

Plugin Test

If the plugin is installed and works you should see the result of the example above

%SEARCH{ "culture" web="System" format=" * $topic is referenced by:$n * %DELAYSEARCH{"$topic" format="$dollartopic" nonoise="on" separator=", " }%" nonoise="on" }%

Plugin Settings

The plugin has no settings at all.

Installation

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.

Plugin Info

Author:	Foswiki:Main.KennethLavrsen
Copyright:	© 2009, Kenneth Lavrsen
License:	GPL (GNU General Public License)
Release:	1.1
Version:	6882 (2010-03-24)
Change History:
24 Mar 2010 (1.1)	Fixed the code so it does not fail showing runtime errors if you forget to give it a macro text to delay. It now defaults to ''
03 Mar 2010 (1.0)	Initial release
Home:	http://foswiki.org/Extensions/DelayMacroPlugin
Support:	http://foswiki.org/Support/DelayMacroPlugin