|Summary||Replaces a special xml tag with the rendered block of a node in Webgen Page Format|
|Provided by bundle||built-in|
This processor replaces a special XML tag with rendered blocks. It is used, for example, in templates to define the place where the actual page content should be.
The general syntax is as follows:
<webgen:block name='BLOCK_NAME' chain='(A)(L)CN;(A)(L)CN;...' node='next|first|current' notfound='ignore' />
So it is basically an XML tag with the mandatory attribute
name and the optional attributes
notfound – the attributes are explained below.
webgen uses a node chain when rendering a page node. The default node chain is automatically determined via the template meta information (also see path handler template) and the important thing to keep in mind is that the first node in the node chain is always the currently rendered template/page.
For example, consider a
default.template with a block tag of
<webgen:block name='content' /> and
index.page that should be rendered. This would result in a node chain of (note that the
extension of the CN of a page node is changed to the extension
html by default)
During the rendering of the
index.page, the node chain like shown above is created and rendering
is started at the first node in the chain, in this case at
default.template. When the block tag
is encountered, it is replaced by the block named
content of the
index.page, after rendering it
according to its render pipeline. If such a block tag was not in the template, then the content of
index.page node would never be inserted into the destination path! The behaviour of the block
tag can be customized by using the various attributes.
Summing up: The template meta information is used to create a node chain which is then used by the block tag to render the appropriate blocks.
XML Element Attributes
- This attribute is the only mandatory attribute and it specifies the name of the block that
should be rendered. If the used node (see the
nodeattribute) has no such named block, an error is raised.
- This optional attribute specifies the node chain that should be used for rendering the block. Its value needs to be a list of (absolute) (localized) canonical names of nodes separated by semicolons that should be used for the node chain. If this attribute is not specified, the default node chain is used (i.e. the one determined via the template meta information).
- This optional attribute specifies which node in the node chain should be used.
If this attribute is not specified or its value is “next”, the next node in the node chain (i.e. the second node) is used. If there is only one node left in the node chain that node is used.
If the attribute has a value of “first”, then the node chain is traversed until a node is found that has a block with the specified name. If no such node is in the node chain, an error is raised. If the attribute
chainis also used, then the search starts at the first node of the node chain. Otherwise it starts at the second node.
If the attribute has a value of “current”, the currently processed node is used (i.e. the first node in the node chain).
Note that the attribute
chainis not used in this situation!
- If this optional attribute has a value of “ignore”, all errors that can occur are ignored. This is especially useful when used in templates to include blocks that may or may not be defined in all page nodes.
All this is more easily explained with examples. Assume that we have a
default.template path, a
page.template path and a
my.page path with the following contents:
--- name:content pipeline:blocks before default <webgen:block name='content' /> after default 1 <webgen:block name='content' chain='page.template;my.html' /> after default 2 <webgen:block name='optional' chain='page.template;my.html' node='first' /> after default 3 <webgen:block name='invalid' notfound='ignore' /> after default 4
--- name:content pipeline:blocks before page 1 <webgen:block name='content' /> after page 1
--- name:content pipeline: The content of the page file. --- name:optional pipeline: Optional content.
my.page gets rendered to
my.html, the node chain looks like this by default:
The first webgen block tag just inserts the rendered block named “content” of
my.page. The second
block tag uses a custom node chain. Therefore the block named “content” of
rendered using the node chain:
and then inserted. The third block tag uses the same custom node chain but for a block named
“optional”. This block does not exist in
page.template but it does exist in
my.page. Since the
node attribute is set to “first”, the first node
page.template in the node chain is ignored and
the block is found in
my.page (if the
node attribute is not specified, an error will be raised).
The fourth block tag specifies a block name that does not occur in
my.page. However, since the
notfound is set to “ignore”, this error is ignored.
So the rendered node
my.html will then look like this:
before default 1 The content of the page file. after default 1 before page 1 The content of the page file. after page 1 after default 2 Optional content. after default 3 after default 4