XML Processing using the Whitebeam Environment

Implementing XML Macros (rb:macrotag)

The tag processing can be used extensively in implementing your own specialised tags - or in providing translations from one XML format to another. In this case the macro itself is defined using the rb:macrotag tag. This declares a new tag, the name being defined by the 'name' attribute of that tag. If the 'name' attribute of the macrotag is the same as an existing, default tag (such as 'body'), the Presentation Engine will execute the behaviour defined by the macro instead of the default behaviour.

The Presentation Engine implementation of the rb:macrotag tag creates an internal representation of the named tag and then stores the JavaScript implementation against that tag. When the engine subsequently finds an instance of the new tag in the document it calls the JavaScript implementation for that tag. The implementation can use the JavaScript XML modelling rb.xml.thisTag method to access the XML body of the tag. As with the rb:block example, the engine does NOT automatically execute the body of the macro - to do so would reduce the scope of the JavaScript implementation. So to get the body text of the tree your must first execute the tree using tag.execute().

This does of course give the JavaScript implementation of the tag the freedom to only execute a portion of the body tags. Consider an example implementation of a tag called '<switch...>' that we want to provide. This will take a number of child tags - <case...>. We'd use this as follows:

<switch expr="resultcode">
   <case test="ok">
      <rb:redirect src="nextpage.rhtm">
   </case>
   <case test="noresource">
      <rb:redirect src="resourcepage.rhtm">
   </case>
   <case test="notfound">
      <h1>Error - you specified a resource that does not exist.</h1>
   </case>
</switch>

This is similar to the JavaScript 'switch' statement - but executed in tags. This illustrates why the Presentation Engine does not automatically execute trees under macro implementations or block tags. The implementation of <switch...> will search through the list of provided cases and only execute the one that matches the result code. This means that only one of the redirection tags will be executed.

A more complete example of how to use tag.execute and the rb:macrotag tags can be found in the Whitebeam examples.