SOPE supports various kinds of templates ... this document is about the internals of the NGObjWeb ones

TODO: write much more ...

How Templates Work ...

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

Class Overview

WOTemplate (WOElement)
- an WOElement subclass
- this represents the 'real' root element of the template and contains some
  additional information like the URL it was loaded from and the subcomponents
  declared in the template
- an WOTemplate object will be bound to a WOComponent once instantiated

WOSubcomponentInfo
- used in WOTemplate to track information on the subcomponents declared in
  the template (like bindings and component name)
- if a WOComponent is instantiated this will be used to construct the 
  subcomponents

WODParser
- a parser for the .wod file format
- works someone like a SAX parser and requires a delegate to collect the
  actual information out of the parsed objects

WOHTMLParser
- the parser for the "hash" template format
- requires a callback for instantiation of dynamic elements

WOComponentScript / WOComponentScriptPart
- this is used to collect server side template scripts declared in an
  XML file or or in a name-associated file (eg Main.js). sample:
    <script runat='server'>a = 1 + 2;</script>
- a WOComponentScriptPart is one entry while WOComponentScript is the set of
  all entries (which usually will be joined into one script for evaluation)

WOTemplateBuilder
- the common superclass for the XML and hash based builder classes
- also acts as the build "registry"
    + (WOTemplateBuilder *)templateBuilderForURL:(NSURL *)_url
  this currently returns the WOxTemplateBuilder for .wox extensions and the
  hash builder for all other templates
- one API method:
    - (WOTemplate *)buildTemplateAtURL:(NSURL *)_url

WOWrapperTemplateBuilder (WOTemplateBuilder)
- subclass of WOTemplateBuilder for "hash" templates
- uses WOHTMLParser and WODParser for processing .wo wrappers
- supports language projects inside wrappers (eg a.wo/English.lproj/a.html)
- looks for JavaScript component scripts (Name.js files)

_WODFileEntry
- used in WOWrapperTemplateBuilder
- somewhat like WOSubcomponentInfo, contains information on a parsed WOD
  entry (will be stored in a name=>entry map)

WOxTemplateBuilder (WOTemplateBuilder)
- subclass of WOTemplateBuilder for XML templates (also called 'wox' templates)
- defaults: WOxBuilderClasses
- also scans for "WOxElemBuilder" resources using NGBundleManager
- this one parses a DOM tree from the "build-URL" and then delegates the actual
  building to so called "element builders" (subclasses of WOxElemBuilder)

WOxElemBuilder
- superclass for all other element builders
- has a 'nextBuilder' for passing on unsupported tags

WOxElemBuilderComponentInfo
- somewhat like _WODFileEntry,
- used in WOxElemBuilder for tracking subcomponent references
- some API:
  - (WOElement *)buildTemplateFromDocument:(id<DOMDocument>)_document;
  - (WOElement *)buildNode:(id<DOMNode>)_node templateBuilder:(id)_bld;
  - (NSArray *)buildNodes:(id<DOMNodeList>)_node templateBuilder:(id)_bld;
- also manages WOAssociation to namespace mappings, binds a WOAssociation 
  subclass to a certain namespace, eg:
    "var" => "WOKeyValueAssociation"
    "<td var:width='calculatedWidth'>"

WOxComponentElemBuilder (WOxElemBuilder)
- build subcomponent references:
  - WOChildComponentReference
  - WOComponentReference
  (but currently no WOSwitchComponent?)
- processes: "<script>", "<component>"
- fallback is: use tagname (not recommended), eg:
  <var:Main/>

WOxTagClassElemBuilder (WOxElemBuilder)
- superclass for builders which map an XML tag to a WODynamicElement
- subclasses can return the class required using:
    - (Class)classForElement:(id<DOMElement>)_element
  everything else will be managed by the tag-builder

WOxElemBuilder

Abstract class to build NGObjWeb WOElement templates from XML DOM structures.

Template builders can be stacked in a processing queue, so that unknown elements are produced by the "nextBuilder". When processing is done using a stack, the first stack builder is called the "templateBuilder" and used to keep global state (eg the template builder must be used to create further elements if the same element set is required).

WOxElemBuilder stacks are not thread-safe since the template builder stores subcomponent creation info in an instance variable.

Component Discovery and Page Creation (WOResourceManager)

  Component Discovery and Page Creation

    All WO code uses either directly or indirectly the WOResourceManager's
    -pageWithName:languages: method to instantiate WO components.

    This methods works in three steps:
      
      1. discovery of files associated with the component
      
      2. creation of a proper WOComponentDefinition, which is some kind
         of 'blueprint' or 'class' for components
      
      3. component instantiation using the definition
    
    All the instantiation/setup work is done by a component definition, the
    resource manager is only responsible for managing those 'blueprint'
    resources.

    If you want to customize component creation, you can supply your
    own WOComponentDefinition in a subclass of WOResourceManager by
    overriding:
      - (WOComponentDefinition *)definitionForComponent:(id)_name
        inFramework:(NSString *)_frameworkName
        languages:(NSArray *)_languages