content_processor.tags

Description

This processor provides an easy method for adding dynamic content to web pages. It uses so called “webgen tags” to replace special markup constructs with dynamic content. This system allows webgen to generate menus and breadcrumb trails, include files and much more.

webgen already comes with many tags that handle simple things, like including a file, to advanced things, like generating a menu. See the tag extension for a list of available tags.

Usage

Each webgen tag is defined using a unique name and handled by a tag extension. A tag can have zero or more parameters some of which are mandatory. Tag parameters map directly to configuration options, so you can temporarily (for the rendering of the tag) override some configuration options.

Since normally only the configuration options for the tag itself are used, a shorter form exists for using them: Just remove the “tag.TAG_NAME.” part from the configuration option name and use the rest. For example, the relocatable tag uses the configuration option tag.relocatable.path and the short name for it (when used as parameter for the relocatable tag, not when used for other tags) is therefore just path.

The supported configuration options and additional information (for example, whether they are mandatory or optional) are listed for each tag on its documentation page. The default mandatory parameter can be specified in a special way, see the following section.

When content is parsed and a webgen tag is encountered, the registered extension for this tag is called. If no extension for a tag exists, there are two possibilities: If a default tag extension exists, then this default extension is called. Otherwise an error is raised.

For information on how to create such a tag extension have a look at the API documentation of the Webgen::Tag class.

Syntax for webgen Tags

webgen tags are defined using a special markup construct which consists of the tag name, a parameter part and a body part.

A tag can be specified in one of the following ways:

• The simplest form of a webgen tag just consists of the tag name itself. This form can only be used if the tag does not have any mandatory parameters.

   {tagname:}
  

• If a plugin has only one mandatory parameter, there is a short-cut syntax for specifying its value (can only be used if the value is not expected to be a hash, the value is parsed as YAML markup):

   {tagname: value}
  

• If a plugin has more than one mandatory parameter or if some default parameter values should be overwritten, one needs to use the following general form:

   {tagname: {option: value, other_option: other_value}}
  

  The parameters defined using this syntax are actually specified using a hash in YAML markup. So you can use any valid YAML construct in the YAML hash definition.

• Additionally, you can use a body part with any of the above forms. To specify that the tag has a body part, just use two colons instead of one after the tag name and don’t forget the closing tag.

   {tagname::}Here comes the body{tagname}
  

  Although you can always specify a body part, only some tags actually use it - the documentation for each tag states if the body part is used or not.

Sometimes you need to specify something which looks like a webgen tag but should not be processed like one. In such cases, you need to escape the tag with a backslash, like this:

\{tagname: {key:value}}

Another solution for this problem is to specify a general prefix for all webgen tags using the  tag.prefix configuration option. Let’s imagine that you set the prefix to webgen:; then this content processor will only process webgen tags of the form {webgen:tagname: {key: value}}.