rb:include
Insert a file into the current Pattern Page BodyThe 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.
|
