Home DocumentationReferenceAPIWebgen ↴

class Webgen::Tag

Namespace for all webgen tags.

About ↑

A tag object is a webgen extension that handles specific webgen tags. webgen tags are used to add dynamic content to page and template files (or any other file for that matter) and are made for ease of use.

Implementing a tag ↑

A tag object only needs to respond to the method call which needs to accept three parameters:

tag

The name of the tag which should be processed (useful for tag objects which can process different tags).

body

Holds the body value for the tag if any.

context

Holds all relevant information for processing – have a look at the Webgen::Context class to see what is available. The special key :config is set to an Webgen::Configuration object that should be used to retrieve configuration option values because the values might be changed due to options set directly via the tag syntax.

The method has to return the result of the processing and, optionally, a boolean value specifying if the result should further be processed (ie. webgen tags replaced).

This allows one to implement a tag object as a class with a class method called call. Or as a Proc object.

The tag object has to be registered so that webgen knows about it, see register for more information.

Tag options ↑

webgen tags allow the specification of options in the tag definition. When registering a tag, one can specify which options are mandatory, i.e. which options always have to be set directly for the tag. The value of the option :config_prefix for the register method is used to resolve partially stated configuration entries.

Sample Tag ↑

Following is a simple tag class example which just reverses the body text and adds some information about the context to the result.

Put the following into the ext/init.rb file of your webgen website:

class Reverser

  def self.call(tag, body, context)
    result = context[:config]['tag.reverser.do_reverse'] ? body.reverse : body
    result << "\nNode: " << context.content_node.alcn << " (" << context.content_node['title'] << ")"
    result << "\nReference node: " << context.ref_node.alcn
    result
  end

end

website.config.define_option('tag.reverser.do_reverse', nil)
website.ext.tag.register(Reverser, :names => 'reverse',
                         :config_prefix => 'tag.reverser',
                         :mandatory => ['do_reverse'])

Then you can use the reverser tag as follows in a page file:

{reverse:: {do_reverse: true}}This text is reversed{reverse}

Public Class Methods

render_tag_template(context, tag)

Render the tag template for the given tag and return the result.

The value of the configuration option 'tag.<TAG>.template' (where '<TAG>' is replaced with tag) is used as template path.

If the template node cannot be found, an empty string is returned.

Public Instance Methods

call(tag, params, body, context)

Process the tag and return the result.

The parameter params (can be a Hash, a String or nil) needs to contain the parameters for the tag and body is the optional body for the tag. context needs to be a valid Webgen::Context object.

register(klass, options = {}, &block)

Register a tag.

The parameter klass can either be a String containing the name of a class/module (which has to respond to :call) or an object that responds to :call. If the class is located under this namespace, only the class name without the hierarchy part is needed, otherwise the full class/module name including parent module/class names is needed.

Instead of registering an object that responds to :call, you can also provide a block that processes a tag.

Options: ↑

:names

The tag name or an array of tag names. If not set, it defaults to the lowercase version of the class name (without the hierarchy part).

The name :default is used for specifying the default tag which is called if an unknown tag name is encountered.

:config_prefix

The configuration prefix, i.e. the part of a configuration option name that does not need to be specified. Defaults to the full class name without the Webgen module downcased and all “::” substituted with “.” (e.g. Webgen::Tag::Menu → tag.menu). Needs to be specified when a block is used!

:mandatory

A list of configuration option names whose values always need to be provided. The first configuration option name is used as the default mandatory option (used when only a string is provided in the tag definition).

Examples: ↑

tag.register('Date')    # registers Webgen::Tag::Date

tag.register('::Date')  # registers Date !!!

tag.register('MyModule::Date', names: ['mydate', 'date'])

tag.register('date', config_prefix: 'tag.date') do |tag, body, context|
  Time.now.strftime(param('tag.date.format'))
end
replace_tags(str) { |tag_name, params, body| ... }

See Webgen::Utils::TagParser#replace_tags.