[veltools] setting up a Velocimacro library

[Nathan Bubna <na...@esha.com>]

So, to get the ball rolling...  i see three 'F's we need to address:

FOLDER(S)
    - do we want each library (view/tools/struts) to have their own macro
library?  certainly different macros will be associated with different tools
(some struts, some general tools, and some needing no tools at all).

    - or should the macros have a completely separate folder(s) all to
themselves?

<suggestion>i'm think it'd be best to associate macros with the library
they'll be using.  (general ones in view/src/macros, ones that use tools in
tools/src/macros, and struts ones in struts/src/macros)</suggestion>


FILE(S)
    - should each macro have it's own file?  this would make it easy to find
them and update them individually.  of course, this would make the
velocimacro.library property (in the velocity.properties) a nightmare.  then
again, Ant does have a <concat> task that could combine various ones at
build time.

    - or should we keep similar and/or dependent ones in the same file?
(i'm thinking that if we allow macros to depend on other ones at all, they
pretty much have to be kept together to avoid serious headaches.)

   - or should we keep them in one big template?  (please don't support this
:)

<suggestion>my preference is to try and keep them separate for the most
part.  any macros that depend on another should probably be put in same file
(e.g.  #macro( foo ) foo! #end and #macro( bar ) #foo() #end  should be kept
together)</suggestion>


FORMAT
    - should we have a coding convention?  what should it be?

    - how do we want to doc these things so that they come with proper use
instructions and due credit?

<suggestion>
#**
 * this macro is just meant to demonstrate my
 * favorite macro style.  btw, this style is meant
 * to produce readable output while still having
 * readable code.
 *
 * @author <a href="mailto:nathan@esha.com">Some Fool</a>
 *#
#macro( example $whatever $whatNot )
    #set( $output = 'Actual content' )
$!output is best non-tabbed.<br>
    #if( $whatever )
$!whatever is safer with the '!'<br>
    #end##
    #foreach( $woogie in $whatNot )

Curious about the empty line-comments and extra line above these
$!{woogie}s?<br>##
    #end

Then you should try this macro out with and without them.
#end
</suggestion>

did i miss any questions/issues?

Nathan Bubna
nathan@esha.com


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

Re: [veltools] setting up a Velocimacro library

[Bill Burton <bi...@progress.com>]

Nathan Bubna wrote:
> Bill said:
> ...
> 
>>What about examples using those macros?
> 
> 
> yeah, we should probably either work them into existing example apps or
> create a new example app just for demonstrating all these. (i'm leaning
> toward the latter.)

Sounds good.

>>If a tool requires macro support, does that change anything?  Can't see
>>how it would.
> 
> 
> I don't think i'd support creating any tool that required the support of
> macros.

Well, it might not require it but it would simplify the API used by 
designers.

> ...
> 
>>Did someone write a javadoc like tool for Velocity that could be used to
>>generate HTML docs?
> 
> ...
> 
> you know, it seems to me that i remember hearing about something like that
> too, but i don't remember where or what exactly it was.  it might come in
> real handy.

After a bit of looking around the archives, I found Velocidoc at 
http://velocidoc.sourceforge.net/.

> 
> Nathan Bubna
> nathan@esha.com

-Bill


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

Re: [veltools] setting up a Velocimacro library

[Nathan Bubna <na...@esha.com>]

Bill said:
...
> What about examples using those macros?

yeah, we should probably either work them into existing example apps or
create a new example app just for demonstrating all these. (i'm leaning
toward the latter.)

...
> Agreed.  As you suggest, keep separate where possible and use Ant to
> generate one template.  The generated macro template for each type
> should probably be named differently for each of tools, view and struts.
>
> Also, instead of concatenating all the macros into one template, why not
> create a template that does a #parse() to load each macro file?  This
> also makes it easier to comment out macros as it's only a single line
> change.

hmm.  yeah, as long as that works and no one has any complaints, i think
that sounds like a pretty good way to go.

> If a tool requires macro support, does that change anything?  Can't see
> how it would.

I don't think i'd support creating any tool that required the support of
macros.

...
> Did someone write a javadoc like tool for Velocity that could be used to
> generate HTML docs?
...

you know, it seems to me that i remember hearing about something like that
too, but i don't remember where or what exactly it was.  it might come in
real handy.

Nathan Bubna
nathan@esha.com


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

Re: [veltools] setting up a Velocimacro library

[Bill Burton <bi...@progress.com>]

Hello,

Nathan Bubna wrote:
> So, to get the ball rolling...  i see three 'F's we need to address:
> 
> FOLDER(S)
>     - do we want each library (view/tools/struts) to have their own macro
> library?  certainly different macros will be associated with different tools
> (some struts, some general tools, and some needing no tools at all).
> 
>     - or should the macros have a completely separate folder(s) all to
> themselves?
> 
> <suggestion>i'm think it'd be best to associate macros with the library
> they'll be using.  (general ones in view/src/macros, ones that use tools in
> tools/src/macros, and struts ones in struts/src/macros)</suggestion>

Agreed.

What about examples using those macros?

> 
> 
> FILE(S)
>     - should each macro have it's own file?  this would make it easy to find
> them and update them individually.  of course, this would make the
> velocimacro.library property (in the velocity.properties) a nightmare.  then
> again, Ant does have a <concat> task that could combine various ones at
> build time.
> 
>     - or should we keep similar and/or dependent ones in the same file?
> (i'm thinking that if we allow macros to depend on other ones at all, they
> pretty much have to be kept together to avoid serious headaches.)
> 
>    - or should we keep them in one big template?  (please don't support this
> :)
> 
> <suggestion>my preference is to try and keep them separate for the most
> part.  any macros that depend on another should probably be put in same file
> (e.g.  #macro( foo ) foo! #end and #macro( bar ) #foo() #end  should be kept
> together)</suggestion>

Agreed.  As you suggest, keep separate where possible and use Ant to 
generate one template.  The generated macro template for each type 
should probably be named differently for each of tools, view and struts.

Also, instead of concatenating all the macros into one template, why not 
create a template that does a #parse() to load each macro file?  This 
also makes it easier to comment out macros as it's only a single line 
change.

If a tool requires macro support, does that change anything?  Can't see 
how it would.

> 
> FORMAT
>     - should we have a coding convention?  what should it be?
> 
>     - how do we want to doc these things so that they come with proper use
> instructions and due credit?
> 
> <suggestion>
> #**
>  * this macro is just meant to demonstrate my
>  * favorite macro style.  btw, this style is meant
>  * to produce readable output while still having
>  * readable code.
>  *
>  * @author <a href="mailto:nathan@esha.com">Some Fool</a>
>  *#
> #macro( example $whatever $whatNot )
>     #set( $output = 'Actual content' )
> $!output is best non-tabbed.<br>
>     #if( $whatever )
> $!whatever is safer with the '!'<br>
>     #end##
>     #foreach( $woogie in $whatNot )
> 
> Curious about the empty line-comments and extra line above these
> $!{woogie}s?<br>##
>     #end
> 
> Then you should try this macro out with and without them.
> #end
> </suggestion>
> 
> did i miss any questions/issues?

Did someone write a javadoc like tool for Velocity that could be used to 
generate HTML docs?

> 
> Nathan Bubna
> nathan@esha.com

-Bill


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