[TransWarp] More PWT Ideas (usage, not terminology!)

[Phillip J. Eby]

At 12:00 PM 7/26/03 +0200, Roché Compaan wrote:

>In the endElement handler the element created by factory is added as a
>child of the last element in the stack - its parent node. 'addChild' is
>a method of the Element class - the base for all DOMlets.

Actually, it isn't the base for all DOMlets, either in theory (since 
anything that implements the IDOMletNode and/or IDOMletElement interface is 
a DOMlet), or in practice (since the Literal class exists and is a DOMlet 
class).

Note that the factory chosen to create text, comments, processing 
instructions and the like comes from the enclosing DOMlet.  So I could 
write something like this:

<something domlet="interpolate">
Foo = ${foo}
</something>

And the "interpolate" DOMlet could define its 'textFactory' attribute as an 
IDOMletNode class that did interpolation of text nodes.  Of course, it 
might be simpler to build the interpolation into the enclosing DOMlet, but 
that's not the point.  I just want to illustrate that you can control the 
class used for rendering text.  An IDOMletNode need not provide only static 
text, and if its 'staticText' attribute is None, then its renderFor() 
method is called, just like element DOMlets.


>TemplateDocument inherits 'renderFor' from Element. It iterates over
>optimizedChildren and calls the 'renderFor' method for each child
>element. In the simple template above 'document' has only child, a text
>domlet.

Technically, the hierarchy looks like this:

      document
     /
     <something> DOMlet
    /
    literal DOMlet for "whatever"

The "whatever" literal DOMlet is thrown away during construction, though, 
because the <something> DOMlet is a ContentReplacer that doesn't intend to 
use it.  But I want to emphasize that it gets created, 
anyway.  Understanding these aspects of the build process may be useful for 
creating advanced DOMlets.

Every block of text, every XML start/end element pair, every comment is 
turned into the creation of a DOMlet node or element, based on the 
factories supplied by the enclosing element or document.  Every piece 
becomes a DOMlet, even if some get thrown away as part of optimization 
(which concatenates adjacent blocks of static text).


>The 'renderFor' method of text replaces the content of the
>element.

In a sense, yes.  In another sense, all it does is write text, which is all 
that DOMlets ever do.  It's up to the DOMlet to write whatever it 
wants.  Technically, it's not even a requirement that they write valid or 
even well-formed XML.  In principle, you could use DOMlets to generate 
plain text or SQL or something, as long as you made sure all the "element" 
DOMlets used didn't write any XML.


>It then uses the write function from the state instance to
>write the opening tag, the content for the tag and finally the closing
>tag.

Yep.  DOMlets use state.write() for all their output, whether they're 
elements or text nodes.  The optimization process I mentioned earlier 
flattens any adjacent static text nodes into a single text node, so as to 
minimize the number of write() calls required.