Webgen::Tag::Base

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'

Public Instance Methods

call(tag, body, context) click to toggle source

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!

     # File lib/webgen/tag/base.rb, line 121
121:   def call(tag, body, context)
122:     raise NotImplementedError
123:   end

create_params_hash(config, node) click to toggle source

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

    # File lib/webgen/tag/base.rb, line 80
80:   def create_params_hash(config, node)
81:     params = tag_params_list
82:     result = case config
83:              when Hash then create_from_hash(config, params, node)
84:              when String then create_from_string(config, params, node)
85:              when NilClass then {}
86:              else
87:                raise Webgen::RenderError.new("Invalid parameter type (#{config.class})",
88:                                              self.class.name, nil, node)
89:              end
90: 
91:     unless params.all? {|k| !website.config.meta_info[k][:mandatory] || result.has_key?(k)}
92:       raise Webgen::RenderError.new("Not all mandatory parameters set", self.class.name, nil, node)
93:     end
94: 
95:     result
96:   end

create_tag_params(tag_config, ref_node) click to toggle source

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

    # File lib/webgen/tag/base.rb, line 69
69:   def create_tag_params(tag_config, ref_node)
70:     begin
71:       config = YAML::load("--- #{tag_config}")
72:     rescue ArgumentError => e
73:       raise Webgen::RenderError.new("Could not parse the tag params '#{tag_config}': #{e.message}",
74:                                     self.class.name, nil, ref_node)
75:     end
76:     create_params_hash(config, ref_node)
77:   end

param(name) click to toggle source

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.

     # File lib/webgen/tag/base.rb, line 105
105:   def param(name)
106:     (defined?(@params) && @params.has_key?(name) ? @params[name] : website.config[name])
107:   end

set_params(params) click to toggle source

Set the current parameter configuration to params.

     # File lib/webgen/tag/base.rb, line 99
 99:   def set_params(params)
100:     @params = params
101:   end

Private Instance Methods

create_from_hash(config, params, node) click to toggle source

Return a valid parameter hash taking values from config which has to be a Hash.

     # File lib/webgen/tag/base.rb, line 145
145:   def create_from_hash(config, params, node)
146:     result = {}
147:     config.each do |key, value|
148:       if params.include?(key)
149:         result[key] = value
150:       elsif params.include?(tag_config_base + '.' + key)
151:         result[tag_config_base + '.' + key] = value
152:       else
153:         log(:warn) { "Invalid parameter '#{key}' for tag '#{self.class.name}' in <#{node}>" }
154:       end
155:     end
156:     result
157:   end

create_from_string(value, params, node) click to toggle source

Return a valid parameter hash by setting value to the default mandatory parameter.

     # File lib/webgen/tag/base.rb, line 160
160:   def create_from_string(value, params, node)
161:     param_name = params.find {|k| website.config.meta_info[k][:mandatory] == 'default'}
162:     if param_name.nil?
163:       log(:error) { "No default mandatory parameter specified for tag '#{self.class.name}' but set in <#{node}>"}
164:       {}
165:     else
166:       {param_name => value}
167:     end
168:   end

tag_config_base() click to toggle source

The base part of the configuration name. This isthe class name without the Webgen module downcased and all “::” substituted with “.” (e.g. Webgen::Tag::Menu -> tag.menu). By overriding this method one can provide a different way of specifying the base part of the configuration name.

     # File lib/webgen/tag/base.rb, line 133
133:   def tag_config_base
134:     self.class.name.gsub('::', '.').gsub(/^Webgen\./, '').downcase
135:   end

tag_params_list() click to toggle source

Return the list of all parameters for the tag class. All configuration options starting with tag_config_base are used.

     # File lib/webgen/tag/base.rb, line 139
139:   def tag_params_list
140:     regexp = /^#{tag_config_base}/
141:     website.config.data.keys.select {|key| key =~ regexp}
142:   end

Home Classes Methods

In Files

Methods

Included Modules

Class Index