Back to the extension listing.

Webgen::ContentProcessor::Tags

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

Each webgen tag is defined using a unique name and handled by a tag class. 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 special configuration options for the tag itself are used, a shorter form can be used for them: just remove the tag class name part (without the Webgen:: prefix) from the configuration option. For example, the relocatable tag handled by Webgen::Tag::Relocatable specifies 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 parameters (and if they are mandatory) 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 spe

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

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

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.

     {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 to this is to specify a general prefix for all webgen tags using the configuration option contentprocessor.tags.prefix. 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}}.

Back to the extension listing.