content_processor.blocks

Summary	Replaces a special xml tag with the rendered block of a node in Webgen Page Format
Short name	blocks
Content type	text
Provided by bundle	built-in
API doc	Webgen::ContentProcessor::Blocks

Description

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.

Syntax

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 chain, node and 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 an 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 the 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

name

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 node attribute) has no such named block, an error is raised.

chain

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).

node

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 chain is 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 chain is not used in this situation!

notfound

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.

Example

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:

The default.template path:

--- 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

The page.template path:

--- name:content pipeline:blocks
before page 1
<webgen:block name='content' />
after page 1

And the my.page path:

--- name:content pipeline:
The content of the page file.
--- name:optional pipeline:
Optional content.

When 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 page.template gets 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 optional attribute 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