Definition of Whitebeam XML Tags

Site Map
 
Home
 
Application Guide
Reference
  Installation
  Configuration
  XML Markup
    authenticate
    block
    cachecontrol
    eval
    false
    header
    include
    insertblock
    insertdebug
    macrotag
    marksession
    nomacro
    noscript
    parser
    redirect
    repeatfor
    return
    script
    if
    test
    true
    xmp
    eval
    id
    marksession
    test
  JavaScript Classes
  ROM
  Templates
  Environment
  Dev Process
  Tools
  External Links
  Example libraries
Community
Contact Whitebeam
To-Do
Download
Credits
Licence
Whitebeam Users
 
 
 

Definition of Whitebeam XML Tags

rb:include

Insert a file into the current Pattern Page

Body

The body of this tag is always empty.

Attributes

Attribute Required Description

src

required

The name of the resource to include, e.g. 'shop.rhtm' may be a library of XML code that works with a shopping template.

once

optional

'yes' or 'no'. Default : no. If this attribute is present and has a value of 'yes' then the file to be include will only be include if it has not already been included previously within this page execution.

type

implied

Tells the Presentation Engine the type of the file being included - and therefore how that file should be incorporated into the page being constructed. The possible values for this attribute are:

.

xml

default. The referenced file contains server-side parsable XML. The Presentation Engine should read the file and execute the XML - inserting the contents as a sub-tree within the current document in place of the <rb:include...> tag.

text

The referenced file contains 'text' that should be sent directly to the client without being executed by the Presentation Engine. The contents of the file are sent to the client in line with the rest of the page in the place currently occupied by the <rb:include...> tag

binary

The referenced file contains binary data - such as a GIF. The Presentation Engine will load the file into memory - discard the output already generated by the Presentation Engine and send the contents directly to the client.

system

implied

Tells the Presentation Engine that the referenced file is part of the core Whitebeam functionality and should be found in the reserved - global Whitebeam file space rather than the file space of the virtual server. This facility is used by Whitebeam to provide access to system wide libraries of code.

Currently this facility is not available to Partners.

id

implied

By default 'rb:include' includes the entire contents of the referenced resource. If an 'id' is specified the presentation engine looks for a tag with an 'rb:id' attribute with a value that matches that specified in the 'id' attribute.

If no tag matches the requested ID then no content is added into the presentation page being built.

This attribute only has meaning if the file contains XML and the Presentation Engine has been told to parse that tree (the type attribute must either be missing or have a value of xml)

test

implied

This is an optional attribute that if present contains a JavaScript expression. If this expression evaluates to 'false' then no file will be loaded by this tag.

Note that this attribute is only available from Whitebeam 0.9.28 onwards.

limit

implied

This is used in conjunction with the 'id' attribute (if there is no 'id' attribute then this attribute, if present, is ignored. The attribute takes one of two values addThis, the default if not present, and addChildren. The default value causes the identified tag to be inserted in the the parent document. If the value of this attribute is addChildren then only the children of the named node are included in the document.

This attribute only has meaning if the file contains XML and the Presentation Engine has been told to parse that tree (the type attribute must either be missing or have a value of xml)

rb:loaderror

implied

By default the Presentation Engine expects the referenced file to exist and that the request to load the named file will work. If the Presentation Engine cannot locate the specified file it will by default generate a page error. This parameter allows this behaviour to be modified. If the attribute is present and has the value 'ignore' then the Presentation Engine will silently ignore the fact that a file does not exist.

This attribute does *not* change the behaviour if the file contains XML and the XML is invalid! If the file is present then the contents must be valid for the specified type of file.

Remarks

This attribute inserts the contents of some other local URL into the current Pattern Page as-if the content of the referenced file had been part of the page being processed. If the referenced file includes JavaScript then that script is interpreted as part of the file.

The 'id' and 'limit' attributes can be used to include subsections of another document. One use of this is to write a complete HTML document, using a standard editor, and then only include children of the <body...> tag. Example.

Include File:

<body rb:id="nav3">
   ...
</body>
<body rb:id="nav4">
   ...
</body>
<body rb:id="ie4">
   ...
</body>

Parent File:

<rb:test expr="browser==nav3">
   <rb:true>
      <rb:include "incfile.inc" id="nav3"/>
   </rb:true>
   ...
</rb:test>

The 'type' attribute tells the Presentation Engine how to incorporate the contents of the file into the page being constructed. The default behaviours is as in the example above. The file is assumed to contain valid XML and the Presentation Engine loads the contents and constructs a valid XML sub-tree fro the contents - reporting errors if the XML is invalid.

The alternatives values for the type attribute are 'text' and 'binary'. If a file is identified as containing 'text' then the Presentation Engine does not attempt to interpret the contents. Instead the entire contents of the file are inserted directly in place of the <rb:include...> tag in the page being constructed.

The Presentation Engine treats binary files as non-interpretable data - such as a GIF - which is not intended to appear in-line with XML output. These files are sent directly to the client browser - discarding any accumulated XML page content along with any subsequent content that could be generated.

An include tag is only ever executed ONCE. The first time it is executed it creates one or more child tags to contain the contents of the refernced file. If an attempt is made to re-exeucte that tag (for example from JavaScript or a rb:repeatfor then only the first reads the file. Subsequent executions runs the contents read the first time.
Whitebeam release 1.3.36
(loadtime : 20ms)