thewoolleyman-webgen 0.5.8.20090419

data/lib/webgen/tag.rb

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+
+module Webgen
+
+  # Namespace for all classes that are useable by Webgen::ContentProcessor::Tag.
+  #
+  # Have a look at the documentation for Webgen::Tag::Base for details on how to implement a tag
+  # class.
+  module Tag
+
+    autoload :Base, 'webgen/tag/base'
+    autoload :Relocatable, 'webgen/tag/relocatable'
+    autoload :Metainfo, 'webgen/tag/metainfo'
+    autoload :Menu, 'webgen/tag/menu'
+    autoload :BreadcrumbTrail, 'webgen/tag/breadcrumbtrail'
+    autoload :Langbar, 'webgen/tag/langbar'
+    autoload :IncludeFile, 'webgen/tag/includefile'
+    autoload :ExecuteCommand, 'webgen/tag/executecommand'
+    autoload :Coderay, 'webgen/tag/coderay'
+    autoload :Date, 'webgen/tag/date'
+    autoload :Sitemap, 'webgen/tag/sitemap'
+    autoload :TikZ, 'webgen/tag/tikz'
+    autoload :Link, 'webgen/tag/link'
+
+  end
+
+end

data/lib/webgen/tag/base.rb

@@ -0,0 +1,170 @@
+# -*- encoding: utf-8 -*-
+
+require 'yaml'
+require 'webgen/loggable'
+require 'webgen/websiteaccess'
+
+# 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
+# <tt>contentprocessor.tags.map</tt> configuration entry for each tag name you want to associate
+# with the tag class. The special name <tt>:default</tt> 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+, +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 <tt>Webgen::</tt> part at the beginning away, substitutes
+# <tt>.</tt> for <tt>::</tt> and makes everything lowercase.
+#
+# An additional configuration entry option is also used: <tt>:mandatory</tt>. 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
+# <tt>tag.</tt> namespace.
+#
+#   class Reverser
+#
+#     include Webgen::Tag::Base
+#
+#     def call(tag, body, context)
+#       result = param('do_reverse') ? body.reverse : body
+#       result += "Node: " + context.content_node.absolute_lcn + " (" + context.content_node['title'] + ")"
+#       result += "Reference node: " + context.ref_node.absolute_lcn
+#       result
+#     end
+#
+#   end
+#
+#   WebsiteAccess.website.config.reverser.do_reverse nil, :mandatory => default
+#   WebsiteAccess.website.config['contentprocessor.tags.map']['reverse'] = 'Reverser'
+#
+module Webgen::Tag::Base
+
+  include Webgen::Loggable
+  include Webgen::WebsiteAccess
+
+  # Return a hash with parameter values extracted from the string +tag_config+.
+  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.absolute_lcn}>: #{e.message}" }
+      config = {}
+    end
+    create_params_hash(config, ref_node)
+  end
+
+  # Set the current parameter configuration to +params+.
+  def set_params(params)
+    @params = params
+  end
+
+  # 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.
+  def param(name)
+    (@params && @params.has_key?(name) ? @params[name] : website.config[name])
+  end
+
+  # 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::ContentProcessor::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!
+  def call(tag, body, context)
+    raise NotImplementedError
+  end
+
+  #######
+  private
+  #######
+
+  # 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.
+  def tag_config_base
+    self.class.name.gsub('::', '.').gsub(/^Webgen\./, '').downcase
+  end
+
+  # Return the list of all parameters for the tag class. All configuration options starting with
+  # +tag_config_base+ are used.
+  def tag_params_list
+    regexp = /^#{tag_config_base}/
+    website.config.data.keys.select {|key| key =~ regexp}
+  end
+
+  # Create the parameter hash from +config+ which needs to be a Hash, a String or +nil+.
+  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.absolute_lcn}>" }
+               {}
+             end
+
+    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.absolute_lcn}> set" }
+    end
+
+    result
+  end
+
+  # Return a valid parameter hash taking values from +config+ which has to be a Hash.
+  def create_from_hash(config, params, node)
+    result = {}
+    config.each do |key, value|
+      if params.include?(key)
+        result[key] = value
+      elsif params.include?(tag_config_base + '.' + key)
+        result[tag_config_base + '.' + key] = value
+      else
+        log(:warn) { "Invalid parameter '#{key}' for tag '#{self.class.name}' in <#{node.absolute_lcn}>" }
+      end
+    end
+    result
+  end
+
+  # Return a valid parameter hash by setting +value+ to the default mandatory parameter.
+  def create_from_string(value, params, node)
+    param_name = params.find {|k| website.config.meta_info[k][:mandatory] == 'default'}
+    if param_name.nil?
+      log(:error) { "No default mandatory parameter specified for tag '#{self.class.name}' but set in <#{node.absolute_lcn}>"}
+      {}
+    else
+      {param_name => value}
+    end
+  end
+
+end

data/lib/webgen/tag/breadcrumbtrail.rb

@@ -0,0 +1,70 @@
+# -*- encoding: utf-8 -*-
+
+module Webgen::Tag
+
+  # Generates a breadcrumb trail for the page. This is especially useful when pages are in deep
+  # hierarchies of directories.
+  class BreadcrumbTrail
+
+    include Webgen::WebsiteAccess
+    include Base
+
+    def initialize #:nodoc:
+      website.blackboard.add_listener(:node_changed?, method(:node_changed?))
+    end
+
+    # Create the breadcrumb trail.
+    def call(tag, body, context)
+      out = breadcrumb_trail_list(context.content_node)
+      (context.dest_node.node_info[:tag_breadcrumb_trail] ||= {})[[@params.to_a.sort, context.content_node.absolute_lcn]] = out.map {|n| n.absolute_lcn}
+      out = out.map {|n| context.dest_node.link_to(n, :lang => context.content_node.lang) }.
+        join(param('tag.breadcrumbtrail.separator'))
+      log(:debug) { "Breadcrumb trail for <#{context.content_node.absolute_lcn}>: #{out}" }
+      out
+    end
+
+    #######
+    private
+    #######
+
+    # Return the list of nodes that make up the breadcrumb trail of +node+ according to the current
+    # parameters.
+    def breadcrumb_trail_list(node)
+      list = []
+      omit_index_path = if node.meta_info.has_key?('omit_index_path')
+                          node['omit_index_path']
+                        else
+                          param('tag.breadcrumbtrail.omit_index_path')
+                        end
+      omit_index_path = omit_index_path && node.parent.routing_node(node.lang) == node
+
+      node = node.parent if omit_index_path
+
+      until node == node.tree.dummy_root
+        list.unshift(node)
+        node = node.parent
+      end
+      list[param('tag.breadcrumbtrail.start_level')..param('tag.breadcrumbtrail.end_level')].to_a
+    end
+
+    # Check if the breadcrumb trails for +node+ have changed.
+    def node_changed?(node)
+      return if !node.node_info[:tag_breadcrumb_trail]
+
+      node.node_info[:tag_breadcrumb_trail].each do |(params, cn_alcn), cached_list|
+        cn = node.tree[cn_alcn]
+        set_params(params.to_hash)
+        list = breadcrumb_trail_list(cn)
+        set_params({})
+
+        if (list.map {|n| n.absolute_lcn} != cached_list) ||
+            list.any? {|n| (r = n.routing_node(cn.lang)) && r != node && r.meta_info_changed?}
+          node.flag(:dirty)
+          break
+        end
+      end
+    end
+
+  end
+
+end

data/lib/webgen/tag/coderay.rb

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+
+module Webgen::Tag
+
+  # Provides syntax highlighting via the +coderay+ library.
+  class Coderay
+
+    include Webgen::Tag::Base
+    include Webgen::WebsiteAccess
+
+    # Highlight the body of the block.
+    def call(tag, body, context)
+      require 'coderay'
+      options = {
+        :css => :style,
+        :wrap => param('tag.coderay.wrap').to_sym,
+        :line_numbers => (param('tag.coderay.line_numbers') ? :inline : nil),
+        :line_number_start => param('tag.coderay.line_number_start'),
+        :tab_width => param('tag.coderay.tab_width'),
+        :bold_every => param('tag.coderay.bold_every')
+      }
+
+      if param('tag.coderay.process_body')
+        body = website.blackboard.invoke(:content_processor, 'tags').call(context.clone(:content => body)).content
+      end
+      CodeRay.scan(body, param('tag.coderay.lang').to_sym).html(options)
+    end
+
+  end
+
+end

data/lib/webgen/tag/date.rb

@@ -0,0 +1,18 @@
+# -*- encoding: utf-8 -*-
+
+module Webgen::Tag
+
+  # Prints out the date using a format string which will be passed to Time#strftime. Therefore you
+  # can use everything Time#strftime offers.
+  class Date
+
+    include Base
+
+    # Return the current date formatted as specified.
+    def call(tag, body, context)
+      Time.now.strftime(param('tag.date.format'))
+    end
+
+  end
+
+end

data/lib/webgen/tag/executecommand.rb

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+
+require 'cgi'
+require 'tempfile'
+require 'rbconfig'
+
+module Webgen::Tag
+
+  # Executes the given command and returns the standard output. All special HTML characters are
+  # escaped.
+  class ExecuteCommand
+
+    include Webgen::Tag::Base
+
+    BIT_BUCKET = (Config::CONFIG['arch'].include?('mswin32') ?  "nul" : "/dev/null")
+
+    # Execute the command and return the standard output.
+    def call(tag, body, context)
+      command = param('tag.executecommand.command')
+      output = `#{command} 2> #{BIT_BUCKET}`
+      if ($? >> 8) != 0
+        raise "Command '#{command}' in <#{context.ref_node.absolute_lcn}> has return value != 0: #{output}"
+      end
+      output = CGI::escapeHTML(output) if param('tag.executecommand.escape_html')
+      [output, param('tag.executecommand.process_output')]
+    end
+
+  end
+
+end

data/lib/webgen/tag/includefile.rb

@@ -0,0 +1,42 @@
+# -*- encoding: utf-8 -*-
+
+require 'cgi'
+
+module Webgen::Tag
+
+  # Includes a file verbatim and optionally escapes all special HTML characters and processes webgen
+  # tags in it.
+  class IncludeFile
+
+    include Webgen::Tag::Base
+    include Webgen::WebsiteAccess
+
+    def initialize #:nodoc:
+      website.blackboard.add_listener(:node_changed?, method(:node_changed?))
+    end
+
+    # Include the specified file verbatim in the output, optionally escaping special HTML characters
+    # and processing tags in it.
+    def call(tag, body, context)
+      filename = param('tag.includefile.filename')
+      filename = File.join(website.directory, filename) unless filename =~ /^(\/|\w:)/
+      content = File.open(filename, 'rb') {|f| f.read}
+      content = CGI::escapeHTML(content) if param('tag.includefile.escape_html')
+      (context.dest_node.node_info[:tag_includefile_filenames] ||= []) << [filename, File.mtime(filename)]
+
+      [content, param('tag.includefile.process_output')]
+    end
+
+    #######
+    private
+    #######
+
+    def node_changed?(node)
+      if filenames = node.node_info[:tag_includefile_filenames]
+        node.flag(:dirty) if filenames.any? {|f, mtime| File.mtime(f) > mtime}
+      end
+    end
+
+  end
+
+end

data/lib/webgen/tag/langbar.rb

@@ -0,0 +1,52 @@
+# -*- encoding: utf-8 -*-
+
+module Webgen::Tag
+
+  # Generates a list with all the languages of the page.
+  class Langbar
+
+    include Webgen::Tag::Base
+    include Webgen::WebsiteAccess
+
+    def initialize #:nodoc:
+      website.blackboard.add_listener(:node_changed?, method(:node_changed?))
+    end
+
+    # Return a list of all translations of the content page.
+    def call(tag, body, context)
+      lang_nodes = all_lang_nodes(context.content_node)
+      (context.dest_node.node_info[:tag_langbar_data] ||= {})[context.content_node.absolute_cn] = lang_nodes.map {|n| n.absolute_lcn}
+      result = lang_nodes.
+        reject {|n| (context.content_node.lang == n.lang && !param('tag.langbar.show_own_lang'))}.
+        sort {|a, b| a.lang <=> b.lang}.
+        collect {|n| context.dest_node.link_to(n, :link_text => (param('tag.langbar.lang_names')[n.lang] || n.lang), :lang => n.lang)}.
+        join(param('tag.langbar.separator'))
+
+      [(param('tag.langbar.show_single_lang') || lang_nodes.length > 1 ? result : ""), param('tag.langbar.process_output')]
+    end
+
+    #######
+    private
+    #######
+
+    # Return all nodes with the same absolute cn as +node+.
+    def all_lang_nodes(node)
+      node.tree.node_access[:acn][node.absolute_cn]
+    end
+
+    # Check if the langbar tag for +node+ changed.
+    def node_changed?(node)
+      return unless (cdata = node.node_info[:tag_langbar_data])
+      cdata.each do |acn, clang_nodes|
+        lang_nodes = all_lang_nodes(node.tree[acn, :acn]) rescue nil
+        if !lang_nodes || lang_nodes.length != clang_nodes.length ||
+            lang_nodes.any? {|n| n.meta_info_changed?}
+          node.flag(:dirty)
+          break
+        end
+      end
+    end
+
+  end
+
+end