You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by "Deinhammer, Guido" <GD...@thegoldensource.com> on 2008/03/05 14:53:19 UTC

A simple macro replacement with user directives

Hi,

I followed the discussion here on Macros - and thought you might be
interested in what I have done to overcome most of their shortcomings.

I understand my writing turned out a little lengthy, but if you are
using macros, it should be worth the read...

Basically I am working on a web-based UI and we use velocity to render
html. We have a number of fairly complex macros - some are recursive -
and when I did a check on the memory consumption that finally made me
rethink whether velocity is suited to what we do at all. The problem is
that it includes the parsed nodetree of a macro wherever it is called
(https://issues.apache.org/jira/browse/VELOCITY-223). In our project
that resulted in up to 10MB of heap memory for a screen and we have
around 800 of them. This would mean that we can cache only around 15
screens in the ResourceCache.
This finally made me change all our (mostly generated) velocity
templates.
Before that there were a few other inconveniences that we got used to -
parameter passing is not ideal - we have often well over 20 parameters
many of them can be defaulted, so the normal macro parameters are not
very useful for us - but that is easy enough to work around - just pass
a single map to your macro - and inside the macro you can use a Java
tool or a user directive to default the values in the argument map with
values of a second - defaultValue map.
That made the maros a lot easier to use for us - but the memory problem
remains.
Another problem was that the caller cannot pass a body, or velocity
markup to the macro - that would be very convenient if you want to
implement e.g. a collapsible section
(https://issues.apache.org/jira/browse/VELOCITY-558 or
https://issues.apache.org/jira/browse/VELOCITY-583)

Other's reported using a variable for the name of the macro doesn't
work. 

So I thought instead of using a macro call I could just implement a
directive that renders another .vm file with the same context and the
same Writer - similar to parse but with the option of passing
parameters. So that's what I did. And with the three directives I have
attached you can do something like this:

#call($myMacro {"arg1": true, "arg2":false})

The $myMacro variable has to resolve to a fileName (you can set the
directory for this, so you don't have to give the full path, and you can
skip the .vm ending). The second parameter is a map that is added to the
context under the name "args" - the "macro" can access the parameters
with $args.arg1. The "macro" itself, is nothing but a .vm file 

You can also do this:

#callBlock(collapsibleSection {"isCollapsed":$collapsed, "title":"My
Section"})
 My section content.....
#end

Where your collapsibleSection.vm file could look like this:

<table><th><td>$args.title</td></th>
#if($args.open)
  #content()
#end
</table>
#end

Where the #content() directive will just render the body of the
callBlock directive - in this case " My section content.....".


So have a look at the attached code, if you have similar problems with
macros - it is quite short and should be easy to understand.
Maybe something like this should be added for the 1.6 version - or the
whole macro concept could be converted to a solution like that - leaving
the existing syntax intact.


Best regards,

Guido Deinhammer

Btw: we have also added another cool directive that allows partial page
rendering...but I didn't have time to write it up yet...

Re: A simple macro replacement with user directives

Posted by Nathan Bubna <nb...@gmail.com>.
On Thu, Mar 6, 2008 at 6:21 AM, Deinhammer, Guido
<GD...@thegoldensource.com> wrote:
> Hi Chris,
>
>  You are right - for a solution that is part of the standard, it would be
>  better to use a nested context to avoid the "args." prefix. I already
>  used macros with only one args parameter - so for me it didn't make
>  sense to do this.
>
>  When adding this functionality, I think it would be best to just add an
>  optional map parameter to the parse directive - this way users don't
>  have to learn any new directive and it would be easy to adopt this
>  feature.

i thought this at first, but i'm not so sure now.  taking a map of
arguments isn't the only difference.  having a chained context,
setting a base directory (unique from the resource loader system), and
taking the first arg as a literal #call( foo ) instead of a string
#parse( "foo.vm" ).

Regarding #callBlock, there's been talk of a #macroblock too.  I
wonder if we should just focus on a #block( foo ) here's da block #end
directive to define blocks, and leave the user to pass the blocks into
the macro or #call on their own.

> Also setting a different base directory for where parse takes
>  the templates from would be useful. This way you can keep the reusable
>  code in one place and you don't have to write the full path when using
>  the parse directive.

true.  that might be useful in general.  Will, how would these ideas
fit with your IncludeEventHandler?

>  Since you are adding the arguments to the context, it might make sense
>  to create another directive - something like #default that takes a map
>  and defaults variables in the context to map entries. When you have many
>  parameters for a macro, being able to efficiently set default values is
>  crucial.

I can't really see that ever being part of a standard distribution.
Also, it could be probably done easily as a tool (or extension
of/addition to the ContextTool).

>  To allow a content to be rendered (what I did with #callBlock and
>  #content), you will need a new directive since it has to be a
>  blockDirective.
>
>
>  You wrote:
>  I think you can choose to use the wrapped versus outer context however
>  you want... I did not really understand why this was true:
>
>  >     // the callStack is needed for the ContentDirective - when the
>  content is rendered,
>  >     // we have to move one level back in the callStack
>
>  This is because when you render the content of the callBlock directive
>  (using #content), you have to reset the args map to what it was before
>  the directive was called - it's essential for nested callBlock
>  statements and recursions. But it should be possible to do the same
>  thing with nested contexts.
>
>  Frankly I don't have much time now to contribute a lot to the project -
>  I am just sharing what I've done. If that functionality makes it into
>  the base product I think it would be a great enhancement.
>
>  Cheers,
>
>  Guido
>
>
>
>  -----Original Message-----
>  From: Christopher Schultz [mailto:chris@christopherschultz.net]
>  Sent: Wednesday, March 05, 2008 9:00 PM
>  To: Velocity Developers List
>  Subject: Re: A simple macro replacement with user directives
>
>  Guido,
>
>  Deinhammer, Guido wrote:
>  > I understand my writing turned out a little lengthy, but if you are
>  > using macros, it should be worth the read...
>
>  It definitely is. Thanks for investigating /and providing code/!
>
>  > The second parameter is a map that is added to the context under the
>  > name "args" - the "macro" can access the parameters with $args.arg1.
>
>  What about wrapping the current VelocityContext in another one that
>  contains the argument map? That would allow you to use your template
>  either through your #call directive or with #parse (because it would
>  remove the need for the "$args." prefix).
>
>  It would be an easy fix. Starting with CallDirective.java:120:
>
>  >     Object oldArgs = context.put(ARGUMENTS_VARIABLE_NAME, args);
>
>  Change this to:
>
>        // Wrap the outer context with a new one
>        Context subContext = new VelocityContext(context);
>
>        // Copy the arguments into the inner context
>        for(Iterator i=args.entrySet().iterator(); i.hasNext(); ) {
>            Map.Entry entry = (Map.Entry)i.next();
>            subContext.put((String)entry.getKey(), entry.getValue());
>        }
>
>  I think you can choose to use the wrapped versus outer context however
>  you want... I did not really understand why this was true:
>
>  >     // the callStack is needed for the ContentDirective - when the
>  content is rendered,
>  >     // we have to move one level back in the callStack
>
>  ... so it's up to you. ;)
>
>  Of course, you'd want to use the wrapped context, here:
>
>  >       template.merge(context, writer);
>
>         template.merge(subContext, writer);
>
>  And this line is unnecessary, since subContext will simply fall out of
>  scope:
>
>  >     context.put(ARGUMENTS_VARIABLE_NAME, oldArgs);
>
>  I'm also not sure about the push and pop of template names if you use a
>  wrapped context. I don't know enough about the internals of Velocity to
>  know if they are required or not.
>
>  Let me know if you think these are reasonable improvements.
>
>  -chris
>
>
>
>
>
> ---------------------------------------------------------------------
>  To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
>  For additional commands, e-mail: dev-help@velocity.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org


RE: A simple macro replacement with user directives

Posted by "Deinhammer, Guido" <GD...@thegoldensource.com>.
Hi Chris,

You are right - for a solution that is part of the standard, it would be
better to use a nested context to avoid the "args." prefix. I already
used macros with only one args parameter - so for me it didn't make
sense to do this.

When adding this functionality, I think it would be best to just add an
optional map parameter to the parse directive - this way users don't
have to learn any new directive and it would be easy to adopt this
feature. Also setting a different base directory for where parse takes
the templates from would be useful. This way you can keep the reusable
code in one place and you don't have to write the full path when using
the parse directive.

Since you are adding the arguments to the context, it might make sense
to create another directive - something like #default that takes a map
and defaults variables in the context to map entries. When you have many
parameters for a macro, being able to efficiently set default values is
crucial.

To allow a content to be rendered (what I did with #callBlock and
#content), you will need a new directive since it has to be a
blockDirective.

You wrote:
I think you can choose to use the wrapped versus outer context however
you want... I did not really understand why this was true:

>     // the callStack is needed for the ContentDirective - when the
content is rendered,
>     // we have to move one level back in the callStack

This is because when you render the content of the callBlock directive
(using #content), you have to reset the args map to what it was before
the directive was called - it's essential for nested callBlock
statements and recursions. But it should be possible to do the same
thing with nested contexts. 

Frankly I don't have much time now to contribute a lot to the project -
I am just sharing what I've done. If that functionality makes it into
the base product I think it would be a great enhancement.

Cheers,

Guido

-----Original Message-----
From: Christopher Schultz [mailto:chris@christopherschultz.net] 
Sent: Wednesday, March 05, 2008 9:00 PM
To: Velocity Developers List
Subject: Re: A simple macro replacement with user directives

Guido,

Deinhammer, Guido wrote:
> I understand my writing turned out a little lengthy, but if you are 
> using macros, it should be worth the read...

It definitely is. Thanks for investigating /and providing code/!

> The second parameter is a map that is added to the context under the 
> name "args" - the "macro" can access the parameters with $args.arg1.

What about wrapping the current VelocityContext in another one that
contains the argument map? That would allow you to use your template
either through your #call directive or with #parse (because it would
remove the need for the "$args." prefix).

It would be an easy fix. Starting with CallDirective.java:120:

>     Object oldArgs = context.put(ARGUMENTS_VARIABLE_NAME, args);

Change this to:

       // Wrap the outer context with a new one
       Context subContext = new VelocityContext(context);

       // Copy the arguments into the inner context
       for(Iterator i=args.entrySet().iterator(); i.hasNext(); ) {
           Map.Entry entry = (Map.Entry)i.next();
           subContext.put((String)entry.getKey(), entry.getValue());
       }

I think you can choose to use the wrapped versus outer context however
you want... I did not really understand why this was true:

>     // the callStack is needed for the ContentDirective - when the
content is rendered,
>     // we have to move one level back in the callStack

... so it's up to you. ;)

Of course, you'd want to use the wrapped context, here:

>       template.merge(context, writer);

	template.merge(subContext, writer);

And this line is unnecessary, since subContext will simply fall out of
scope:

>     context.put(ARGUMENTS_VARIABLE_NAME, oldArgs);

I'm also not sure about the push and pop of template names if you use a
wrapped context. I don't know enough about the internals of Velocity to
know if they are required or not.

Let me know if you think these are reasonable improvements.

-chris



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org


Re: A simple macro replacement with user directives

Posted by Christopher Schultz <ch...@christopherschultz.net>.
Guido,

Deinhammer, Guido wrote:
> I understand my writing turned out a little lengthy, but if you are
> using macros, it should be worth the read...

It definitely is. Thanks for investigating /and providing code/!

> The second parameter is a map that is added to the
> context under the name "args" - the "macro" can access the parameters
> with $args.arg1.

What about wrapping the current VelocityContext in another one that 
contains the argument map? That would allow you to use your template 
either through your #call directive or with #parse (because it would 
remove the need for the "$args." prefix).

It would be an easy fix. Starting with CallDirective.java:120:

>     Object oldArgs = context.put(ARGUMENTS_VARIABLE_NAME, args);

Change this to:

       // Wrap the outer context with a new one
       Context subContext = new VelocityContext(context);

       // Copy the arguments into the inner context
       for(Iterator i=args.entrySet().iterator(); i.hasNext(); ) {
           Map.Entry entry = (Map.Entry)i.next();
           subContext.put((String)entry.getKey(), entry.getValue());
       }

I think you can choose to use the wrapped versus outer context however 
you want... I did not really understand why this was true:

>     // the callStack is needed for the ContentDirective - when the content is rendered,
>     // we have to move one level back in the callStack

... so it's up to you. ;)

Of course, you'd want to use the wrapped context, here:

>       template.merge(context, writer);

	template.merge(subContext, writer);

And this line is unnecessary, since subContext will simply fall out of 
scope:

>     context.put(ARGUMENTS_VARIABLE_NAME, oldArgs);

I'm also not sure about the push and pop of template names if you use a 
wrapped context. I don't know enough about the internals of Velocity to 
know if they are required or not.

Let me know if you think these are reasonable improvements.

-chris


Re: A simple macro replacement with user directives

Posted by Nathan Bubna <nb...@gmail.com>.
On Wed, Mar 5, 2008 at 11:51 PM, Claude Brisson <cl...@renegat.net> wrote:
>
>  Le mercredi 05 mars 2008 à 12:13 -0800, Nathan Bubna a écrit :
#snip()
>  > interesting.  seems like new ideas are starting to pop up. :)  i have
>  > one i'm excited about, but i'm not quite ready to put it out there for
>  > community vetting.
>  >
>  > in any case, if we can't work some of these new ideas into 1.6 proper,
>  > it would be great to at least get them in 1.6's whiteboard at a very
>  > minimum to make it easier for people to start playing with them.
>
>  Let's create the 1_7 branch, and we'll backport thinks that we managed
>  to do in the 1.6 before the release. It's subversion, it's not
>  subversive. It's merge, not submerge ;)

if you want to do it, go for it.  i don't find it easy to manage two
branches at once, but if you're going to take the lead in the effort,
that's ok with me.

>  We could also create the 2_0 branch right away...

heh.  i'd never veto it. :)

>
>  Agree?
>
>   Claude
>
>  > ---------------------------------------------------------------------
>  > To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
>  > For additional commands, e-mail: dev-help@velocity.apache.org
>  >
>
>
>  ---------------------------------------------------------------------
>  To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
>  For additional commands, e-mail: dev-help@velocity.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org


Re: A simple macro replacement with user directives

Posted by Claude Brisson <cl...@renegat.net>.
Le mercredi 05 mars 2008 à 12:13 -0800, Nathan Bubna a écrit :
> On Wed, Mar 5, 2008 at 5:53 AM, Deinhammer, Guido
> <GD...@thegoldensource.com> wrote:
> > Hi,
> >
> >  I followed the discussion here on Macros - and thought you might be
> >  interested in what I have done to overcome most of their shortcomings.
> >
> >  I understand my writing turned out a little lengthy, but if you are
> >  using macros, it should be worth the read...
> >
> >  Basically I am working on a web-based UI and we use velocity to render
> >  html. We have a number of fairly complex macros - some are recursive -
> >  and when I did a check on the memory consumption that finally made me
> >  rethink whether velocity is suited to what we do at all. The problem is
> >  that it includes the parsed nodetree of a macro wherever it is called
> >  (https://issues.apache.org/jira/browse/VELOCITY-223). In our project
> >  that resulted in up to 10MB of heap memory for a screen and we have
> >  around 800 of them. This would mean that we can cache only around 15
> >  screens in the ResourceCache.
> 
> yeah, we've heard a lot of such stories.  there's also the weird
> parsing issues with multi-line comments in macros we've been having.
> for all the improvements made to them last summer,  they still have a
> long way to go.
> 
> >  This finally made me change all our (mostly generated) velocity
> >  templates.
> >  Before that there were a few other inconveniences that we got used to -
> >  parameter passing is not ideal - we have often well over 20 parameters
> >  many of them can be defaulted, so the normal macro parameters are not
> >  very useful for us - but that is easy enough to work around - just pass
> >  a single map to your macro - and inside the macro you can use a Java
> >  tool or a user directive to default the values in the argument map with
> >  values of a second - defaultValue map.
> >  That made the maros a lot easier to use for us - but the memory problem
> >  remains.
> >  Another problem was that the caller cannot pass a body, or velocity
> >  markup to the macro - that would be very convenient if you want to
> >  implement e.g. a collapsible section
> >  (https://issues.apache.org/jira/browse/VELOCITY-558 or
> >  https://issues.apache.org/jira/browse/VELOCITY-583)
> >
> >  Other's reported using a variable for the name of the macro doesn't
> >  work.
> >
> >  So I thought instead of using a macro call I could just implement a
> >  directive that renders another .vm file with the same context and the
> >  same Writer - similar to parse but with the option of passing
> >  parameters. So that's what I did. And with the three directives I have
> >  attached you can do something like this:
> >
> >  #call($myMacro {"arg1": true, "arg2":false})
> >
> >  The $myMacro variable has to resolve to a fileName (you can set the
> >  directory for this, so you don't have to give the full path, and you can
> >  skip the .vm ending). The second parameter is a map that is added to the
> >  context under the name "args" - the "macro" can access the parameters
> >  with $args.arg1. The "macro" itself, is nothing but a .vm file
> >
> >  You can also do this:
> >
> >  #callBlock(collapsibleSection {"isCollapsed":$collapsed, "title":"My
> >  Section"})
> >   My section content.....
> >  #end
> >
> >  Where your collapsibleSection.vm file could look like this:
> >
> >  <table><th><td>$args.title</td></th>
> >  #if($args.open)
> >   #content()
> >  #end
> >  </table>
> >  #end
> >
> >  Where the #content() directive will just render the body of the
> >  callBlock directive - in this case " My section content.....".
> 
> these look like a great improvements on #parse.
> 
> >  So have a look at the attached code, if you have similar problems with
> >  macros - it is quite short and should be easy to understand.
> >  Maybe something like this should be added for the 1.6 version - or the
> >  whole macro concept could be converted to a solution like that - leaving
> >  the existing syntax intact.
> 
> i'm totally interested.  no time to look at the code today, but i
> would love to have something like #parse but with a little more
> control over the variables/namespace.
> 
> >
> >
> >  Best regards,
> >
> >  Guido Deinhammer
> >
> >  Btw: we have also added another cool directive that allows partial page
> >  rendering...but I didn't have time to write it up yet...
> 
> interesting.  seems like new ideas are starting to pop up. :)  i have
> one i'm excited about, but i'm not quite ready to put it out there for
> community vetting.
> 
> in any case, if we can't work some of these new ideas into 1.6 proper,
> it would be great to at least get them in 1.6's whiteboard at a very
> minimum to make it easier for people to start playing with them.

Let's create the 1_7 branch, and we'll backport thinks that we managed
to do in the 1.6 before the release. It's subversion, it's not
subversive. It's merge, not submerge ;)

We could also create the 2_0 branch right away...

Agree?

  Claude

> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
> For additional commands, e-mail: dev-help@velocity.apache.org
> 


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org


Re: A simple macro replacement with user directives

Posted by Jonathan Revusky <re...@gmail.com>.
Nathan Bubna wrote:

>>  #callBlock(collapsibleSection {"isCollapsed":$collapsed, "title":"My
>>  Section"})
>>   My section content.....
>>  #end
>>
>>  Where your collapsibleSection.vm file could look like this:
>>
>>  <table><th><td>$args.title</td></th>
>>  #if($args.open)
>>   #content()
>>  #end
>>  </table>
>>  #end
>>
>>  Where the #content() directive will just render the body of the
>>  callBlock directive - in this case " My section content.....".
> 
> these look like a great improvements on #parse.
> 
>>  So have a look at the attached code, if you have similar problems with
>>  macros - it is quite short and should be easy to understand.
>>  Maybe something like this should be added for the 1.6 version - or the
>>  whole macro concept could be converted to a solution like that - leaving
>>  the existing syntax intact.
> 
> i'm totally interested.  no time to look at the code today, but i
> would love to have something like #parse but with a little more
> control over the variables/namespace.
> 
>>
>>  Best regards,
>>
>>  Guido Deinhammer
>>
>>  Btw: we have also added another cool directive that allows partial page
>>  rendering...but I didn't have time to write it up yet...
> 
> interesting.  seems like new ideas are starting to pop up. :)  

<LOL>

Nathan, these aren't new ideas. Basically, all of these things have been 
implemented in FreeMarker for 5, even 6 years. Okay, I grant that you 
could say they are "new" insofar as they would be new in Velocity. But 
still, it seems to me that, if you're serious about doing work in some 
application space, there has to be some notion of an existing state of 
the art, and you can't be referring to things that are longstanding 
features in other tools in the space as "new ideas". It's like as if I 
wrote a vanilla text editor, and then started saying that something like 
syntax highlighting was an exciting new feature. Well, I suppose it 
would be if you never looked at a state of the art programmer's editor....

> i have
> one i'm excited about, but i'm not quite ready to put it out there for
> community vetting.


Gee, I wonder which of the things on this page that might be....

http://freemarker.org/features.html

> 
> in any case, if we can't work some of these new ideas into 1.6 proper,
> it would be great to at least get them in 1.6's whiteboard at a very
> minimum to make it easier for people to start playing with them.

Well, yeah, but I think it's fair comment to say that people in our user 
community are not "playing with" these "new ideas". They simply use 
them, in production code and so on, at this stage, things like macro 
invocations with associated blocks, and default and unordered parameter 
lists and so on, are longstanding features that have been there in a 
stable form for 5 years or more.

Jonathan Revusky
--
lead developer, FreeMarker project, http://freemarker.org/

Velocity or FreeMarker: Looking at 5 Years of Practical Experience
http://freemarker.blogspot.com/2007/12/velocity-of-freemarker-looking-at-5.html




---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org


Re: A simple macro replacement with user directives

Posted by Nathan Bubna <nb...@gmail.com>.
On Wed, Mar 5, 2008 at 5:53 AM, Deinhammer, Guido
<GD...@thegoldensource.com> wrote:
> Hi,
>
>  I followed the discussion here on Macros - and thought you might be
>  interested in what I have done to overcome most of their shortcomings.
>
>  I understand my writing turned out a little lengthy, but if you are
>  using macros, it should be worth the read...
>
>  Basically I am working on a web-based UI and we use velocity to render
>  html. We have a number of fairly complex macros - some are recursive -
>  and when I did a check on the memory consumption that finally made me
>  rethink whether velocity is suited to what we do at all. The problem is
>  that it includes the parsed nodetree of a macro wherever it is called
>  (https://issues.apache.org/jira/browse/VELOCITY-223). In our project
>  that resulted in up to 10MB of heap memory for a screen and we have
>  around 800 of them. This would mean that we can cache only around 15
>  screens in the ResourceCache.

yeah, we've heard a lot of such stories.  there's also the weird
parsing issues with multi-line comments in macros we've been having.
for all the improvements made to them last summer,  they still have a
long way to go.

>  This finally made me change all our (mostly generated) velocity
>  templates.
>  Before that there were a few other inconveniences that we got used to -
>  parameter passing is not ideal - we have often well over 20 parameters
>  many of them can be defaulted, so the normal macro parameters are not
>  very useful for us - but that is easy enough to work around - just pass
>  a single map to your macro - and inside the macro you can use a Java
>  tool or a user directive to default the values in the argument map with
>  values of a second - defaultValue map.
>  That made the maros a lot easier to use for us - but the memory problem
>  remains.
>  Another problem was that the caller cannot pass a body, or velocity
>  markup to the macro - that would be very convenient if you want to
>  implement e.g. a collapsible section
>  (https://issues.apache.org/jira/browse/VELOCITY-558 or
>  https://issues.apache.org/jira/browse/VELOCITY-583)
>
>  Other's reported using a variable for the name of the macro doesn't
>  work.
>
>  So I thought instead of using a macro call I could just implement a
>  directive that renders another .vm file with the same context and the
>  same Writer - similar to parse but with the option of passing
>  parameters. So that's what I did. And with the three directives I have
>  attached you can do something like this:
>
>  #call($myMacro {"arg1": true, "arg2":false})
>
>  The $myMacro variable has to resolve to a fileName (you can set the
>  directory for this, so you don't have to give the full path, and you can
>  skip the .vm ending). The second parameter is a map that is added to the
>  context under the name "args" - the "macro" can access the parameters
>  with $args.arg1. The "macro" itself, is nothing but a .vm file
>
>  You can also do this:
>
>  #callBlock(collapsibleSection {"isCollapsed":$collapsed, "title":"My
>  Section"})
>   My section content.....
>  #end
>
>  Where your collapsibleSection.vm file could look like this:
>
>  <table><th><td>$args.title</td></th>
>  #if($args.open)
>   #content()
>  #end
>  </table>
>  #end
>
>  Where the #content() directive will just render the body of the
>  callBlock directive - in this case " My section content.....".

these look like a great improvements on #parse.

>  So have a look at the attached code, if you have similar problems with
>  macros - it is quite short and should be easy to understand.
>  Maybe something like this should be added for the 1.6 version - or the
>  whole macro concept could be converted to a solution like that - leaving
>  the existing syntax intact.

i'm totally interested.  no time to look at the code today, but i
would love to have something like #parse but with a little more
control over the variables/namespace.

>
>
>  Best regards,
>
>  Guido Deinhammer
>
>  Btw: we have also added another cool directive that allows partial page
>  rendering...but I didn't have time to write it up yet...

interesting.  seems like new ideas are starting to pop up. :)  i have
one i'm excited about, but i'm not quite ready to put it out there for
community vetting.

in any case, if we can't work some of these new ideas into 1.6 proper,
it would be great to at least get them in 1.6's whiteboard at a very
minimum to make it easier for people to start playing with them.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org


Re: A simple macro replacement with user directives

Posted by Jonathan Revusky <re...@gmail.com>.
Deinhammer, Guido wrote:
> Hi,
> 
> I followed the discussion here on Macros - and thought you might be
> interested in what I have done to overcome most of their shortcomings.

As mostly a casual observer here, I found it fascinating. My initial 
reaction, though, is that, pragmatically speaking, does this make any 
sense? I mean, Velocity's main competitor in this space, a project that 
is largely (but far from completely) my fault, has had all these 
features you need in its stable releases for over 5 years. What's more, 
this is a pretty well known project we're talking about. FreeMarker. 
It's used directly by a lot of people but also as a third-party 
component for templating in a large number of tools and frameworks out 
there, Struts 2, Hibernate Tools, Netbeans.... So these features have 
been stress-tested a huge amount in the course of those 5 years, and, 
while I'd be the last person to say it's perfect, there is a test of 
time that has happened, and you can say that this is something pretty 
solid that you could built mission-critical aps on top of. It will take 
you a long time to get the same features into that state working from 
the current state of Velocity.

So, you know, to add these new features to Velocity might only be a 
moderate amount of work, (you'd probably spend more hours on all the 
community debate over how everything has to work than actually 
implementing it) but what you have will not be nearly as robust as the 
same features in FreeMarker that have been part of the stable releases 
for 5 years. I don't think there is any way you can subject your work to 
the test that is comparable to 5 years of real world usage by a fairly 
large community out there.

Another aspect of things is that FreeMarker is still something of a 
moving target. We're going to have a prerelease of 2.4 which has some 
interesting new features, which, I grant, will not be stress-tested than 
the ones that have been in there for so long. But I mean, to say, that 
by the time you bring Velocity up to the feature set of FreeMarker of 5 
years ago, surely we'll have a fairly stable 2.4 out with some 
interesting new features and you'lll be quite well behind again.

I don't know how you take this note, Guido, I can tell you that I don't 
have any axe to grind with you personally. I think it's great that you 
have fire in your belly to some work in this application space. It would 
be great if you wanted to be a collaborator in our project.  In that 
case, you'd at least be working approximately on the cutting edge of 
what is available in this kind of tool, rather than trying to catch up 
with the state of an existing tool of 5 years ago....

You might take this as something of a rebuke but it's not really: I 
think you would be better off, before investing all this time to add 
features to Velocity or some other existing tool, to look around out 
there and get a sense of what the state of the art in that space is. In 
this case, you would see that the features you need that you intended to 
implement in Velocity already exist in a very stable form in an 
alternative tool. It's not a rebuke, because, I can imagine you were 
eager to get into this and hack the code, and you saw that you could add 
these features and so on. But that's not always pragmatic. It makes 
sense to check whether you're not reinventing the wheel.


> 
> I understand my writing turned out a little lengthy, but if you are
> using macros, it should be worth the read...
> 
> Basically I am working on a web-based UI and we use velocity to render
> html. We have a number of fairly complex macros - some are recursive -
> and when I did a check on the memory consumption that finally made me
> rethink whether velocity is suited to what we do at all. The problem is
> that it includes the parsed nodetree of a macro wherever it is called
> (https://issues.apache.org/jira/browse/VELOCITY-223). 

Uhh, yeah, that's the kind of thing I was referring to in another note 
when I mentioned first order implementation mistakes... I mean, 
seriously, is this the kind of thing one should see in such a visible 
project that is over 7 years old?

> In our project
> that resulted in up to 10MB of heap memory for a screen and we have
> around 800 of them. This would mean that we can cache only around 15
> screens in the ResourceCache.
> This finally made me change all our (mostly generated) velocity
> templates.
> Before that there were a few other inconveniences that we got used to -
> parameter passing is not ideal - we have often well over 20 parameters
> many of them can be defaulted, so the normal macro parameters are not
> very useful for us - but that is easy enough to work around - just pass
> a single map to your macro - and inside the macro you can use a Java
> tool or a user directive to default the values in the argument map with
> values of a second - defaultValue map.

Yeah, this has been in FreeMarker for 5 or 6 years. See:

http://freemarker.org/docs/dgui_misc_userdefdir.html#autoid_22

and

http://freemarker.org/docs/ref_directive_macro.html

The macro system allows default parameters to be specified as well as 
vararg style lists where the extra args are passed in as a variable 
that's a list.

> That made the maros a lot easier to use for us - but the memory problem
> remains.
> Another problem was that the caller cannot pass a body, or velocity
> markup to the macro - that would be very convenient if you want to
> implement e.g. a collapsible section

Uh, yeah, see:

http://freemarker.org/docs/dgui_misc_userdefdir.html#autoid_23

and again,

http://freemarker.org/docs/ref_directive_macro.html

> (https://issues.apache.org/jira/browse/VELOCITY-558 or
> https://issues.apache.org/jira/browse/VELOCITY-583)

Uhh, yeah, BTW, I think the reporter of issue 583 gave up on Velocity 
and is now using FreeMarker.... Path of least resistance, as the other 
tool already had the feature in a highly stable form.

> 
> Other's reported using a variable for the name of the macro doesn't
> work. 

I think FreeMarker has had this for 6 years or so.

<#assign myMacro = .vars[macroName]>
<@myMacro />

It looks in the special built-in .vars hash to find the variable 
associated with the string in macroName and the resulting expression is 
a macro. It can be assigned to a variable like myMacro and invoked, as 
in the second line, or you could just write it in slightly more 
obfuscated style in one line:

<@.vars[macroName]/>

This isn't possible in Velocity because of some, you know, first order 
implementation mistakes AFAICS.

> 
> So I thought instead of using a macro call I could just implement a
> directive that renders another .vm file with the same context and the
> same Writer - similar to parse but with the option of passing
> parameters. So that's what I did. 

Yeah, I see the motivation but it's still a bit of a hack. It means that 
you need a separate file for each macro, doesn't it? I really think it's 
easier to use a template engine that simply allows for this usage 
pattern as part of its core feature set.


> And with the three directives I have
> attached you can do something like this:
> 
> #call($myMacro {"arg1": true, "arg2":false})

In FreeMarker, (and I'm assuming that $myMacro contains the macro to be 
invoked by name) that's:

<#assign macroToInvoke = .vars[myMacro]>
<@macroToInvoke arg1=true arg2=false />

and again, it could be done in one line with:

<@.vars[myMacro] arg1=true arg2=false />


> 
> The $myMacro variable has to resolve to a fileName (you can set the
> directory for this, so you don't have to give the full path, and you can
> skip the .vm ending). The second parameter is a map that is added to the
> context under the name "args" - the "macro" can access the parameters
> with $args.arg1. 

One drawback, which is the reason you use a map here is is that you're 
any parameters to main overall context. In FreeMarker, it works as it 
should sensibly, the arg1 and arg2 are local, only defined in the body 
of the macro.

>The "macro" itself, is nothing but a .vm file 

If you use macros extensively you're going to have a lot of separate 
files. IMO, it makes more sense to be able to group related macros in 
the same file.

> 
> You can also do this:
> 
> #callBlock(collapsibleSection {"isCollapsed":$collapsed, "title":"My
> Section"})
>  My section content.....
> #end


> 
> Where your collapsibleSection.vm file could look like this:
> 
 > #callBlock(collapsibleSection {"isCollapsed":$collapsed, "title":"My
 > Section"})
 > My section content.....
 > #end


I think the FreeMarker syntax is potentially simpler. There's none of 
this args.title stuff or having to put things in a separate file and all 
that. You'd write the macro as:

<#macro collapsibleSection isCollapsed, title>
   <table><th><td>${title}</td></th>
    <#if !isCollapsed>
      <#nested>
    </#if>
    </table>
</#macro>


<@collapsibleSection collapsed "My Section">
    My section content
</@>

or in more verbose form:

<@collapsibleSection isCollapsed=collapsed title="My Section">
    My section content
</...@collapsibleSection>

> 
> Where the #content() directive will just render the body of the
> callBlock directive - in this case " My section content.....".

Uh huh, yeah,... revolutionary! ;-)

> 
> 
> So have a look at the attached code, if you have similar problems with
> macros - it is quite short and should be easy to understand.
> Maybe something like this should be added for the 1.6 version - or the
> whole macro concept could be converted to a solution like that - leaving
> the existing syntax intact.

The idea (though hardly new :-)) is of course quite right and the 
ability to do this kind of thing really should be considered very basic 
to a template engine, particularly when you're using it to generate HTML 
or similar markup. The problem, I think, is that if you compare it to a 
competing template engine where this functionality has been implemented 
as part of the core, you've got a lot of rather awkward syntax, and 
strange artificial rules, like putting the macro in its own text file 
and referring to the arguments as args.argName and all that. Also, 
you're not declaring the names (or number of) parameters that the macro 
takes, so using a set of macros written this way is going to be 
significantly more error-prone. FreeMarker will say, "Hey, I expected 2 
args to macro collapsibleSection and only got 1" or whatever. Especially 
given the flakey way that Velocity handles undefined or missing values, 
(See: http://in.relation.to/Bloggers/AStoryAboutFreeMarkerAndVelocity ) 
this could make things all rather error-prone.

Anyway, it is good to see someone who wants to give back and I hope my 
comments are useful to you.

Jonathan Revusky
--
lead developer, FreeMarker project, http://freemarker.org/

Velocity or FreeMarker: Looking at 5 Years of Practical Experience
http://freemarker.blogspot.com/2007/12/velocity-of-freemarker-looking-at-5.html


> 
> 
> Best regards,
> 
> Guido Deinhammer
> 
> Btw: we have also added another cool directive that allows partial page
> rendering...but I didn't have time to write it up yet...
> 
> 
> ------------------------------------------------------------------------
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
> For additional commands, e-mail: dev-help@velocity.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org