SOPE currently allows for two different template formats, the traditional WebObjects one (with the # addition) as well as a new XML based one. This document tries to outline some pros and cons for each.

work in progress ..., just collecting ideas for now ;-)
TODO: need some intro to both formats
TODO: need some examples for each pro and contra

Important: Note that WOx does not try to replace WO wrapper templates! Both formats are complementary and can be mixed. What template format is better really depends on the actual use case and both have strength and weaknesses.

Advantages of .wo "Wrapper Templates"

  • pretty clean separation between HTML content and bindings which attach tags to the code
  • good at handling a lot of bindings attached to a single dynamic element
  • supports property lists as constants
  • tool support by WOBuilder
  • good at handling non XML/HTML content, since this is just a pattern replacement
  • allows "invalid" XML in the source, like: <a href="<#MyURL/>">

    • Advantages of .wox "XML Templates"

  • very good and compact templates, especially if things are "mostly" HTML or "mostly" abstract (no HTML, only dynelems)
  • "transparent" generic elements/containers. No need to declare in a .wod, just use <td var:bgcolor="activeColor">!
  • can use different WOAssociations, allows to add own associations, eg <var:string xpath:value="Envelope/LoginRequest/login"/> could extract a value using an XPath expression.
  • different XML element builders can be used to support "foreign" XML template formats, like XSLT, Zope Page Templates or Tapestry templates! All those can be expressed without big efforts in WOx
  • can use any SAX driver! Not just XML. This includes the HTML driver, but also things like the iCal or STX SAX driver which can be used for generation of non HTML/XML formats.
    Another option are SAX drivers which emit XML for different template formats, like PHP or ASP. Not too difficult!
  • any XML editor can be used to create the templates. You can write XML-schema files to enable features like tag and attribute completion
  • any XML tool can be used to generate, process, validate or search WOx templates (eg xmlgrep to find all templates which use some keypath as a element binding)
  • can generate resource URLs for any attribute (eg rsrc:background)
  • due to resource associations some WODynamicElements are not necessary anymore, ie WOJavaScript is <script rsrc:src="myfile.js">

    • Disadvantages of .wo "Wrapper Templates"

    A lot of the issues come from the fact that the templates are wrappers, that is, separate files.

  • No good tool support. WO tags are unknown to most HTML designer tools which is why ZPT or Tapestry attach to HTML instead of using own tags
  • CVS - dealing with directories with contained files is annoying and quite slow.
  • you need tool support to edit the templates (eg WOBuilder), otherwise you need to constantly switch between buffers.
  • for components with few tags (whether HTML or dynamic elements) the .wod is an unnecessary addition, always annoyed me
  • there is no way to actually make use of the nice WOAssociation abstraction because you are fixed to WOKeyPathAssociation and WOConstantAssociation
  • hard to validate, because parsing a WO wrapper requires a linked application

    • Disadvantages of .wox "XML Templates"

  • need to declare all the XML preamble stuff
  • its slower to parse
  • if you want to generate plain text or XML (or other formats), its a bit difficult to read because the XML is parsed as XML (eg the preamble and namespaces), but something different is generated (XSLT suffers from the same issue)
  • with a lot of bindings on a single tag, XML becomes hard to read (IMHO), though proper indentation can help a bit (also see the FAQ on this)

    • Some text from the sources .. (to be cleaned up)

    In general we have two kinds of templates, XML based ones and "hash" based ones.
The 'hash' templates are simple scanners for strings which start and end with "<#" and "</#", while the XML based templates are valid and "namespace'd" XML files.
Practical difference:
- XML templates can be created, parsed, transformed, ... with any standard XML tool
- hash templates can be used in a non-tag way, eg this is a valid template:
<a href="<#MyHRef/>">blah</a>
Since unlike the XML parser the hash parser only scans for "<#", this is OK.
- hash templates use "wod" files for declarations which may or may not improve
the visual clutter in the template itself
- XML templates do not need to have a 1:1 mapping from tag to WODynamicElement
and the mapping between tag and element is completely controlled by the
builder while for hash templates you always use the actuall WODynamicElement
subclass name in the .wod file

    Associations

    TODO: write more

  • WOValueAssociation (aka const:)
  • WOKeyValueAssociation (aka var:)
  • WOResourceURLAssociation (aka rsrc:)
  • WOScriptAssocation (aka js:)

    • Some other associations which might make sense:

  • WOLabelAssociation - for transforming label keys to strings
  • WOXPathAssociation - for evaluation of XPath's

    • You can also use it too shorten all kind of pathes, eg to access session variables, you could use something like: 

    <var:string sn:value="loginUser"/>

    Though this particular case is probably not worth the effort. On the other side this syntax increases the semantic value of the XML file and could be used to validate (using XML tools) whether the contained value is an available session key.

    Good matches with namespaces ...

    Something which is a bit "surprising" is that namespace "clutter" is pretty low for associations and elements. The worst case would be, if you would need to specify a namespace prefix for each attribute. But as mentioned, this is seldom necessary: 

    <var:foreach list="addresses" item="address">
<var:string value="lastName"/>

    ... matches very well for purely dynamic tags, and it matches HTML tags quite well, and highlights pretty well which parts are dynamic: 

    <td align="left" width="80%" var:bgcolor="backColor">
<img rsrc:src="filename.gif"/>

    One example where it doesn't match well is: 

    <var:condition="showIt" const:negate="YES">

    FAQ

    Q: Do you transform the WOx templates into .wod and .html strings of the wrapper format and pipe that into +templateWithHTMLString:declarationString:languages: calls?
    A: No. For SOPE we made the whole template creation mechanism pluggable so we don't need to resort to use available public API.
    So both, the .wo wrapper builder and the .wox builder are regular template formats supported by SOPE. Take a look in NGObjWeb/Templates if you are interested.

    Q: How fast are WOx templates?
    A: Parsing WOx templates is slower than parsing WO templates. First the DOM tree will be built driven by SAX events, then the DOM tree will be converted into the dynamic element tree.
    We don't consider that an issue, since in a deployed app component templates are cached and during the development 10ms more do not matter. See next question if you want to do a lot of parsing ;-)
    At runtime evaluation WOx templates are exactly as fast as WO templates - the result of parsing is in any case a regular WOElement tree.

    Q: Parsing templates is too expensive, because I compose them dynamically in my application!
    A: Yes, in this case WOx may be too slow. Actually SOPE also contains NGObjDOM which is basically the "reverse" approach to WOx.
    Instead of building a WOElement tree out of a DOM, it allows to use a DOM tree directly as a dynamic element.
    This approach is used in OGo Publisher, because each page is treated as a separate component but only used once (so the template creation would be superflous).
    Update: NGObjDOM now lives in the Recycler.

    Q: If I have a dynamic element or component with a lot of bindings, the WOx becomes hard to write in XML.
    A: If you have a lot of bindings on a single element, a WO wrapper templates might indeed be better.
    On the other side WOxElemBuilder are free to use DOM structure to represent bindings! That is, instead of putting all bindings of the element into XML attributes, you can use child tags which are converted into WOAssociations instead of WOElements.
    But of course this requires custom coding (which may be worth the effort for such complex elements!)