[PEAK] Resources and traversal in peak.web

[Phillip J. Eby]

At 03:06 PM 8/21/04 -0400, Phillip J. Eby wrote:
>We might want to use a different extension for such resource files, and 
>use a template subclass that either refuses to render to HTTP, or places 
>itself within a standard layout template.  Hm, that's three kinds of 
>templates, then:
>
>   * Standalone page template: renders the same whether it's accessed 
> directly via HTTP, or embedded in another template.
>
>   * "Widget" template: only renders when embedded in another template, 
> refuses to render via HTTP, registering a '403 Forbidden' error if you try.
>
>   * "Fragment" template: renders as-is when embedded in another template, 
> but if accessed directly via HTTP, it wraps itself in a "standard layout" 
> template.
>
>The last of these is kind of a convenient special case for objects that 
>can be displayed within another page, or by themselves.
>
>I'm not sure how these should be designated, although we could just use 
>extensions like '.page', '.widget', and '.fragment'.  Or maybe they would 
>be '.page.pwt', '.widget.pwt', and so on.  (The resource subsystem can 
>handle multi-part extensions like this, and longer extensions take 
>precedence over shorter ones.)

I'm beginning to think that the best way to handle this is not going to be 
by a naming convention, but by content in the template itself:

    * this:page_layout="layoutname" -- use the specified layout if the 
template is accessed directly as a web page (as opposed to embedded in 
another page).  That is, this is used for a "fragment" template.

    * this:page_layout="None" -- this is a "standalone" template that 
renders the same whether it's embedded or not

    * No page_layout specified -- this is a widget template, so render a 
"403 Forbidden" if you try to use it directly (a safe default mode)

This would be "registration" attribute that notifies the top-level 
"document" object what layout to embed the template in, if it's accessed as 
a web page, rather than as an embedded fragement.  It might also be useful 
to have another "registration" attribute to control the template's MIME 
type, as long as there are no conflicting declarations within the 
document.  E.g. 'this:mime-type="text/xml"'.

In addition, it seems it would be useful to allow type constraints as well, 
so that one can designate an interface that a template (or portion thereof) 
expects, e.g. 'content:expects="some_module.IFoo"'.  An error handler could 
trap the adaptation.  This would have to be a "replacement" attribute 
rather than a "registration" one, although it would also be useful to have 
a 'this:template_for="some.module.IFoo"' to register the top-level template 
type, to avoid the issue of e.g., accidentally invoking a template on its 
containing folder.

Anyway, this approach doesn't require any new extensions, but it does 
require you to at least skim the template if you want to see what's going on.