err.no Git - sope/blob - sope-appserver/NGObjWeb/Templates/README-Templates.txt

   1 # $Id$
   2
   3 How Templates Work ...
   4 ======================
   5
   6 In general we have two kinds of templates, XML based ones and "hash" based
   7 ones.
   8 The 'hash' templates are simple scanners for strings which start and end with
   9 "<#" and "</#", while the XML based templates are valid and "namespace'd" XML
  10 files.
  11
  12 Practical difference:
  13 - XML templates can be created, parsed, transformed, ... with any standard XML
  14   tool
  15 - hash templates can be used in a non-tag way, eg this is a valid template:
  16     <a href="<#MyHRef/>">blah</a>
  17   Since unlike the XML parser the hash parser only scans for "<#", this is OK.
  18 - hash templates use "wod" files for declarations which may or may not improve
  19   the visual clutter in the template itself
  20 - XML templates do not need to have a 1:1 mapping from tag to WODynamicElement
  21   and the mapping between tag and element is completely controlled by the
  22   builder while for hash templates you always use the actuall WODynamicElement
  23   subclass name in the .wod file
  24
  25 Class Overview
  26 ==============
  27
  28 WOTemplate (WOElement)
  29 - an WOElement subclass
  30 - this represents the 'real' root element of the template and contains some
  31   additional information like the URL it was loaded from and the subcomponents
  32   declared in the template
  33 - an WOTemplate object will be bound to a WOComponent once instantiated
  34
  35 WOSubcomponentInfo
  36 - used in WOTemplate to track information on the subcomponents declared in
  37   the template (like bindings and component name)
  38 - if a WOComponent is instantiated this will be used to construct the
  39   subcomponents
  40
  41 WODParser
  42 - a parser for the .wod file format
  43 - works someone like a SAX parser and requires a delegate to collect the
  44   actual information out of the parsed objects
  45
  46 WOHTMLParser
  47 - the parser for the "hash" template format
  48 - requires a callback for instantiation of dynamic elements
  49
  50 WOComponentScript / WOComponentScriptPart
  51 - this is used to collect server side template scripts declared in an
  52   XML file or or in a name-associated file (eg Main.js). sample:
  53     <script runat='server'>a = 1 + 2;</script>
  54 - a WOComponentScriptPart is one entry while WOComponentScript is the set of
  55   all entries (which usually will be joined into one script for evaluation)
  56
  57 WOTemplateBuilder
  58 - the common superclass for the XML and hash based builder classes
  59 - also acts as the build "registry"
  60     + (WOTemplateBuilder *)templateBuilderForURL:(NSURL *)_url
  61   this currently returns the WOxTemplateBuilder for .wox extensions and the
  62   hash builder for all other templates
  63 - one API method:
  64     - (WOTemplate *)buildTemplateAtURL:(NSURL *)_url
  65
  66 WOWrapperTemplateBuilder (WOTemplateBuilder)
  67 - subclass of WOTemplateBuilder for "hash" templates
  68 - uses WOHTMLParser and WODParser for processing .wo wrappers
  69 - supports language projects inside wrappers (eg a.wo/English.lproj/a.html)
  70 - looks for JavaScript component scripts (Name.js files)
  71
  72 _WODFileEntry
  73 - used in WOWrapperTemplateBuilder
  74 - somewhat like WOSubcomponentInfo, contains information on a parsed WOD
  75   entry (will be stored in a name=>entry map)
  76
  77 WOxTemplateBuilder (WOTemplateBuilder)
  78 - subclass of WOTemplateBuilder for XML templates (also called 'wox' templates)
  79 - defaults: WOxBuilderClasses
  80 - also scans for "WOxElemBuilder" resources using NGBundleManager
  81 - this one parses a DOM tree from the "build-URL" and then delegates the actual
  82   building to so called "element builders" (subclasses of WOxElemBuilder)
  83
  84 WOxElemBuilder
  85 - superclass for all other element builders
  86 - has a 'nextBuilder' for passing on unsupported tags
  87
  88 WOxElemBuilderComponentInfo
  89 - somewhat like _WODFileEntry,
  90 - used in WOxElemBuilder for tracking subcomponent references
  91 - some API:
  92   - (WOElement *)buildTemplateFromDocument:(id<DOMDocument>)_document;
  93   - (WOElement *)buildNode:(id<DOMNode>)_node templateBuilder:(id)_bld;
  94   - (NSArray *)buildNodes:(id<DOMNodeList>)_node templateBuilder:(id)_bld;
  95 - also manages WOAssociation to namespace mappings, binds a WOAssociation
  96   subclass to a certain namespace, eg:
  97     "var" => "WOKeyValueAssociation"
  98     "<td var:width='calculatedWidth'>"
  99
 100 WOxComponentElemBuilder (WOxElemBuilder)
 101 - build subcomponent references:
 102   - WOChildComponentReference
 103   - WOComponentReference
 104   (but currently no WOSwitchComponent?)
 105 - processes: "<script>", "<component>"
 106 - fallback is: use tagname (not recommended), eg:
 107   <var:Main/>
 108
 109 WOxTagClassElemBuilder (WOxElemBuilder)
 110 - superclass for builders which map an XML tag to a WODynamicElement
 111 - subclasses can return the class required using:
 112     - (Class)classForElement:(id<DOMElement>)_element
 113   everything else will be managed by the tag-builder