Proposal: <#p expression> for printing values that deliberately store markup

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Proposal: <#p expression> for printing values that deliberately store markup

Daniel Dekany
I want to able to tell this simple rule of thumb to users:

- Always put the template into <#escape x as x?html>, or when it
  becomes available, just turn on global escaping and forget about it.

- Print values that aren't meant to contain HTML markup with
  `${expression}`. These will be automatically escaped.

- Print values that meant to store HTML markup with
  `<#p expression>`. These will not be automatically escaped, ever.

  In general, what you print with <@...> or <#...>-s (i.e., with
  macros or directives) is never escaped. They meant to generate
  markup, and that's why they look like HTML tags.

You may wonder why not `${expression?noescape}` or something like that.
For two reasons:

- It violates the rule of thumb shown above. It's something that's not
  escaped, meant to generate markup, yet doesn't look like <...>. #p
  is true to the above idea.

  BTW, there's this confusion in many heads about what's the
  difference between a #macro (or a directive) and a #function, and
  why you can't call macros inside expression, and so on. The reason
  of the distinction is basically the above rule of thumb. Only this
  rule wasn't communicated or even executed clearly so far.

- What exactly would be the result of `expression?noescape`? If it's
  just an FTL string, how would ${...} know that it must not be
  escaped? Or what's the result of `foo + bar?noescape`? In a new
  language I probably would have plain-string VS markup-string type,
  but adding it to a 10+ years old language would probably be a too
  brutal change.

You may also wonder what's the problem with:

   <#noescape>${expression}</#noescape>

Well, it's far too ugly for a basic task like this. Other than it's
annoying to type and read back, if many interpolations would print
values that are already markup in a certain template, the author will
possibly feel tempted to remove #escape and use ${exprssion?html} on
the places where the expression value needs to be escaped. Then in
some templates you have to write ?html, in some you must not write
that or you do double-escaping... that's messy and dangerous and
invalidates the rule of thumb shown earlier.

Comments/ideas?

--
Best regards,
 Daniel Dekany


------------------------------------------------------------------------------
Everyone hates slow websites. So do we.
Make your web apps faster with AppDynamics
Download AppDynamics Lite for free today:
http://p.sf.net/sfu/appdyn_d2d_feb
_______________________________________________
FreeMarker-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/freemarker-devel
Reply | Threaded
Open this post in threaded view
|

Re: Proposal: <#p expression> for printing values that deliberately store markup

Denis Bredelet
The proposal looks well thought out.

I will just say that I approve it.

What is the difference between macro and function then?

-- Denis.

> I want to able to tell this simple rule of thumb to users:
>
> - Always put the template into <#escape x as x?html>, or when it
>  becomes available, just turn on global escaping and forget about it.
>
> - Print values that aren't meant to contain HTML markup with
>  `${expression}`. These will be automatically escaped.
>
> - Print values that meant to store HTML markup with
>  `<#p expression>`. These will not be automatically escaped, ever.
>
>  In general, what you print with <@...> or <#...>-s (i.e., with
>  macros or directives) is never escaped. They meant to generate
>  markup, and that's why they look like HTML tags.
>
> You may wonder why not `${expression?noescape}` or something like that.
> For two reasons:
>
> - It violates the rule of thumb shown above. It's something that's not
>  escaped, meant to generate markup, yet doesn't look like <...>. #p
>  is true to the above idea.
>
>  BTW, there's this confusion in many heads about what's the
>  difference between a #macro (or a directive) and a #function, and
>  why you can't call macros inside expression, and so on. The reason
>  of the distinction is basically the above rule of thumb. Only this
>  rule wasn't communicated or even executed clearly so far.
>
> - What exactly would be the result of `expression?noescape`? If it's
>  just an FTL string, how would ${...} know that it must not be
>  escaped? Or what's the result of `foo + bar?noescape`? In a new
>  language I probably would have plain-string VS markup-string type,
>  but adding it to a 10+ years old language would probably be a too
>  brutal change.
>
> You may also wonder what's the problem with:
>
>   <#noescape>${expression}</#noescape>
>
> Well, it's far too ugly for a basic task like this. Other than it's
> annoying to type and read back, if many interpolations would print
> values that are already markup in a certain template, the author will
> possibly feel tempted to remove #escape and use ${exprssion?html} on
> the places where the expression value needs to be escaped. Then in
> some templates you have to write ?html, in some you must not write
> that or you do double-escaping... that's messy and dangerous and
> invalidates the rule of thumb shown earlier.
>
> Comments/ideas?
>
> --
> Best regards,
> Daniel Dekany
>
>
> ------------------------------------------------------------------------------
> Everyone hates slow websites. So do we.
> Make your web apps faster with AppDynamics
> Download AppDynamics Lite for free today:
> http://p.sf.net/sfu/appdyn_d2d_feb
> _______________________________________________
> FreeMarker-devel mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/freemarker-devel

------------------------------------------------------------------------------
Everyone hates slow websites. So do we.
Make your web apps faster with AppDynamics
Download AppDynamics Lite for free today:
http://p.sf.net/sfu/appdyn_d2d_feb
_______________________________________________
FreeMarker-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/freemarker-devel
Reply | Threaded
Open this post in threaded view
|

Re: Proposal: <#p expression> for printing values that deliberately store markup

Daniel Dekany
Sunday, February 24, 2013, 4:38:02 PM, Denis Bredelet wrote:

> The proposal looks well thought out.
>
> I will just say that I approve it.
>
> What is the difference between macro and function then?

Macros meant to be used for generating markup, or for flow control, or
for side-effects. They are basically template fragments. Functions
meant to be used for calculating a value that is usually not markup
(but plain text, number, boolean, sequence, etc). But of course you
can find misuses of these constructs all around...

> -- Denis.
>
>> I want to able to tell this simple rule of thumb to users:
>>
>> - Always put the template into <#escape x as x?html>, or when it
>>  becomes available, just turn on global escaping and forget about it.
>>
>> - Print values that aren't meant to contain HTML markup with
>>  `${expression}`. These will be automatically escaped.
>>
>> - Print values that meant to store HTML markup with
>>  `<#p expression>`. These will not be automatically escaped, ever.
>>
>>  In general, what you print with <@...> or <#...>-s (i.e., with
>>  macros or directives) is never escaped. They meant to generate
>>  markup, and that's why they look like HTML tags.
>>
>> You may wonder why not `${expression?noescape}` or something like that.
>> For two reasons:
>>
>> - It violates the rule of thumb shown above. It's something that's not
>>  escaped, meant to generate markup, yet doesn't look like <...>. #p
>>  is true to the above idea.
>>
>>  BTW, there's this confusion in many heads about what's the
>>  difference between a #macro (or a directive) and a #function, and
>>  why you can't call macros inside expression, and so on. The reason
>>  of the distinction is basically the above rule of thumb. Only this
>>  rule wasn't communicated or even executed clearly so far.
>>
>> - What exactly would be the result of `expression?noescape`? If it's
>>  just an FTL string, how would ${...} know that it must not be
>>  escaped? Or what's the result of `foo + bar?noescape`? In a new
>>  language I probably would have plain-string VS markup-string type,
>>  but adding it to a 10+ years old language would probably be a too
>>  brutal change.
>>
>> You may also wonder what's the problem with:
>>
>>   <#noescape>${expression}</#noescape>
>>
>> Well, it's far too ugly for a basic task like this. Other than it's
>> annoying to type and read back, if many interpolations would print
>> values that are already markup in a certain template, the author will
>> possibly feel tempted to remove #escape and use ${exprssion?html} on
>> the places where the expression value needs to be escaped. Then in
>> some templates you have to write ?html, in some you must not write
>> that or you do double-escaping... that's messy and dangerous and
>> invalidates the rule of thumb shown earlier.
>>
>> Comments/ideas?
>>
>> --
>> Best regards,
>> Daniel Dekany
>>
>>
>> ------------------------------------------------------------------------------
>> Everyone hates slow websites. So do we.
>> Make your web apps faster with AppDynamics
>> Download AppDynamics Lite for free today:
>> http://p.sf.net/sfu/appdyn_d2d_feb
>> _______________________________________________
>> FreeMarker-devel mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/freemarker-devel
>
> ------------------------------------------------------------------------------
> Everyone hates slow websites. So do we.
> Make your web apps faster with AppDynamics
> Download AppDynamics Lite for free today:
> http://p.sf.net/sfu/appdyn_d2d_feb
> _______________________________________________
> FreeMarker-devel mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/freemarker-devel
>

--
Best regards,
 Daniel Dekany


------------------------------------------------------------------------------
Everyone hates slow websites. So do we.
Make your web apps faster with AppDynamics
Download AppDynamics Lite for free today:
http://p.sf.net/sfu/appdyn_d2d_feb
_______________________________________________
FreeMarker-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/freemarker-devel