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