Feedback needed for an ongoing open source project: Cambridge Template Engine
Erdinc Yilmazel
Reinier Zwitserloot
good all by itself (running the template file directly in a browser),
or if at least you can start up some lightweight standalone template
runner.
Running a template in a browser is basically impossible; even with
fancy javascript, getting includes / framing right is too complicated.
Removing the notion of 'include' from a template language is a very
bad idea, though, which leaves the lightweight standalone option, but
that doesn't work very well without a few features of the template. To
wit:
- Every aspect needs example information. So, instead of {#key.name},
you need: <a:value key="key.name">Example of what this may look like</
a:value>.
- pulled in resources (javascript, images, css, etc) have paths, and
these paths need to be resolved by the stand-alone template runner.
usually a simple project-wide configuration that maps web paths to
paths relative to the project dir is enough (e.g, /css/* should go to
disk: ./web/css/*)
- loops need to have a way of having multiple iterations, with each
iteration beyond the first serving only as example code. Embracing
this also naturally leads to a nice syntax for having suffixes,
prefixes, and infixes for loops, as well as an exceptional case for
the empty loop:
<a:foreach key="somekey">
<table><thead><tr><td>name</td><td>age2</td></tr></thead><tbody>
<tr a:iteration><td a:value="name">Alan Smithee</td><td
a:value="age">42</td></tr>
<tr><td colspan="2"><a href="#top">Back to top</a></td></tr>
<tr a:iteration><td>John Smith</td><td>84</td></tr>
</tbody></table>
</a:foreach>
<a:ifempty style="display:none">
<div class="errorMessage">0 records found</div>
</a>
So, what's happening here?
First off, The entire line that starts with <table> and ends with
<tbody> is the loop prefix, as it precedes the first iteration.
The <tr><td a:value="name">...</tr> line is the actual loop content
(as it is the content of the first iteration).
The back to top link is the link infix - and will be inserted in
between each loop.
The second iteration is there just for show. It is ignored during
template processing, but its there when checking out the template to
see if it looks good. You can't tell if something looks like it should
if you can't stick a bunch of lorem ipsem in there, and running the
whole server, even just the test environment, is a lot more effort
compared to a completely stand alone program. It also keeps the 'test'
data for the design where it belongs: In the template.
Finally, there's a way to skip the entirety of the loop (no table at
all), and show something else, in case there aren't any entries to
loop through. This bit is mostly optional depending on how your
template handles ifs. If ifs work on truthy/falsy behaviour, and loops
work by way of collections, and the empty collection is falsy, doing
this with an if/else around the foreach is simpler than introducing
more syntax to explicitly deal with empty loops.
You can apply the same strategy to keeping the template nice and
maintainable; for example, it would be nice if you can state someplace
in the template that ALL instances of "foobar" are to be replaced with
a java-side supplied name. So, if, for example, I have a webpage that
is about a website (some sort of analytics or some such), I could say
that anytime "wikipedia.org" is used in the template, consider it
reads {#server.name}. This makes writing templates endlessly easier,
as web design isn't something you should do with a programmer's
mindset. You'll need to be aware of location - 'wikipedia.org' in a
tag attribute should be escaped differently than when its in text
someplace.
On Jan 4, 4:46 pm, Erdinc Yilmazel <erdincyilma...@gmail.com> wrote:
> Hi everybody, I've been working on a new template engine that may be used in
> web application development as an alternative to Freemarker, JSP etc. It is
> still in active development and I desperately need feedback from experienced
> java developers at this point to shape its usage scenarios and its API. If
> you are interested to have a look at it, please go tohttp://code.google.com/p/cambridge/where you can view the Wiki or checkout
Dominic Mitchell
Hi everybody, I've been working on a new template engine that may be used in web application development as an alternative to Freemarker, JSP etc. It is still in active development and I desperately need feedback from experienced java developers at this point to shape its usage scenarios and its API. If you are interested to have a look at it, please go to http://code.google.com/p/cambridge/ where you can view the Wiki or checkout the source code. Cambridge Template Engine is an open source library with Apache 2 license.
The one thing that jumped out at me (from the docs — I haven't had a chance to play yet) is how you handle escaping. Or don't, I'm not sure. You do state that “Cambridge is designed especially for generating HTML, XML or any markup content,” so I figure it's important to be able to produce such output correctly.
For example, if I set the name variable to <script>alert('hi!')</script>, and run it through the template <h1>${name}</h1> then does Cambridge output:
- <h1><script>alert('hi!')</script></h1>
- <h1><script>alert('hi!')</script></h1>
Thankfully modern templating systems are starting to behave like this (both rails and django now escape by default). It's shocking quite how long this problem has been around though.
-Dom
Erdinc Yilmazel
The one thing that jumped out at me (from the docs — I haven't had a chance to play yet) is how you handle escaping. Or don't, I'm not sure. You do state that “Cambridge is designed especially for generating HTML, XML or any markup content,” so I figure it's important to be able to produce such output correctly.
For example, if I set the name variable to <script>alert('hi!')</script>, and run it through the template <h1>${name}</h1> then does Cambridge output:
- <h1><script>alert('hi!')</script></h1>
- <h1><script>alert('hi!')</script></h1>
Dominic Mitchell
The one thing that jumped out at me (from the docs — I haven't had a chance to play yet) is how you handle escaping. Or don't, I'm not sure. You do state that “Cambridge is designed especially for generating HTML, XML or any markup content,” so I figure it's important to be able to produce such output correctly.
For example, if I set the name variable to <script>alert('hi!')</script>, and run it through the template <h1>${name}</h1> then does Cambridge output:
- <h1><script>alert('hi!')</script></h1>
- <h1><script>alert('hi!')</script></h1>
In Cambridge, the escaping is handled by filters, which are not documented on the wiki yet. By default, Cambridge currently outputs any text as it is, but there is a filter named escape that provides this functionality. Instead of writing ${name}, if you write ${name}(escape) it will print <h1><script>alert('hi!')</script></h1>. What I'm not sure is if this should be the default behaviour or not. Maybe escaping by default is better.
That's great to hear. Please, please, make this the default. You'll save yourself a lot of trouble down the road.
The filters can also be chained using the | character, for instance you can write ${name}(escape|upper) and get the output in upper case.
-Dom