Re: User defined directives as first-class citizens & WRAPPER directive

Tuesday, May 18, 2010, 4:17:37 PM, Phil Ventura wrote:

> Our development team is currently working on moving from the
> (Perl-based) Template Toolkit to Freemarker.  One of the directives
> that Template Toolkit provides and is used in a large number of our
> existing template files is named WRAPPER
> (http://template-toolkit.org/docs/manual/Directives.html#section_WRAPPER).
>
> Here's the basic idea implemented as a Freemarker macro:
>
> <#macro wrapper include>
>   <#local content>
>     <#nested>
>   </#local>
>   <#include include>
> </#macro>

You may just should define a macro with some common name like "main"
in each templates that you want to use as a wrapper, and then call the
"main" macro in it, which then can use #nested as it meant to be. Or,
you should collect all the possible wrappers into a single file (that
file thus acts as a macro library); that's how FM was designed to be
used. It uses macros as the basic building component, not template
files.

> So, given the .ftl files,
> wrapper.ftl:
>
> header info
>
> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>
> ${content}
>
> ----------------------------------------------------------------------
>
> footer info
>
> and, simple.ftl:
>
> <@wrapper include="/wrapper.ftl">
>
>   <p>Wrap this.</p>
>
> </wrapper>
>
> It produces:
>
> header info
>
> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>
>
>   <p>Wrap this.</p>
>
>
>
> ----------------------------------------------------------------------
>
> footer info
>
> Since our production team uses WRAPPER so frequently, I'd like to
> be able to add it as a directive.  However, when reading up on
> creating my own directive in Java
> (http://freemarker.sourceforge.net/docs/pgui_datamodel_directive.html)
> it appears that the syntax for using a user defined directive is
> different from that used for the built-in directives.

Yes.

> So, my question is, are there plans to make (Java) user defined
> directives to use the same syntax as the built-ins?

No, at least not in the foreseeable future. Allowing that would either
make it impossible to extend the core with new directives without
breaking backward-compatibility, or(/and) it would be quite confusing.
Currently, calls to core directives can be identified and be bound to
the target directive before calling the template, because no
template-execution-time circumstances can make the meaning of the tag
different. It makes things predicable, typos can be detected early,
and looking at the templates you can be sure what's called there.
(Only few languages try to get away without a bunch reserved names...
and FM is not one of them.)

(Otherwise I know this "I need my own directives look like core
directives" problem... Especially outside the web-page field it can be
legitimate. For a correct solution the template engine had to support
defining custom template languages. I mean, without dirty patching and
re-building... but sadly FreeMarker doesn't support that.)

> If so, how soon is this expected? If not, is there interest in
> adding a WRAPPER directive to the built-ins? Looking at the source,
> it appears that it simply requires a change to the JavaCC grammar
> together with a class definition both of which are similar to what
> is done with Include.

It's rather that the parser could just assume that whatever <#foo>
stuff where the name ("foo") is not recognized is just the same as
<@foo>. And that's it. But that would cause all the
backward-compatibility issues and other mess I referred to earlier.

> --
> Phil Ventura, Ph.D.
> Software Engineer
> Research & Development Group
> Velocitude
> Fort Lauderdale, FL

-- 
Best regards,
 Daniel Dekany


------------------------------------------------------------------------------