[TransWarp] PROPOSAL: New peak.web.template terminology/explanation

[Phillip J. Eby]

What follows is a write-up on the current consensus that Ty and I reached 
after discussing the PWT terminology, and after reviewing the IRC channel 
discussion on the subject.  If you find it unclear or awkward, or have any 
other objections (or questions!), please let me know.

=======

DOMlet - A component (or class for such a component) that generates XML, 
HTML, or text.  Currently, these are covered by various ITemplate* 
interfaces; these will be renamed to IDOMlet*.

PWT attribute syntax example:

<table
   xmlns:show="http://peak.telecommunity.com/peak.web.templates/"
   show:data="tabulardata"
   show:as="list"
 >
<tr show:format="listItem">
    <td class="oddrow" show:as="text">Odd row</td>
</tr>
<tr show:format="listItem">
    <td class="evenrow" show:as="text">Even row</td>
</tr>
<tr>
    <td class="oddrow">Sample data, as much as needed</td>
</tr>
<tr>
    <td class="evenrow">for a realistic mockup.</td>
</tr>
</table>

Explanation: peak.web templates convert an XML (or XHTML) template into 
components called DOMlets.  By default, every element or text node of the 
document is converted into a simple static DOMlet that outputs the original 
content as-is.  However, by identifying a DOMlet class with the 'show:as' 
attribute, you can cause the marked element to be converted to a DOMlet 
that generates dynamic content.

DOMlets need to know what data they're displaying, so the 'show:data' 
attribute can be used to identify the data that will be supplied to all the 
DOMlets inside the element where the 'show:data' attribute appears, 
including that element itself.  The name or path supplied in 'show:data' is 
*relative* to any enclosing 'show:data' settings, so in the following:

<form show:data="myRecord">
Enter your name: <input type="text" show:data="name" show:as="input.text">
</form>

The inner 'input.text' DOMlet will be applied to "myRecord/name".  This 
example also demonstrates that show:data and show:as do not have to appear 
on the same document elements.

The last PWT attribute is 'show:format', which is used to supply formatting 
parameters to some kinds of DOMlets.  The DOMlet representing the element 
where the 'show:format' attribute appears, is supplied to its enclosing 
DOMlet as a parameter.  A simple example:

<ul show:data="myList" show:as="list">
<li show:format="listItem" show:data="title" show:as="text">Title here</li>
</ul>

In this case, the DOMlet representing the 'ul' element will be given the 
'li' DOMlet as its "listItem" parameter.  In the case of the "list" DOMlet, 
this means that the supplied DOMlet will be used to output each item in the 
supplied list.  Notice here that an element marked with 'show:format' can 
be any DOMlet, whether dynamic or static.

Multiple contained elements may be marked with show:format, with the same 
or different names; all are supplied to the nearest surrounding dynamic 
DOMlet's 'addFormat()' method as the template is parsed.  Thus, the outer 
DOMlet can invoke the "format parameter" DOMlets as needed.

DOMlets are standard peak.binding.Components, with their immediate 
containing DOMlet used as their parent component.  Generally speaking, the 
top-level DOMlet of a template will have a skin or application root 
component as its parent.  Since they are Components, they can obtain 
utilities or properties from their parent(s) just as any other components 
can, and those bindings will last as long as the template exists.

DOMlets are created by DOMlet classes or DOMlet factories.  The class or 
factory object must implement IDOMletElementFactory, an interface for 
constructing a DOMlet from XML element data.  DOMlet instances must 
implement IDOMletElement.  (For text, comment, and processing instruction 
nodes, there are separate IDOMletNode and IDOMletNodeFactory interfaces.)

To find a DOMlet class or factory, the value of the 'show:as' attribute is 
looked up as a property in the [peak.web.DOMlets] property namespace (to be 
renamed from peak.web.views).  So 'show:as="list"' will look up the value 
of 'peak.web.DOMlets.list', and adapt the result to 
IDOMletElementFactory.  The property lookup starts with the immediately 
enclosing DOMlet, and proceeds up through the other parent DOMlets, out of 
the template and on up to the application root.  Note that this means that 
DOMlets can supply "nested" DOMlet classes/factories that are only 
available within the context of that DOMlet, or that override the 
definition of an existing DOMlet name within the context of the DOMlet, e.g.:

<table show:as="foo">
<tr show:as="bar"></tr>
</table>

If the "foo" DOMlet has a binding with offerAs=['peak.web.DOMlets.bar'], 
that binding will be used to create the nested DOMlet, in place of whatever 
DOMlet factory might be defined for "bar" outside of the "foo" DOMlet.

Of course, DOMlets can supply other properties or utilities to contained 
DOMlets, so that they can intelligently "wire" themselves together in 
larger structures.  It's expected, too, that an application will likely 
have custom DOMlets, usually as a simple subclass of an existing DOMlet to 
add some customization or set some parameters.  For example, if someone 
creates a "smart table" widget that does sorting when you click on item 
headers, it's likely that you'll need to subclass it to parameterize 
various settings, or bind them to data supplied by your application's 
configuration.  Or maybe you'll create a context DOMlet that doesn't do 
anything but supply configuration data to the off-the-shelf DOMlets.

Currently, the only DOMlets that exist are "list" and "text" - trivial 
examples that do nothing to showcase the true potential for creating 
dynamic XML/HTML widgets.  As we develop peak.web applications, however, we 
expect the available DOMlets to continually increase in availability and power.