Template engine v2

[Geert Bevin]

Hey,

I've aggregated some of the syntax experiments and design exercises that I've been doing for the new version of the template engine.

It's located here:
https://github.com/gbevin/rife/wiki/Templates-v2-discussion

Here's the current WIP feature overview, it assumes much of the v1 template API is in place:

* new template syntax, based on snip and gap instead of B, V, BV and BA
* key design parts that were taken over from v1:
* gaps are filled in with content and can have default content
* snippets are always stripped away during rendering
* during template modifications, each snip and gap preserve their identity
and are only resolved to text when the template is explicitly rendered
* templates don't assume any particular text syntax (like XML or so), they
purely operate on text and don't parse anything besides the template engine
tags
* gap (previously V) tags are not shown anymore when no content is set
* gaps and snippets support actions: setAs:, addTo: with optional
conditions: when:, unless:
* when they have actions, they can be anonymous
* each template has an execution context (POJO instance), whose methods are
used to resolve non standard actions or when conditions
* template instance can also have named context variables that can be set and
whose methods can also be used for actions or when conditions
* when: or unless: require an argument that resolve to methods in the execution
context and have to return boolean
* actions are purely for manipulating or generating template content, they
receive the action argument, tag's content and the template instance
* gaps will evaluate the return values of action methods and render them as
content
* load tag will include the content of another template at instantiation time
of the template instance
* convention packages for classes, set a base package

Any thoughts, ideas?

Take care,

Geert

[Josh Hansen]

Hi Geert,

On 6/23/2013 11:53 PM, Geert Bevin wrote:
> Hey,
>
> I've aggregated some of the syntax experiments and design exercises
> that I've been doing for the new version of the template engine.
>
> It's located here:
> https://github.com/gbevin/rife/wiki/Templates-v2-discussion
>
> Here's the current WIP feature overview, it assumes much of the v1 template API is in place:
>
> * new template syntax, based on snip and gap instead of B, V, BV and BA

You didn't mention 'C', which is one of my favorite tags! It's really
nice to be able to clearly indicate a comment and know that it will
never be compiled or transmitted to the browser. Very handy for
commenting JavaScript, unusual/unclear block relationships, and omitting
(disabling) entire chunks of HTML and RIFE tags for testing.

Regarding naming, I like the V, B, etc. names since they are short. The
tag names are obscure at first, but they aren't complicated, and the
abbreviated syntax is nice since Eclipse doesn't know how to
auto-complete them (so there isn't much typing to do).

> * key design parts that were taken over from v1:
> * gaps are filled in with content and can have default content
> * snippets are always stripped away during rendering
> * during template modifications, each snip and gap preserve their identity
> and are only resolved to text when the template is explicitly rendered
> * templates don't assume any particular text syntax (like XML or so), they
> purely operate on text and don't parse anything besides the template engine
> tags

All good stuff.

XML style tags are particularly nice when editing HTML:
* Eclipse can match the start and end tags, and allow you to click to
conceal the whole block. This is really handy for focusing on certain
parts of the code, as well as trying to figure out where the extra (or
missing) end tag is.
* When typing a start tag, Eclipse auto-adds the matching end tag.
Convenient!
* It encourages well-formed documents, specifically proper nesting.

The main downside to the XML style tags is that they are all
red-underlined in Eclipse since it doesn't know what they are and can't
validate them.

> * gap (previously V) tags are not shown anymore when no content is set

This will be nice. Most of my V tags are written with explicit
beginning and ending tags (e.g. "<r:v name=...></r:v>") to avoid empty
tags showing up in the output.

> * gaps and snippets support actions: setAs:, addTo: with optional
> conditions: when:, unless:
> * when they have actions, they can be anonymous
> * each template has an execution context (POJO instance), whose methods are
> used to resolve non standard actions or when conditions

It will be interesting to how the last two work (anonymous, and methods
resolving non-standard actions). I find that I put presentation logic
into the element since I don't have programming constructs in the
templates. These sounds like features that would allow (encourage)
presentation logic to be more clearly isolated from business logic
and/or marshaling logic.

> * template instance can also have named context variables that can be set and
> whose methods can also be used for actions or when conditions
> * when: or unless: require an argument that resolve to methods in the execution
> context and have to return boolean
> * actions are purely for manipulating or generating template content, they
> receive the action argument, tag's content and the template instance
> * gaps will evaluate the return values of action methods and render them as
> content
> * load tag will include the content of another template at instantiation time
> of the template instance
> * convention packages for classes, set a base package

I didn't see a description of "convention packages for classes, ...".

> Any thoughts, ideas?

An idea for a new tag...

One idiom I started using is to have a concealment block for B, BV, and
BA tags.
------------------------------------------------
<html>
<head>
</head>
<body>
<r:v name="hello"></r:v>

</body>
</html>

<r:b name="CONCEAL_c334ffca3d58d9f2265584519e9020e7">
<r:c>
Send less whitespace to the browser by putting an r:b tag around
sequences of b, bv, and ba tags
</r:c>

<r:b name="hello_bob">Hello, Bob!</r:b>
<r:bv name="hello">Hello, world!</r:bv>
</r:b>
------------------------------------------------

A dedicated tag for this would be nice so it isn't necessary to generate
the unique "CONCEAL_...." block name. Maybe "r:s" (for "surround") or
"r:x" (for "eXternal")?

Josh

[Geert Bevin]

Hi Josh,

Thanks a lot for these suggestions!

> You didn't mention 'C', which is one of my favorite tags! It's really nice to be able to clearly indicate a comment and know that it will never be compiled or transmitted to the browser. Very handy for commenting JavaScript, unusual/unclear block relationships, and omitting (disabling) entire chunks of HTML and RIFE tags for testing.

Good catch, including that now. So that would bring the new version to four main tags:

* snip : which can include gap and snip tags, but snip tags themselves are always removed
* gap : which can contain default text, empty by default
* load : include the source code of another template
* note : whose contents are simply ignored for any processing (not sure about the tag name still, suggestions welcomed)

> Regarding naming, I like the V, B, etc. names since they are short. The tag names are obscure at first, but they aren't complicated, and the abbreviated syntax is nice since Eclipse doesn't know how to auto-complete them (so there isn't much typing to do).

Right, I still think this needs proper attention to strike to right balance between readability, easy adoption and developer comport. Have you looked at the syntax exercises I did here: https://github.com/gbevin/rife/wiki/Templates-v2-discussion ?

I think the new version is much more readable, certainly combined with the actions and conditions.

>> * gap (previously V) tags are not shown anymore when no content is set
>
> This will be nice. Most of my V tags are written with explicit beginning and ending tags (e.g. "<r:v name=...></r:v>") to avoid empty tags showing up in the output.

Indeed, that behaviour was initially done to make it easier to debug missing values in the rendered templates, but in practice I found myself doing exactly the same things, always setting them to empty content.

>> * gaps and snippets support actions: setAs:, addTo: with optional
>> conditions: when:, unless:
>> * when they have actions, they can be anonymous
>> * each template has an execution context (POJO instance), whose methods are
>> used to resolve non standard actions or when conditions
>
> It will be interesting to how the last two work (anonymous, and methods resolving non-standard actions). I find that I put presentation logic into the element since I don't have programming constructs in the templates. These sounds like features that would allow (encourage) presentation logic to be more clearly isolated from business logic and/or marshaling logic.

Yes, that's one of the points. I'm still designing the actions and conditions feature in my mind and any thoughts would be very welcome.

Some things that crossed my mind:

* instead of having a single execution context, maybe have a list that is evaluated in order, going to the next actions or conditions if none are found in earlier ones. This could then allow all non business logic to be totally extracted. Downside is that things could become too magical or obscure ("where's that action coming from", "damn I didn't see the other action in a previous context", …)

* allowing actions to be on properties (and properties of properties) of the main execution context, this would make the links more predictable but the templates a lot less readable. It would also require boilerplate code to be added to each execution context, just to get at the actions and conditions.

* allowing pure functional static actions that are tied to classes and static public methods. I'm personally reluctant since I fear the propagation of public static methods and classes that turn into stateless method collections. I find that it makes code very difficult to inspect and maintain.

>> * convention packages for classes, set a base package
>

> I didn't see a description of "convention packages for classes, …".

I was thinking that it might be useful to support top-level packages that are used for retrieving classes and resources without any configuration: templates, elements, sites, … Of course, it should still be possible to separate into another package hierarchy, but these convention top-level packages could make coding up simple sites and examples very easy and without any configuration.

>> Any thoughts, ideas?
>
> An idea for a new tag...
>
> One idiom I started using is to have a concealment block for B, BV, and BA tags.
> ------------------------------------------------
> <html>
> <head>
> </head>
> <body>
> <r:v name="hello"></r:v>
>
> </body>
> </html>
>
> <r:b name="CONCEAL_c334ffca3d58d9f2265584519e9020e7">
> <r:c>
> Send less whitespace to the browser by putting an r:b tag around sequences of b, bv, and ba tags
> </r:c>
>
> <r:b name="hello_bob">Hello, Bob!</r:b>
> <r:bv name="hello">Hello, world!</r:bv>
> </r:b>
> ------------------------------------------------
>
> A dedicated tag for this would be nice so it isn't necessary to generate the unique "CONCEAL_...." block name. Maybe "r:s" (for "surround") or "r:x" (for "eXternal")?

Interesting, I've done similar things.

Given the idea of allowing anonymous snip tags, maybe those should be allowed without any actions even, then it can just be:

--------------------------------------------------
<html>
<head>
</head>
<body>
<!--gap hello/-->

</body>
</html>

<!--snip-->
<!--note-->
Send less whitespace to the browser by putting an snip tag around sequences of gap and snip tags
<!--/note-->

<!--snip hello_bob-->Hello, Bob!<!--/snip-->
<!--snip setAs:hello-->Hello, world<!--/snip-->
<!--/snip-->
--------------------------------------------------

Take care,

Geert

[Geert Bevin]

Just replying to this separately.

I think that the creation of proper IDE plugins is going to be of capital importance for RIFE v2. So I do plan on having at least Eclipse and IDEA plugins that allow proper highlighting and code navigation features.