[FreeMarker-user] Several doubtful points on the manual

[Albert Kam]

I have several points to ask based on the manual, please share your views :

(1) http://freemarker.sourceforge.net/docs/dgui_datamodel_types.html

The main reason is that the result of functions are subject to automatic

XML-escaping (due to the nature of ${...}),
Is it true that the function return value and the result of interpolation
are automatically escaped ?
I tried this :
<#assign myvar="hello&world">

<#function hello>
<#return "<inside&function">
</#function>

${myvar}
${hello()}

with this result :
hello&world
<inside&function

while the output of user-defined directives are not (due to the nature of

<@...>; its output is assumed to be markup, and hence already escaped).
Is it true that user defined directives are automatically escaped also ?
But i think not, since we have the ?html and #escape for this, am i right ?

(2) http://freemarker.org/docs/dgui_misc_userdefdir.html

also you can use complex expression on the left side of = (e.g.

someParam=(price + 50)*1.25)
Should be on the --right-- side instead of the --left-- side ?

(3) http://freemarker.org/docs/dgui_template_valueinsertion.html

Guide for inserting date/time values
If the expression evaluates to a date then the numerical value will be

transformed to a text according to a default format.
Should be the --date-- value instead of --numerical-- value ?

(4) http://freemarker.sourceforge.net/docs/dgui_misc_whitespace.html

It is useful for templates that contain macro definitions only (and some

other non-outputting directives), because it removes the line-breaks that
you use between the macro definitions and between the other top-level
directives to improve the readability of the template
How is it improving the readability of the 'library' template when what the
developer see is always the unparsed version ?

Regards from Jakarta,
Albert

[Denis Bredelet]

Post by Albert Kam
(1) http://freemarker.sourceforge.net/docs/dgui_datamodel_types.html

The main reason is that the result of functions are subject to automatic XML-escaping (due to the nature of ${...}),

Is it true that the function return value and the result of interpolation are automatically escaped ?

It is subject to escaping *if* you use #escape. Not so for macro calls.

Post by Albert Kam
<#assign myvar="hello&world">
<#function hello>
<#return "<inside&function">
</#function>
${myvar}
${hello()}
hello&world
<inside&function
Is it true that user defined directives are automatically escaped also ? But i think not, since we have the ?html and #escape for this, am i right ?
(2) http://freemarker.org/docs/dgui_misc_userdefdir.html

also you can use complex expression on the left side of = (e.g. someParam=(price + 50)*1.25)

Should be on the --right-- side instead of the --left-- side ?

Yes.

Post by Albert Kam
(3) http://freemarker.org/docs/dgui_template_valueinsertion.html

Guide for inserting date/time values
If the expression evaluates to a date then the numerical value will be transformed to a text according to a default format.

Should be the --date-- value instead of --numerical-- value ?

Technically dates are usually time stamps since the epoch, but I agree with you.

Post by Albert Kam
(4) http://freemarker.sourceforge.net/docs/dgui_misc_whitespace.html

It is useful for templates that contain macro definitions only (and some other non-outputting directives), because it removes the line-breaks that you use between the macro definitions and between the other top-level directives to improve the readability of the template

How is it improving the readability of the 'library' template when what the developer see is always the unparsed version ?

Exactly, this allows you to add newlines in the template without breaking the layout. Hence it improves readability.

Post by Albert Kam
Regards from Jakarta,
Albert
--
Do not pursue the past. Do not lose yourself in the future.
The past no longer is. The future has not yet come.
Looking deeply at life as it is in the very here and now,
the practitioner dwells in stability and freedom.
(Thich Nhat Hanh)
------------------------------------------------------------------------------
Symantec Endpoint Protection 12 positioned as A LEADER in The Forrester
Wave(TM): Endpoint Security, Q1 2013 and "remains a good choice" in the
endpoint security space. For insight on selecting the right partner to
tackle endpoint security challenges, access the full report.
http://p.sf.net/sfu/symantec-dev2dev
_______________________________________________
FreeMarker-user mailing list
https://lists.sourceforge.net/lists/listinfo/freemarker-user

[Albert Kam]

Hello, thank you for the response ..

Post by Denis Bredelet
It is subject to escaping *if* you use #escape.

Did you mean the function's result ? That's why i was doubtful, because it
says in the manual 'subject to --automatic-- xml escaping.

Post by Denis Bredelet
Not so for macro calls.

Did you mean macro calls will result in escaped content automatically ?

Post by Denis Bredelet
Exactly, this allows you to add newlines in the template without breaking

the layout. Hence it improves readability.
Ah, makes sense ! But in the context of 'library' template with only macros
only, i imagine we can add newlines also without strip_text, and not
breaking anything, because the what is important is the macros, not the
newlines or any other texts outside the macros, am i correct ?

Post by Denis Bredelet
(1) http://freemarker.sourceforge.net/docs/dgui_datamodel_types.html

The main reason is that the result of functions are subject to automatic

XML-escaping (due to the nature of ${...}),
Is it true that the function return value and the result of interpolation
are automatically escaped ?
It is subject to escaping *if* you use #escape. Not so for macro calls.
<#assign myvar="hello&world">
<#function hello>
<#return "<inside&function">
</#function>
${myvar}
${hello()}
hello&world
<inside&function

while the output of user-defined directives are not (due to the nature

Is it true that user defined directives are automatically escaped also ?
But i think not, since we have the ?html and #escape for this, am i right ?
(2) http://freemarker.org/docs/dgui_misc_userdefdir.html

also you can use complex expression on the left side of = (e.g.

someParam=(price + 50)*1.25)
Should be on the --right-- side instead of the --left-- side ?
Yes.
(3) http://freemarker.org/docs/dgui_template_valueinsertion.html

Guide for inserting date/time values
If the expression evaluates to a date then the numerical value will be

transformed to a text according to a default format.
Should be the --date-- value instead of --numerical-- value ?
Technically dates are usually time stamps since the epoch, but I agree with you.
(4) http://freemarker.sourceforge.net/docs/dgui_misc_whitespace.html

It is useful for templates that contain macro definitions only (and some

other non-outputting directives), because it removes the line-breaks that
you use between the macro definitions and between the other top-level
directives to improve the readability of the template
How is it improving the readability of the 'library' template when what
the developer see is always the unparsed version ?
Exactly, this allows you to add newlines in the template without breaking
the layout. Hence it improves readability.
Regards from Jakarta,
Albert
--
Do not pursue the past. Do not lose yourself in the future.
The past no longer is. The future has not yet come.
Looking deeply at life as it is in the very here and now,
the practitioner dwells in stability and freedom.
(Thich Nhat Hanh)
------------------------------------------------------------------------------
Symantec Endpoint Protection 12 positioned as A LEADER in The Forrester
Wave(TM): Endpoint Security, Q1 2013 and "remains a good choice" in the
endpoint security space. For insight on selecting the right partner to
tackle endpoint security challenges, access the full report.
http://p.sf.net/sfu/symantec-dev2dev
_______________________________________________
FreeMarker-user mailing list
https://lists.sourceforge.net/lists/listinfo/freemarker-user
------------------------------------------------------------------------------
Symantec Endpoint Protection 12 positioned as A LEADER in The Forrester
Wave(TM): Endpoint Security, Q1 2013 and "remains a good choice" in the
endpoint security space. For insight on selecting the right partner to
tackle endpoint security challenges, access the full report.
http://p.sf.net/sfu/symantec-dev2dev
_______________________________________________
FreeMarker-user mailing list
https://lists.sourceforge.net/lists/listinfo/freemarker-user

[Daniel Dekany]

Post by Albert Kam
Hello, thank you for the response ..

Post by Denis Bredelet
It is subject to escaping *if* you use #escape.

Did you mean the function's result ? That's why i was doubtful,
because it says in the manual 'subject to --automatic-- xml escaping.

The only thing that might applies auto-escaping is `${...}`, but to
insert the values of functions till 2.3.30 you can only use `${...}`.

Post by Albert Kam

Post by Denis Bredelet
Not so for macro calls.

Did you mean macro calls will result in escaped content automatically ?

It's assumed to be *already* escaped on the caller side.

Post by Albert Kam

Post by Denis Bredelet
Exactly, this allows you to add newlines in the template without breaking the layout. Hence it improves readability.

Ah, makes sense ! But in the context of 'library' template with
only macros only, i imagine we can add newlines also without
strip_text, and not breaking anything, because the what is important
is the macros, not the newlines or any other texts outside the macros, am i correct ?

Correct, except that the legacy way of pulling in a library is with
#include, which can print to the output of the template that uses it.
--
Best regards,
Daniel Dekany

Post by Albert Kam
(1) http://freemarker.sourceforge.net/docs/dgui_datamodel_types.html

Post by Denis Bredelet
The main reason is that the result of functions are subject to automatic XML-escaping (due to the nature of ${...}),

Is it true that the function return value and the result of
interpolation are automatically escaped ?
It is subject to escaping *if* you use #escape. Not so for macro calls.
<#assign myvar="hello&world">
<#function hello>
<#return "<inside&function">
</#function>
${myvar}
${hello()}
hello&world
<inside&function
Is it true that user defined directives are automatically escaped
also ? But i think not, since we have the ?html and #escape for this, am i right ?
(2) http://freemarker.org/docs/dgui_misc_userdefdir.html

Post by Denis Bredelet
also you can use complex expression on the left side of = (e.g. someParam=(price + 50)*1.25)

Should be on the --right-- side instead of the --left-- side ?
Yes.
(3) http://freemarker.org/docs/dgui_template_valueinsertion.html

Post by Denis Bredelet
Guide for inserting date/time values
If the expression evaluates to a date then the numerical value will be transformed to a text according to a default format.

Should be the --date-- value instead of --numerical-- value ?
Technically dates are usually time stamps since the epoch, but I agree with you.
(4) http://freemarker.sourceforge.net/docs/dgui_misc_whitespace.html

Post by Denis Bredelet
It is useful for templates that contain macro definitions only (and some other non-outputting directives), because it removes the line-breaks that you use between the macro definitions and between the other top-level directives to improve the readability of the template

How is it improving the readability of the 'library' template when
what the developer see is always the unparsed version ?
Exactly, this allows you to add newlines in the template without
breaking the layout. Hence it improves readability.
Regards from Jakarta,
Albert
--
Do not pursue the past. Do not lose yourself in the future.
The past no longer is. The future has not yet come.
Looking deeply at life as it is in the very here and now,
the practitioner dwells in stability and freedom.
(Thich Nhat Hanh)

[Daniel Dekany]

Post by Daniel Dekany

Post by Albert Kam
Hello, thank you for the response ..

Post by Denis Bredelet
It is subject to escaping *if* you use #escape.

Did you mean the function's result ? That's why i was doubtful,
because it says in the manual 'subject to --automatic-- xml escaping.

The only thing that might applies auto-escaping is `${...}`, but to
insert the values of functions till 2.3.30

I meant 2.3.20. Here's the relevant quote from earlier mailing, which
also clarifies what's the difference between #functions and
#macros/directives:

http://thread.gmane.org/gmane.comp.web.freemarker.devel/7950

Post by Daniel Dekany
you can only use `${...}`.

Post by Albert Kam

Post by Denis Bredelet
Not so for macro calls.

Did you mean macro calls will result in escaped content automatically ?

It's assumed to be *already* escaped on the caller side.

Post by Albert Kam

Post by Denis Bredelet
Exactly, this allows you to add newlines in the template without breaking the layout. Hence it improves readability.

Ah, makes sense ! But in the context of 'library' template with
only macros only, i imagine we can add newlines also without
strip_text, and not breaking anything, because the what is important
is the macros, not the newlines or any other texts outside the macros, am i correct ?

Correct, except that the legacy way of pulling in a library is with
#include, which can print to the output of the template that uses it.

[Albert Kam]

Thanks for the thread explaining the best practices for the macro, function
and interpolation.
So basically the conclusion that i got is that there is nothing that is
--automatically-- escaped with the current stable version.
I guess its the 'automatic' part in the manual that i pasted earlier that
got me doubtful.

Regards from Jakarta,
Albert Kam

Post by Daniel Dekany

Post by Daniel Dekany

Post by Albert Kam
Hello, thank you for the response ..

Post by Denis Bredelet
It is subject to escaping *if* you use #escape.

Did you mean the function's result ? That's why i was doubtful,
because it says in the manual 'subject to --automatic-- xml escaping.

The only thing that might applies auto-escaping is `${...}`, but to
insert the values of functions till 2.3.30

I meant 2.3.20. Here's the relevant quote from earlier mailing, which
also clarifies what's the difference between #functions and
http://thread.gmane.org/gmane.comp.web.freemarker.devel/7950

Post by Daniel Dekany
you can only use `${...}`.

Post by Albert Kam

Post by Denis Bredelet
Not so for macro calls.

Did you mean macro calls will result in escaped content automatically ?

It's assumed to be *already* escaped on the caller side.

Post by Albert Kam

Post by Denis Bredelet
Exactly, this allows you to add newlines in the template without

breaking the layout. Hence it improves readability.

Post by Daniel Dekany

Post by Albert Kam
Ah, makes sense ! But in the context of 'library' template with
only macros only, i imagine we can add newlines also without
strip_text, and not breaking anything, because the what is important
is the macros, not the newlines or any other texts outside the macros,

am i correct ?

Post by Daniel Dekany
Correct, except that the legacy way of pulling in a library is with
#include, which can print to the output of the template that uses it.

--
Best regards,
Daniel Dekany
------------------------------------------------------------------------------
Symantec Endpoint Protection 12 positioned as A LEADER in The Forrester
Wave(TM): Endpoint Security, Q1 2013 and "remains a good choice" in the
endpoint security space. For insight on selecting the right partner to
tackle endpoint security challenges, access the full report.
http://p.sf.net/sfu/symantec-dev2dev
_______________________________________________
FreeMarker-user mailing list
https://lists.sourceforge.net/lists/listinfo/freemarker-user

[Daniel Dekany]

Thanks for the thread explaining the best practices for the macro, function and interpolation.
So basically the conclusion that i got is that there is nothing
that is --automatically-- escaped with the current stable version.

I guess putting the whole template inside #escape counts as automatic
escaping of ${...}-s. Well, it's not entirely automatic... but I used
to put templates into it.

I guess its the 'automatic' part in the manual that i pasted earlier that got me doubtful.
Regards from Jakarta,
Albert Kam

Post by Daniel Dekany

Post by Albert Kam
Hello, thank you for the response ..

Post by Denis Bredelet
It is subject to escaping *if* you use #escape.

Did you mean the function's result ? That's why i was doubtful,
because it says in the manual 'subject to --automatic-- xml escaping.

The only thing that might applies auto-escaping is `${...}`, but to
insert the values of functions till 2.3.30

I meant 2.3.20. Here's the relevant quote from earlier mailing, which
also clarifies what's the difference between #functions and
http://thread.gmane.org/gmane.comp.web.freemarker.devel/7950

Post by Daniel Dekany
you can only use `${...}`.

Post by Albert Kam

Post by Denis Bredelet
Not so for macro calls.

Did you mean macro calls will result in escaped content automatically ?

It's assumed to be *already* escaped on the caller side.

Post by Albert Kam

Post by Denis Bredelet
Exactly, this allows you to add newlines in the template without breaking the layout. Hence it improves readability.

Ah, makes sense ! But in the context of 'library' template with
only macros only, i imagine we can add newlines also without
strip_text, and not breaking anything, because the what is important
is the macros, not the newlines or any other texts outside the macros, am i correct ?

Correct, except that the legacy way of pulling in a library is with
#include, which can print to the output of the template that uses it.

--
Best regards,
Daniel Dekany
------------------------------------------------------------------------------
Symantec Endpoint Protection 12 positioned as A LEADER in The Forrester
Wave(TM): Endpoint Security, Q1 2013 and "remains a good choice" in the
endpoint security space. For insight on selecting the right partner to
tackle endpoint security challenges, access the full report.
http://p.sf.net/sfu/symantec-dev2dev
_______________________________________________
FreeMarker-user mailing list
https://lists.sourceforge.net/lists/listinfo/freemarker-user

[Albert Kam]

Oh, i got what you mean now.

I was stuck with how to enable html escaping for every templates,
and ended up using the solution from here (although i skip the
strip_whitespace part and add it in the configuration setting instead) :
http://watchitlater.com/blog/2011/10/default-html-escape-using-freemarker/

Thank you for your time Daniel !

Regards from Jakarta,
Albert Kam

Post by Albert Kam
Thanks for the thread explaining the best practices for the macro,

function and interpolation.

Post by Albert Kam
So basically the conclusion that i got is that there is nothing
that is --automatically-- escaped with the current stable version.

I guess putting the whole template inside #escape counts as automatic
escaping of ${...}-s. Well, it's not entirely automatic... but I used
to put templates into it.

Post by Albert Kam
I guess its the 'automatic' part in the manual that i pasted earlier

that got me doubtful.

Post by Albert Kam
Regards from Jakarta,
Albert Kam

Post by Daniel Dekany

Post by Albert Kam
Hello, thank you for the response ..

Post by Denis Bredelet
It is subject to escaping *if* you use #escape.

Did you mean the function's result ? That's why i was doubtful,
because it says in the manual 'subject to --automatic-- xml escaping.

The only thing that might applies auto-escaping is `${...}`, but to
insert the values of functions till 2.3.30

I meant 2.3.20. Here's the relevant quote from earlier mailing, which
also clarifies what's the difference between #functions and
http://thread.gmane.org/gmane.comp.web.freemarker.devel/7950

Post by Daniel Dekany
you can only use `${...}`.

Post by Albert Kam

Post by Denis Bredelet
Not so for macro calls.

Did you mean macro calls will result in escaped content automatically ?

It's assumed to be *already* escaped on the caller side.

Post by Albert Kam

Post by Denis Bredelet
Exactly, this allows you to add newlines in the template without

breaking the layout. Hence it improves readability.

Post by Albert Kam

Post by Daniel Dekany

Post by Albert Kam
Ah, makes sense ! But in the context of 'library' template with
only macros only, i imagine we can add newlines also without
strip_text, and not breaking anything, because the what is important
is the macros, not the newlines or any other texts outside the macros,

am i correct ?

Post by Albert Kam

Post by Daniel Dekany
Correct, except that the legacy way of pulling in a library is with
#include, which can print to the output of the template that uses it.

--
Best regards,
Daniel Dekany

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

Post by Albert Kam
Symantec Endpoint Protection 12 positioned as A LEADER in The Forrester
Wave(TM): Endpoint Security, Q1 2013 and "remains a good choice" in the
endpoint security space. For insight on selecting the right partner to
tackle endpoint security challenges, access the full report.
http://p.sf.net/sfu/symantec-dev2dev
_______________________________________________
FreeMarker-user mailing list
https://lists.sourceforge.net/lists/listinfo/freemarker-user

--
Best regards,
Daniel Dekany
------------------------------------------------------------------------------
Symantec Endpoint Protection 12 positioned as A LEADER in The Forrester
Wave(TM): Endpoint Security, Q1 2013 and "remains a good choice" in the
endpoint security space. For insight on selecting the right partner to
tackle endpoint security challenges, access the full report.
http://p.sf.net/sfu/symantec-dev2dev
_______________________________________________
FreeMarker-user mailing list
https://lists.sourceforge.net/lists/listinfo/freemarker-user

[Daniel Dekany]

Post by Albert Kam
(1) http://freemarker.sourceforge.net/docs/dgui_datamodel_types.html

The main reason is that the result of functions are subject to automatic XML-escaping (due to the nature of ${...}),

Is it true that the function return value and the result of
interpolation are automatically escaped ?
<#assign myvar="hello&world">
<#function hello>
<#return "<inside&function">
</#function>
${myvar}
${hello()}
hello&world
<inside&function

The output of `${...}` is escaped only if it's inside a #escape call.
Later maybe it will change so that escaping can be on by default,
without any #escape calls, and actually some users already do that
through a TemplateLoader hack. Anyway, the point is, if you want to
output markup, try not to use `${...}`, and hence functions, because
they aren't meant to be used for that. To generate markup use a macro
or directive.

Post by Albert Kam
Is it true that user defined directives are automatically escaped
also ? But i think not, since we have the ?html and #escape for this, am i right ?

The output of directives is never escaped, because they meant to
something that's already markup. That it's already markup also means
that if the directive (the macro) has contained `${...}`, it had to
ensure that those were properly escaped.

Post by Albert Kam
(2) http://freemarker.org/docs/dgui_misc_userdefdir.html

also you can use complex expression on the left side of = (e.g. someParam=(price + 50)*1.25)

Should be on the --right-- side instead of the --left-- side ?

Ops... right. Will fix it.

Post by Albert Kam
(3) http://freemarker.org/docs/dgui_template_valueinsertion.html

Guide for inserting date/time values
If the expression evaluates to a date then the numerical value will be transformed to a text according to a default format.

Should be the --date-- value instead of --numerical-- value ?

Sure. Also will be fixed.

Post by Albert Kam
(4) http://freemarker.sourceforge.net/docs/dgui_misc_whitespace.html

It is useful for templates that contain macro definitions only (and some other non-outputting directives), because it removes the line-breaks that you use between the macro definitions and between the other top-level directives to improve the readability of the template

How is it improving the readability of the 'library' template when
what the developer see is always the unparsed version ?

That you can add empty lines helps readably. If those empty lines were
include in the output, the library author would omit them, making the
library less readable.

Post by Albert Kam
Regards from Jakarta,
Albert