Back to the extension listing.

Webgen::ContentProcessor::Blocks

Summary

As short name for the content processor (used, for example, in the pipeline option of a block in a file in Webgen Page Format) one of the following can be used: 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.

The general syntax is as follows:

<webgen:block name='BLOCK_NAME' chain='(L)CN;(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 but first comes a small explanation of how this tag works.

webgen uses a node chain when rendering a page file. The default node chain is automatically determined via the template meta information (see SourceHandler::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 CN of a page file has the extension html)

default.template ---> index.html

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, after rendering it according to its render pipeline, of the index.page. If such a block tag was not in the template, then the content of the index.page file would never be inserted into the output file! 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.

Following is the documentation for the available attributes of the tag:

  • The name attribute is the only mandatory attribute and it specifies the name of the block that should be rendered in place of the block tag. If the used node (see the node attribute) has no such named block, an error is raised.

  • The optional attribute chain specifies the node chain that should be used for rendering the block. Its value needs to be a list of (localized) canonical names of nodes separated by semicolons that should be used as node chain. If this attribute is not specified the default node chain is used.

  • The optional attribute node 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 till 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!

  • If the optional attribute notfound 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 not be defined in all page files.

All this is more easily explained with examples. Assume that we have a default.template file, a page.template file and a my.page file with the following contents:

The default.template file:

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

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

And the my.page file:

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

default.template ---> my.html

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:

page.template ---> my.html

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.

Summing up the above, the rendered file 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

Back to the extension listing.