Module: Webgen::Tag::Base

Includes:
Loggable, WebsiteAccess
Included in:
BreadcrumbTrail, Coderay, Date, ExecuteCommand, IncludeFile, Langbar, Link, Menu, Metainfo, Relocatable, Sitemap, TikZ
Defined in:
lib/webgen/tag/base.rb

Overview

This module should be mixed into any class that wants to serve as a webgen tag class. Have a look a the example below to see how a basic tag class looks like.

Tag classes

A tag class is a webgen extension that handles specific webgen tags. webgen tags are used to add dynamic content to page and template files and are made for ease of use.

A tag class can handle multiple different tags. Just add a (tag name)-(class name) pair to the contentprocessor.tags.map configuration entry for each tag name you want to associate with the tag class. The special name :default is used for the default tag class which is called if a tag with an unknown tag name is encountered.

The only method needed to be written is call which is called by the tags content processor to the actual processing. And the initialize method must not take any parameters!

Tag classes can also choose to not use this module. If they don't use it they have to provide the following methods: set_params, create_tag_params, create_params_hash, call.

Tag parameters

webgen tags allow the specification of parameters in the tag definition. The method tag_params_list returns all configuration entries that can be set this way. And the method tag_config_base is used to resolve partially stated configuration entries. The default method uses the full class name, strips a Webgen:: part at the beginning away, substitutes . for :: and makes everything lowercase.

An additional configuration entry option is also used: :mandatory. If this key is set to true for a configuration entry, the entry counts as mandatory and needs to be set in the tag definition. If this key is set to default, this means that this entry should be the default mandatory parameter (used when only a string is provided in the tag definition). There should be only one default mandatory parameter.

Sample Tag Class

Following is a simple tag class example which just reverses the body text and adds some information about the context to the result. Note that the class does not reside in the Webgen::Tag namespace and that the configuration entry is therefore also not under the tag. namespace.

class Reverser

  include Webgen::Tag::Base

  def call(tag, body, context)
    result = param('do_reverse') ? body.reverse : body
    result += "Node: " + context.content_node.alcn + " (" + context.content_node['title'] + ")"
    result += "Reference node: " + context.ref_node.alcn
    result
  end

end

WebsiteAccess.website.config.reverser.do_reverse nil, :mandatory => 'default'
WebsiteAccess.website.config['contentprocessor.tags.map']['reverse'] = 'Reverser'

Instance Method Summary (collapse)

Methods included from WebsiteAccess

included, #website

Methods included from Loggable

#log, #puts

Instance Method Details

- (Object) call(tag, body, context)

Default implementation for processing a tag. The parameter tag specifies the name of the tag which should be processed (useful for tag classes which process different tags).

The parameter body holds the optional body value for the tag.

The context parameter holds all relevant information for processing. Have a look at the Webgen::Context class to see what is available.

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

Needs to be redefined by classes that mixin this module!

Raises:

  • (NotImplementedError) 


121
122
123
 
# File 'lib/webgen/tag/base.rb', line 121

def call(tag, body, context)
  raise NotImplementedError
end

- (Object) create_params_hash(config, node)

Create and return the parameter hash from config which needs to be a Hash, a String or nil.



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/webgen/tag/base.rb', line 80

def create_params_hash(config, node)
  params = tag_params_list
  result = case config
           when Hash then create_from_hash(config, params, node)
           when String then create_from_string(config, params, node)
           when NilClass then {}
           else
             raise Webgen::RenderError.new("Invalid parameter type (#{config.class})",
                                           self.class.name, nil, node)
           end

  unless params.all? {|k| !website.config.meta_info[k][:mandatory] || result.has_key?(k)}
    raise Webgen::RenderError.new("Not all mandatory parameters set", self.class.name, nil, node)
  end

  result
end

- (Object) create_tag_params(tag_config, ref_node)

Create a hash with parameter values extracted from the string tag_config and return it.



69
70
71
72
73
74
75
76
77
 
# File 'lib/webgen/tag/base.rb', line 69

def create_tag_params(tag_config, ref_node)
  begin
    config = YAML::load("--- #{tag_config}")
  rescue ArgumentError => e
    raise Webgen::RenderError.new("Could not parse the tag params '#{tag_config}': #{e.message}",
                                  self.class.name, nil, ref_node)
  end
  create_params_hash(config, ref_node)
end

- (Object) param(name)

Retrieve the parameter value for name. The value is taken from the current parameter configuration if the parameter is specified there or from the website configuration otherwise.



105
106
107
 
# File 'lib/webgen/tag/base.rb', line 105

def param(name)
  (defined?(@params) && @params.has_key?(name) ? @params[name] : website.config[name])
end

- (Object) set_params(params)

Set the current parameter configuration to params.



99
100
101
 
# File 'lib/webgen/tag/base.rb', line 99

def set_params(params)
  @params = params
end