This module should be included in every source handler as it provides the default methods for creating nodes.

Implementing Source Handlers

A source handler is a webgen extension that processes source paths to create nodes and that provides the rendered content of these nodes. The nodes are later written to the output location. This can range from simply copying a path from the source to the output location to generating a whole set of nodes from one input path!

The paths that are handled by a source handler are specified via path patterns (see below). During a webgen run the # method for each source paths that matches a specified path pattern is called. And when it is time to write out the node, the # method is called to retrieve the rendered content.

A source handler must not take any parameters on initialization and when this module is not mixed in, the methods # and # need to be defined. Also, a source handler does not need to reside under the Webgen::SourceHandler namespace but all shipped ones do.

This base class provides useful default implementations of methods that are used by nearly all source handler classes:

• #

• #

• #

It also provides other utility methods:

• #

• #

• #

Nodes Created for Paths

The main functions of a source handler class are to create one or more nodes for a source path and to provide the content of these nodes. To achieve this, certain information needs to be set on a created node. If you use the create_node method provided by this base class, you don’t need to set them explicitly because this is done by the method:

node_info[:processor]

Has to be set to the class name of the source handler. This is used by the Node class: all unknown method calls are forwarded to the node processor.

node_info[:src]

Has to be set to the string version of the path that lead to the creation of the node.

node_info[:creation_path]

Has to be set to the string version of the path that is used to create the path.

meta_info['no_output']

Has to be set to true on nodes that are used during a webgen run but do not produce an output file.

meta_info['modified_at']

Has to be set to the current time if not already set correctly (ie. if not a Time object).

If meta_info['draft'] is set on a path, then no node should be created in create_node and nil has to be returned.

Note: The difference between :src and :creation_path is that a creation path need not have an existing source path representation. For example, fragments created from a page source path have a different :creation_path which includes the fragment part.

Additional information that is used only for processing purposes should be stored in the # hash of a node as the # hash is reserved for real node meta information and should not be changed once the node is created.

Output Path Names

The method for creating an output path name for a source path is stored in the meta information output_path. If you don’t use the provided method output_path, have a look at its implementation to see how to an output path gets created. Individual output path creation methods are stored as methods in the OutputPathHelpers module.

Path Patterns and Invocation order

Path patterns define which paths are handled by a specific source handler. These patterns are specified in the sourcehandler.patterns configuration hash as a mapping from the source handler class name to an array of path patterns. The patterns need to have a format that Dir.glob can handle. You can use the configuration helper patterns to set this (is shown in the example below).

Specifying a path pattern does not mean that webgen uses the source handler. One also needs to provide an entry in the configuration value sourcehandler.invoke. This is a hash that maps the invocation rank (a number) to an array of source handler class names. The lower the invocation rank the earlier the specified source handlers are used.

The default invocation ranks are:

1

Early. Normally there is no need to use this rank.

5

Standard. This is the rank the normal source handler should use.

9

Late. This rank should be used by source handlers that operate on/use already created nodes and need to ensure that these nodes are available.

Default Meta Information

Each source handler can define default meta information that gets automatically set on the source paths that are passed to the # method.

The default meta information is specified in the sourcehandler.default_meta_info configuration hash as a mapping from the source handler class name to the meta information hash.

Sample Source Handler Class

Following is a simple source handler class example which copies paths from the source to the output location modifying the extension:

  class SimpleCopy

    include Webgen::SourceHandler::Base
    include Webgen::WebsiteAccess

    def create_node(path)
      path.ext += '.copied'
      super(path)
    end

    def content(node)
      website.blackboard.invoke(:source_paths)[node.node_info[:src]].io
    end

  end

  WebsiteAccess.website.config.patterns('SimpleCopy' => ['**/*.jpg', '**/*.png'])
  WebsiteAccess.website.config.sourcehandler.invoke[5] << 'SimpleCopy'

     # File lib/webgen/sourcehandler/base.rb, line 252
252:     def content(node)
253:       nil
254:     end

     # File lib/webgen/sourcehandler/base.rb, line 220
220:     def create_node(path, options = {})
221:       return nil if path.meta_info['draft']
222:       parent = options[:parent] || parent_node(path)
223:       output_path = options[:output_path] || self.output_path(parent, path)
224:       node = node_exists?(path, output_path)
225: 
226:       if node && (node.node_info[:src] != path.source_path || node.node_info[:processor] != self.class.name)
227:         log(:warn) { "Node already exists: source = #{path.source_path} | path = #{node.path} | alcn = #{node.alcn}"}
228:         return node #TODO: think! should nil be returned?
229:       elsif !node
230:         node = Webgen::Node.new(parent, output_path, path.cn, path.meta_info)
231:       elsif node.flagged?(:reinit)
232:         node.reinit(output_path, path.meta_info)
233:       else
234:         return node
235:       end
236: 
237:       if !node['modified_at'].kind_of?(Time)
238:         log(:warn) { "Meta information 'modified_at' set to current time in <#{node}> since its value '#{node['modified_at']}' was of type #{node['modified_at'].class}" } unless node['modified_at'].nil?
239:         node['modified_at'] = Time.now
240:       end
241:       node.node_info[:src] = path.source_path
242:       node.node_info[:creation_path] = path.path
243:       node.node_info[:processor] = self.class.name
244:       yield(node) if block_given?
245:       node
246:     end

     # File lib/webgen/sourcehandler/base.rb, line 199
199:     def node_exists?(path, output_path = self.output_path(parent_node(path), path))
200:       Webgen::WebsiteAccess.website.tree[path.alcn] || (!path.meta_info['no_output'] && Webgen::WebsiteAccess.website.tree[output_path, :path])
201:     end

     # File lib/webgen/sourcehandler/base.rb, line 175
175:     def output_path(parent, path)
176:       method = path.meta_info['output_path'] + '_output_path'
177:       use_lang_part = if path.meta_info['lang'].nil? # unlocalized files never get a lang in the filename!
178:                         false
179:                       else
180:                         Webgen::WebsiteAccess.website.config['sourcehandler.default_lang_in_output_path'] ||
181:                           Webgen::WebsiteAccess.website.config['website.lang'] != path.meta_info['lang']
182:                       end
183:       if OutputPathHelpers.public_instance_methods(false).map {|c| c.to_s}.include?(method)
184:         name = send(method, parent, path, use_lang_part)
185:         name += '/'  if path.path =~ /\/$/ && name !~ /\/$/
186:         if (node = node_exists?(path, name)) && node.lang != path.meta_info['lang']
187:           name = send(method, parent, path, (path.meta_info['lang'].nil? ? false : true))
188:           name += '/'  if path.path =~ /\/$/ && name !~ /\/$/
189:         end
190:         name
191:       else
192:         raise Webgen::NodeCreationError.new("Unknown method for creating output path: #{path.meta_info['output_path']}",
193:                                             self.class.name, path)
194:       end
195:     end

     # File lib/webgen/sourcehandler/base.rb, line 258
258:     def page_from_path(path)
259:       begin
260:         page = Webgen::Page.from_data(path.io.data, path.meta_info)
261:       rescue Webgen::Page::FormatError => e
262:         raise Webgen::NodeCreationError.new("Error reading source path: #{e.message}",
263:                                             self.class.name, path)
264:       end
265:       path.meta_info = page.meta_info
266:       page
267:     end

     # File lib/webgen/sourcehandler/base.rb, line 270
270:     def parent_node(path)
271:       parent_dir = (path.parent_path == '' ? '' : Webgen::Path.new(path.parent_path).alcn)
272:       if !(parent = Webgen::WebsiteAccess.website.tree[parent_dir])
273:         raise Webgen::NodeCreationError.new("The needed parent path <#{parent_dir}> does not exist",
274:                                             self.class.name, path)
275:       end
276:       parent
277:     end