[PEAK] Traversal, views, and templates = PWT, Reloaded

[Phillip J. Eby]

At 02:51 AM 8/22/04 -0400, Phillip J. Eby wrote:
>We've come a long way, so I'll go back to recap the concept of the new 
>template system:
>
>  * There will be two XML namespaces, colloquially referred to as 'this' 
> and 'content'
>
>  * There will be a single property namespace used to look up the 
> implementations of attributes in these two XML namespaces.
>
>  * Attribute implementations will be either "registration" or 
> "replacement" attributes.  At most one "replacement" attribute is 
> permitted per XML element
>
>  * The "replacement" attribute, if any, will be used to create the DOMlet 
> for that element.  If the 'content' namespace is used, then the created 
> DOMlet will actually be nested just inside the element where the 
> attribute appears, and all of the child nodes that would have been added 
> to the element are instead added to the "replacement" DOMlet.
>
>  * The "registration" attributes, if any, will be supplied with the 
> element where they appear, unless they are in the 'content' namespace, in 
> which case they will be supplied an element corresponding to the entire 
> contents of the element where they appear.  (If there was a "replacement" 
> attribute, this "contents" element will be the "replacement" DOMlet, 
> otherwise an extra "tagless element" node will be created.)
>
>  * An 'is' "registration" attribute will replace the current 'pwt:define' 
> attribute, and a 'replace' attribute will replace most uses of the 
> existing 'pwt:domlet' attribute.  Other new "replacement" attributes will 
> be used instead of the values previously specified in 'pwt:domlet' 
> attributes.  E.g. 'content:list="foo"' will do the same thing that 
> 'pwt:domlet="list:foo"' used to do, and 'this:replace="bar"' will take 
> the place of 'pwt:domlet="text.notag:bar"'.

The above items are now available in CVS, albeit with some rough 
edges.  The main "rough edge" is that there isn't any documentation on how 
to create registration-style DOMlets, or how to use existing DOMlets with 
the new syntax.  However, the old pwt:domlet/pwt:define syntax is still 
fully functional.

But I'd like to change that, as it's becoming progressively more difficult 
to maintain the backward compatibility.  So please let me know if you are 
currently using the 'pwt:' syntax, and need to keep using it.  Most people, 
however, will be able to just use these simple translation examples to 
upgrade existing templates:

Before                      After
--------------------        ------------------
pwt:define="xyz"            this:is="xyz"

pwt:domlet="text"           content:text="."
pwt:domlet="text:foo"       content:text="foo"
pwt:domlet="text.notag"     this:replace="."
pwt:domlet="text.notag:x"   this:replace="x"

pwt:domlet="xml"            content:xml="."
pwt:domlet="xml:foo"        content:xml="foo"
pwt:domlet="xml.notag"      this:xml="."
pwt:domlet="xml.notag:foo"  this:xml="foo"

pwt:domlet="list"           content:list="."
pwt:domlet="list:foo"       content:list="foo"

pwt:domlet="url"            content:url="."
pwt:domlet="url:foo"        content:url="foo"
pwt:domlet="url.notag"      this:url="."
pwt:domlet="url.notag:foo"  this:url="foo"

pwt:domlet="url.href"       this:url.href="."
pwt:domlet="url.href:foo"   this:url.href="foo"

pwt:domlet=":foo"          **no translation currently, please let me know 
if you're using!**

Of course, the above only reflects things that were possible with the old 
syntax; the new syntax can express many things that the old syntax 
can't.  (like 'content:is', and 'this:list').

If you are using custom DOMlets, you will need to add them to 
[peak.web.verbs], in this fashion:

     [Import on Demand]
     pwt = "peak.web.templates"

     [peak.web.verbs]
     my_domlet = pwt.negotiatorFactory(somewhere.MyDomletClass)

You will then be able to use it with 'this:my_domlet="data"' or 
'content:my_domlet="data"'.  If you use an existing domlet with the 
'content:' namespace, it must *not* write an open or close tag.  If your 
domlet subclasses the standard domlets, this will be handled automatically 
for you as long as you are writing self._openTag, self._closeTag, and/or 
self._emptyTag.

Also note that it is no longer possible to define "context-specific" 
DOMlets via property namespace; all DOMlets must be defined at the "service 
area" level, or in the template schema (see 'peak.web.template_schema' in 
'peak.ini', and the 'pwt-schema.ini' file in the 'peak.web' package).  If 
you are making use of such DOMlet offerings, please let me know.

Please upgrade from the old syntax as soon as practical, and let me know if 
you are using anything that is currently untranslatable or if you are 
unable to use an existing DOMlet with the new syntax.  Ideally, I'd like to 
start phasing out the old syntax within the next few days.

(I'm also thinking I might like to replace the 'url.attrname' facility with 
a more general attribute-specifying mechanism, perhaps similar to the one 
in ZPT.  But I'm not settled for certain on this yet.)