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

#call(tag, body, context) ⇒ Object

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) 


129
130
131
 
# File 'lib/webgen/tag/base.rb', line 129

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

#create_params_hash(config, node) ⇒ Object

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

Returns the parameter hash and a boolean which is true if any mandatory parameters are missing.



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/webgen/tag/base.rb', line 86

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
             log(:error) { "Invalid parameter type (#{config.class}) for tag '#{self.class.name}' in <#{node.alcn}>" }
             {}
           end

  mandatory_params_missing = false
  unless params.all? {|k| !website.config.meta_info[k][:mandatory] || result.has_key?(k)}
    log(:error) { "Not all mandatory parameters for tag '#{self.class.name}' in <#{node.alcn}> set" }
    mandatory_params_missing = true
  end

  [result, mandatory_params_missing]
end

#create_tag_params(tag_config, ref_node) ⇒ Object

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

Returns the parameter hash and a boolean which is true if any mandatory parameters are missing.



72
73
74
75
76
77
78
79
80
 
# File 'lib/webgen/tag/base.rb', line 72

def create_tag_params(tag_config, ref_node)
  begin
    config = YAML::load("--- #{tag_config}")
  rescue ArgumentError => e
    log(:error) { "Could not parse the tag params '#{tag_config}' in <#{ref_node.alcn}>: #{e.message}" }
    config = {}
  end
  create_params_hash(config, ref_node)
end

#param(name) ⇒ Object

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.



113
114
115
 
# File 'lib/webgen/tag/base.rb', line 113

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

#set_params(params) ⇒ Object

Set the current parameter configuration to params.



107
108
109
 
# File 'lib/webgen/tag/base.rb', line 107

def set_params(params)
  @params = params
end