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

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](../sourcehandler/template.html)) 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!
    {:.important}

* 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