[Web-SIG] Standardized template API

[Phillip J. Eby]

At 02:03 AM 2/1/2006 -0500, Michael Bayer wrote:
>do either of these specs address the concept of componentized
>templates ?  that is, when you are referencing a template, compiling
>its output, and delivering its textual output, in reality that
>template would consist of possibly dozens of smaller sub-templates,
>to form different parts of the page, and also to form various nesting
>schemes.  In myghty, the resolver stack, i.e. the thing that takes
>some kind of string, runs it through some rules (which can be a
>straight down list or a whole structure of conditionals and groups),
>and produces a template object (actually called a component), is not
>used only for handling the initial URL from an HTTP request.  It is
>used entirely within the request for every sub-component, nested- 
>template, subrequest, template inheritance scheme, what-have-you, so
>that a single request actually calls a lot of templates which call
>each other, all using the same resolver stack to find things.  Extra
>contextual information can also be passed to the resolver to give it
>more things with which to make decisions; such as the "context",
>which can say "im the top-level request calling you", "im a sub- component 
>calling you", "im your super-(inherited) parent calling
>you", etc.   Information about the resolved component is available as
>well, such as getting back the re.Match object that resulted from a
>regexp call, or other parameters that indicate things about the
>resolver rule that actually matched.   All of that stuff is important.

My assumption is that framework-specific functionality of this nature would 
be made available via standard WSGI "server extension APIs", which is to 
say objects or callbacks inside of the 'environ' dict.  So, you might have 
a 'myghty.resolver' key in environ to provide access to that API.


>A cross-template resolution/execution API introduces the concept of
>one kind of template including snips from other kinds of templates,
>or someone using a template-inheritance-enabled system to enable that
>capability for a system that doesnt have that feature, etc.   So it
>would be nice if this system could support that use case, and not
>just be request-oriented.
>
>When I first wrote WSGI support for Myghty and saw what Ian was doing
>with Paste, I thought, wow, why dont I take my component model and
>make them all into little WSGI application() objects...but in
>reality, for those sub-templates, the typical HTTP request/response
>as well as the start_response doesnt really seem appropriate,
>especially for the kinds of interactions those components have with
>each other, such as intricate wrapping schemes, iterative patterns.

Note that different templating engines have different notions of what a 
sub-template would consist of; some think of them as functions, others as 
DOM trees, and still others as strings or objects implementing some kind of 
rendering interface.  Some need subtemplates that are effectively bound as 
methods of some object being rendered, so there's a need for a "self" 
parameter to the subtemplate.

Thus, it seems to me that all this stuff needs to remain on the template 
side of the API to start with, as it isn't currently generalizable to some 
sort of generic API.  (Which is why my proposal doesn't currently include a 
standard way to find other templates.)



>Also i dont believe any templating system should ever be hardcoded to
>an "HTTP request" concept....too many places have we had JSP or PHP
>sites that hit a brick wall when we want to use the same templates to
>pre-generate files, or emails, etc. because those systems have no
>notion of non-HTTP usage.

Sorry, you lost me there.  I see no reason why you can't use a WSGI 
response to write to a file or send an email.


>Forgive my rambling, I havent gotten to dig deeply into Ian's spec
>and I'm still trying to get an idea of what the more encompassing
>spec is about  (like what is template polymorphism exactly ?)

Specifying only a template's *name* in code, not its type.  In peak.web, if 
I refer to a resource or template named "foo", the system looks in the 
resource directory and determines the template type based on 
extensions.  So if there's a foo.pwt or foo.html or foo.gif or foo.jpeg, it 
determines the resource type from that.  When you combine this feature with 
skinning, it means that deployers are free to change the technology used to 
deliver a particular template or resource.  For example, replacing a .gif 
or .jpeg with a .png or vice versa, or using a different template engine 
for a template.

I don't know if any other frameworks support it; IIRC TurboGears currently 
embeds the template engine name inside the code that refers to the template.

Anyway, resource polymorphism is a deep assumption in peak.web, and it 
obviously affects how it does subtemplate lookups -- another reason why I 
think we should start with a spec that doesn't get into subtemplating to 
start with.

There's nothing stopping the a WSGI-based templating proposal from 
providing some kind of subtemplate support, though; it's just an extension 
API after all.  What I'm opposed to is giving official status to 
half-solutions to the subtemplating problem that only work with a few 
string-oriented templates and frameworks.

However, I'm thinking maybe we could take a step in the direction of making 
it easier for templating systems to play without needing full WSGI 
support.  We could require a WSGI templating environ to include a 
'wti.return_string' key, defined such that you could do something like this:

      def template(environ, start_response):
          return environ['wti.return_string'](
              start_response, 'text/plain', "rendered text"
          )

This would make it trivial to wrap string-based template engines in WTI 
(the WSGI Template Interface).  Heck, it might not be a bad idea to have a 
key like that in WSGI 1.1!

But I digress.  What I think we should do as we figure out other models to 
return for things besides strings, we can add other 'wti.return_foo' keys 
to allow templates to return non-string things that can nonetheless be 
reduced to strings if middleware is in play and needs them.