[TransWarp] PROPOSAL: New peak.web.template terminology/explanation
Phillip J. Eby
pje at telecommunity.com
Mon Jul 21 16:38:27 EDT 2003
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:
<td class="oddrow" show:as="text">Odd row</td>
<td class="evenrow" show:as="text">Even row</td>
<td class="oddrow">Sample data, as much as needed</td>
<td class="evenrow">for a realistic mockup.</td>
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:
Enter your name: <input type="text" show:data="name" show:as="input.text">
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>
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.:
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.
More information about the PEAK