velocity-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <>
Subject [Jakarta-velocity Wiki] Update of "MacroIssues" by WillGlassHusain
Date Mon, 02 Jan 2006 14:16:54 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jakarta-velocity Wiki" for change

The following page has been changed by WillGlassHusain:

The comment on the change is:
new file

New page:
=== Macro bug fixes / enhancements ===

some notes by Will <>.

I'm starting to look into the remain bug fix/enhancements for the 1.5 release.  
Not surprisingly, many of the remaining issues are all pretty subtle.  I thought I'd publically
share a few notes on macros.

Here's a catalog of the open macro-related issues targeted for 1.5.

 *  Macros in #parsed files are not refreshed
when including page is refreshed

 *  Can't load macros in file loaded with

 *  Macros not evaluated on the first attempt
with #parse

 *   Calls to local macros not always made
when template caching is off
 *   VM libs will not autoreload if unparseable
at Velocity startup


Most of these issues stem from how Velocity stores macros.  Macros can be stored either at
a global level 
or on a per-template level.  This is controlled by the config key "velocimacro.permissions.allow.inline.local.scope",
which is
false by default.  (i.e. all macros are part of global scope).  See the 
developer's guide].

This means that the following common-sense use case (referenced in VELOCITY-277, VELOCITY-362,
and VELOCITY-136) just doesn't work.



#macro(NewMacro) do something #end

Here's why.  Case 1.  If "velocimacro.permissions.allow.inline.local.scope" is true, then
#!NewMacro is 
defined in "macros.txt"  but not "file1.vm".  Thus the macro is not available for use.

Case 2.  If "velocimacro.permissions.allow.inline.local.scope" is false, then then #!NewMacro
is defined 
globally and available from all templates.  This seems like a good idea
but is impractical in practice for the following reasons.
 * First of all, it doesn't work.  Hence the first three bugs.  They are technically not bugs
since this behavior is 
 [ documented],
though that's difficult to find.
 * Currently macros are evaluated at parse time while #parse is evaluated at runtime. (allowing
the template to dynamically
 choose a page to include).  That's why the macro is not picked up by the #parse.
 * Even if we fix this, there's a threading problem and a namespace problem.  This macro is
available to any template.
 If a website has hundreds or thousands of templates, there's no guarantee that another page
hasn't defined a macro with
 the same name which could be loaded into the same common name space unexpectedly.  The results
could be very hard to debug.
Proposed Solution: Add a new mode for macros.  (really, this should be the default in the
future), which is request based.  When a 
macro is defined in a page, it should be follow the execution of the page, be available in
any subpages called with #parse
and be available to a calling page that has called this with #parse.  However, the macro shouldn't
interfere with the global
namespace or any non-related templates.

Open issues / discussion points - 
 * Can this be done while preserving Velocity's high-performance template caching?
 * If we add a new scope for macros, is this backwards compatible?  (assuming we allow old
modes to continue to work).

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message