[Web-SIG] My original template API proposal

[Ian Bicking]

Kevin Dangoor wrote:
> On 2/5/06, Ian Bicking <ianb at colorstudy.com> wrote:
> 
>>      def render(template_instance, vars, wsgi_environ=None,
>>                 set_header_callback=None, **kwargs):
> 
> 
> I'm not keen on the wsgi_environ and set_header_callback options,
> because I don't perceive a true need for *this* API to be tied to the
> web. Of course, you need these if the template itself is going to set
> any of the headers, but there is some added complexity that results.
> TurboGears skirts this by having the Python code outside of the
> template decide what content-type (and other headers) are appropriate.
> 
> Since these are optional, I'm not strongly against them, but they just
> feel like they add a bit of complexity to an API that is dealing with
> a simple problem.

The benefit I see, particularly with wsgi_environ, is that we can define 
exactly what it is -- it is a WSGI environment, with a supporting spec 
to define exactly what that is.  We could also put it in a specific key 
in vars, but that doesn't feel as clean to me.  Anyway, that doesn't 
change that it's very optional, and a template plugin is completely free 
to ignore it, and a framework is free not to pass it in.  But in the 
case where both template and framework are interested in that sort of 
thing, the spec documents how that information is passed around because 
we've given it an argument name.

set_header_callback is very kludgy-feeling, though, and I'm not very 
comfortable with it.  OTOH, I like at least that you know if anyone is 
listening (where a value of None means no one is) -- having all 
templates generate headers, and then substantial portion of frameworks 
throw those headers away, seems like a bad solution as well.  And 
there's lots of contexts when a template simply shouldn't be allowed to 
set headers, because that's not meaningful in the context it is being 
used (even if it is in a web request, and wsgi_environ still applies). 
Though content-type has some real utility even in embedded contexts -- 
smart templates could fix up encodings of included content, or even do 
markup transformations -- like XHTML to HTML (or vice versa).

-- 
Ian Bicking  /  ianb at colorstudy.com  /  http://blog.ianbicking.org