Issue 4 in json-template: Provide a standard way for formatters to take arguments, e.g. for implementing include statement

[codesite...@google.com]

Updates:
Summary: Provide a standard way for formatters to take arguments, e.g. for
implementing include statement

Comment #12 on issue 4 by a...@chubot.org: Provide a standard way for
formatters to take arguments, e.g. for implementing include statement
http://code.google.com/p/json-template/issues/detail?id=4

(No comment was entered for this change.)

--
You received this message because you are listed in the owner
or CC fields of this issue, or because you starred this issue.
You may adjust your issue notification preferences at:
http://code.google.com/hosting/settings

[codesite...@google.com]

Updates:
Status: Started

Comment #13 on issue 4 by a...@chubot.org: Provide a standard way for

formatters to take arguments, e.g. for implementing include statement
http://code.google.com/p/json-template/issues/detail?id=4

We've agreed on a way to do this -- it still needs to be implemented in
JavaScript
and documented everywhere.

[codesite...@google.com]

Comment #14 on issue 4 by Robert.David.Williams: Provide a standard way for

formatters to take arguments, e.g. for implementing include statement
http://code.google.com/p/json-template/issues/detail?id=4

I recommend implementing a simple template recursion feature such as in
StringTemplate. On the other hand, I strongly recommend against the idea
of tracking
dependencies between templates as described here. Please allow me to
explain...

My desired usage scenario is that I want a simple API for creating an empty
instance
of a template, assembling and inserting my data, then rendering the
template with
that data to obtain a String. The template engine should be aware of and
properly
handle character encoding, probably by forcing me to declare the encoding
of the
template(s) prior to loading.

So, I should be able to do something like the following:

instance = template.create("name")
data = ...(whatever I want, independent of the template API)...
output = instance.render(data)

A crucial feature of this approach is that I should be able to refactor the
template
"name" as much as I want without having to edit the code to use it. In
particular, I
should be able to refactor gracefully from a template in a single file
(known by
"name") to splitting the template up into as many named pieces (separate
files) as I
want. Typically, template "name" represents a single web page, report, or
whatever
other output that I desire.

This feature necessitates a means of invoking the template engine with a
configuration for finding all the template pieces. This might mean a
constructor
that takes a directory (with named templates as files within the
subdirectory tree).
This might mean a single file with templates as named sections within it.
This
might mean a constructor for the template engine that creates an empty
template
holder that allows the user to add named templates at will, via whatever
mechanism
that the user chooses. In JavaScript, the engine could make AJAX calls to
request
empty templates by name from the server (where relevant).

As a consequence, each template instance must have a parent object that
knows how to
resolve and provide any references to other templates. StringTemplate does
this via
a StringTemplateGroup.

However, one of StringTemplate's problems is that the API has gotten way
too complex,
in large part because of this addition of the StringTemplateGroup, plus
some special
syntax to support it, etc. I STRONGLY advocate for keeping your template
language
and the API simple and clean. In particular, if you add such a feature
then I would
make it a separate deliverable/artifact that is optional and separately
testable
(which StringTemplate did not do).

As for the whole dependency thing, I consider it to be a nonissue. If I am
templating a web page, then the browser will trigger the rendering of the
HTML
template by the initial web request. When the browser finds a reference to
the
"external" CSS file, then that web request will trigger the rendering of
the CSS
template. Likewise, the reference to the "external" JavaScript file in the
HTML
template will trigger a web request for the JavaScript template. If I edit
the HTML
template to no longer reference the "external" CSS or JavaScript, then the
browser
won't find them and it won't issue web requests for them. However, I want
to be able
to make that CSS and JavaScript internal by replacing the "external"
references with
"internal" references to the same (sub)templates. I should be able to
switch back
and forth between those implementations without changing my code, and I can
with
StringTemplate.

However, StringTemplate has gotten too complex and they seem to have lost
sight of
the real usage patterns, so their test suite is incomplete and does not
adequately
cover these features. Therefore, in recent versions, this behavior has
become buggy
and the code base has become bloated.

I think that we can avoid a repetition with json-template, and I am
committed to
helping do so.

Best wishes...

[codesite...@google.com]

Comment #15 on issue 4 by andychup: Provide a standard way for formatters

to take arguments, e.g. for implementing include statement
http://code.google.com/p/json-template/issues/detail?id=4

You know I think you'll be pleased with the reuse mechanism(s). It
satisfies the
properties you request, and the API for JSON Template is still dead simple.

The key is that the include mechanisms are implemented as a special case of
"formatters". It's completely on top of the engine, and user
configurable. I wrote
the file system include mechanism in formatters.py, but you can also write
one that
does AJAX calls, etc. like you said. All without modification of the API.

Definitely read this if you haven't:

http://json-template.googlecode.com/svn/trunk/doc/On-Design-Minimalism.html

The implementation now basically a demo, and not really "standardized".
But the idea
is all there. I think it's too early to standardize; we need some more
feedback
based on actual usage.

I hadn't seen StringTemplate until now. It sounds like it has some of the
same
problems in mind. But I took one look at this page:
http://www.antlr.org/wiki/display/ST/StringTemplate+Documentation

And my initial thought is that it's way too complicated.

It's interesting that there's a paper about how it's a functional language:
http://www.cs.usfca.edu/~parrt/papers/ST.pdf

I'll have to read this sometime. JSON Template is also a functional
language as I
wrote in that article... in particular all language constructs can be
evaluated in
any order whatsoever.

[codesite...@google.com]

Updates:
Labels: Todo-Java Todo-PHP

Comment #16 on issue 4 by a...@chubot.org: Provide a standard way for

formatters to take arguments, e.g. for implementing include statement
http://code.google.com/p/json-template/issues/detail?id=4

Done in JS and Python

This is the FunctionRegistry set of APIs