webgen 0.4.7 → 0.5.0

data/lib/webgen/tag/base.rb

@@ -0,0 +1,162 @@
+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. 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 is normally the class name without the Webgen
+  # module downcased and all "::" substituted with "." (e.g. Webgen::Tag::Menu -> tag.menu).
+  def tag_config_base
+    self.class.name.gsub('::', '.').gsub(/^Webgen\./, '').downcase
+  end
+
+  # Return the list of all parameters for the tag class.
+  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/menu.rb

@@ -0,0 +1,187 @@
+require 'webgen/websiteaccess'
+require 'webgen/tag'
+
+module Webgen::Tag
+
+  # Generates a menu that can be configured extensively.
+  class Menu
+
+    include Webgen::WebsiteAccess
+    include Base
+
+    # Special menu node class. It encapsulates the original node for later access.
+    class MenuNode
+
+      # Array of the child nodes.
+      attr_reader :children
+
+      # The parent node.
+      attr_reader :parent
+
+      # The encapsulated node.
+      attr_reader :node
+
+      # Create a new menu node under +parent+ for the real node +node+.
+      def initialize(parent, node)
+        @parent = parent
+        @node = node
+        @children = []
+      end
+
+      # Sort recursively all children of the node using the wrapped nodes.
+      def sort!
+        self.children.sort! {|a,b| a.node <=> b.node}
+        self.children.each {|child| child.sort!}
+        self
+      end
+
+      # Return the menu tree under the node as nested list of alcn values.
+      def to_lcn_list
+        self.children.inject([]) {|temp, n| temp << n.node.absolute_lcn; temp += ((t = n.to_lcn_list).empty? ? [] : [t]) }
+      end
+
+    end
+
+    def initialize #:nodoc:
+      website.blackboard.add_listener(:node_changed?, method(:node_changed?))
+    end
+
+    # Generate the menu.
+    def call(tag, body, context)
+      tree = specific_menu_tree_for(context.content_node)
+
+      (context.dest_node.node_info[:tag_menu_menus] ||= []) << [@params, context.content_node.absolute_lcn, (tree ? tree.to_lcn_list : nil)]
+      if tree && !tree.children.empty?
+        "<div class=\"webgen-menu\">#{create_output(context, tree)}</div>"
+      else
+        ""
+      end
+    end
+
+    #########
+    protected
+    #########
+
+    # Check if the menus for +node+ have changed.
+    def node_changed?(node)
+      return if !node.node_info[:tag_menu_menus] || @inside_node_changed
+
+      @inside_node_changed = true  #TODO: better solution for this race condition?
+      node.node_info[:tag_menu_menus].each do |params, cn_alcn, cached_tree|
+        cn = node.tree[cn_alcn]
+        menu_tree = menu_tree_for_lang(cn.lang, cn.tree.root)
+
+        set_params(params)
+        tree = build_specific_menu_tree(cn, menu_tree)
+        tree_list = tree.to_lcn_list if tree
+        set_params({})
+
+        if (tree.nil? && !cached_tree.nil?) || (tree_list && tree_list != cached_tree) ||
+            (tree_list && tree_list.flatten.any? {|alcn| (n = node.tree[alcn]) && (r = n.routing_node(cn.lang)) && r != node && r.changed?})
+          node.dirty = true
+          break
+        end
+      end
+      @inside_node_changed = false
+    end
+
+    # Wrapper method for returning the specific menu tree for +content_node+.
+    def specific_menu_tree_for(content_node)
+      tree = menu_tree_for_lang(content_node.lang, content_node.tree.root)
+      if param('tag.menu.used_nodes') == 'fragments'
+        @params['tag.menu.start_level'] = param('tag.menu.start_level') + content_node.level
+      end
+      build_specific_menu_tree(content_node, tree)
+    end
+
+    # Build a menu tree for +content_node+ from the tree +menu_node+.
+    def build_specific_menu_tree(content_node, menu_node, level = 1)
+      if menu_node.nil? \
+        || level > param('tag.menu.max_levels') + param('tag.menu.start_level') - 1 \
+        || ((level > param('tag.menu.min_levels') + param('tag.menu.start_level') - 1) \
+             && (menu_node.node.level >= content_node.level \
+                  || (param('tag.menu.show_current_subtree_only') && !content_node.in_subtree_of?(menu_node.node))
+                 )
+            ) \
+        || (level == param('tag.menu.start_level') && !content_node.in_subtree_of?(menu_node.node))
+        return nil
+      end
+
+      sub_menu_tree = MenuNode.new(nil, menu_node.node)
+      menu_tree = MenuNode.new(nil, menu_node.node)
+      menu_node.children.each do |child|
+        next if param('tag.menu.used_nodes') == 'files' && !is_in_menu_tree_of_files?(child)
+        menu_tree.children << (this_node = MenuNode.new(menu_tree, child.node))
+        sub_node = child.children.length > 0 ? build_specific_menu_tree(content_node, child, level + 1) : nil
+        sub_node.children.each {|n| this_node.children << n; sub_menu_tree.children << n} if sub_node
+      end
+
+      if level < param('tag.menu.start_level')
+        sub_menu_tree
+      else
+        menu_tree
+      end
+    end
+
+    # Return +true+ if +menu_node+ is in the menu tree without fragment nodes.
+    def is_in_menu_tree_of_files?(menu_node)
+      (!menu_node.node.is_fragment? && menu_node.node['in_menu']) || menu_node.children.any? {|c| is_in_menu_tree_of_files?(c)}
+    end
+
+    # Create the HTML menu of the +tree+ using the provided +context+.
+    def create_output(context, tree)
+      out = "<ul>"
+      tree.children.each do |child|
+        menu = child.children.length > 0 ? create_output(context, child) : ''
+        style, link = menu_item_details(context.dest_node, child.node, context.content_node.lang)
+
+        out << "<li #{style}>#{link}"
+        out << menu
+        out << "</li>"
+      end
+      out << "</ul>"
+      out
+    end
+
+    # Return style information (node is selected, ...) and a link from +dest_node+ to +node+.
+    def menu_item_details(dest_node, node, lang)
+      styles = []
+      styles << 'webgen-menu-submenu' if node.is_directory? || (node.is_fragment? && node.children.length > 0)
+      styles << 'webgen-menu-submenu-inhierarchy' if (node.is_directory? || (node.is_fragment? && node.children.length > 0)) &&
+        dest_node.in_subtree_of?(node)
+      styles << 'webgen-menu-item-selected' if node == dest_node
+      style = "class=\"#{styles.join(' ')}\"" if styles.length > 0
+
+      link = dest_node.link_to(node)
+
+      [style, link]
+    end
+
+    # Return the menu tree for the language +lang+.
+    def menu_tree_for_lang(lang, root)
+      menus = (website.cache.volatile[:menutrees] ||= {})
+      unless menus[lang]
+        menus[lang] = create_menu_tree(root, nil, lang)
+        menus[lang].sort! if menus[lang]
+      end
+      menus[lang]
+    end
+
+    # Create and return a menu tree if at least one node is in the menu or +nil+ otherwise.
+    def create_menu_tree(node, parent, lang)
+      menu_node = MenuNode.new(parent, node)
+
+      node.children.select do |child|
+        child.lang == lang || child.lang.nil? || child.is_directory?
+      end.each do |child|
+        sub_node = create_menu_tree(child, menu_node, lang)
+        menu_node.children << sub_node unless sub_node.nil?
+      end
+
+      menu_node.children.empty? ? (node['in_menu'] ? menu_node : nil) : menu_node
+    end
+
+
+  end
+
+end

data/lib/webgen/tag/metainfo.rb

@@ -0,0 +1,25 @@
+require 'webgen/tag'
+
+module Webgen::Tag
+
+  # Provides easy access to the meta information of a node.
+  class Metainfo
+
+    include Base
+
+    # Return the meta information key specified in +tag+ of the content node.
+    def call(tag, body, context)
+      output = ''
+      if tag == 'lang'
+        output = context.content_node.lang
+      elsif context.content_node[tag]
+        output = context.content_node[tag].to_s
+      else
+        log(:warn) { "No value for tag '#{tag}' in <#{context.ref_node.absolute_lcn}> found in <#{context.content_node.absolute_lcn}>" }
+      end
+      output
+    end
+
+  end
+
+end

data/lib/webgen/tag/relocatable.rb

@@ -0,0 +1,53 @@
+require 'webgen/tag'
+require 'uri'
+
+module Webgen::Tag
+
+  # Makes a path relative. This is very useful for templates. For example, you normally include a
+  # stylesheet in a template. If you specify the filename of the stylesheet directly, the reference
+  # to the stylesheet in the output file of a page file that is not in the same directory as the
+  # template would be invalid.
+  #
+  # By using the +relocatable+ tag you ensure that the path stays valid.
+  class Relocatable
+
+    include Webgen::Tag::Base
+
+    # Return the relativized path for the path provided in the tag definition.
+    def call(tag, body, context)
+      uri_string = param('tag.relocatable.path')
+      result = ''
+      unless uri_string.nil?
+        begin
+          uri = URI.parse(uri_string)
+          if uri.absolute?
+            result = uri_string
+          else
+            result = resolve_path(uri_string, context)
+          end
+          if result.empty?
+            log(:error) { "Could not resolve path '#{uri_string}' in <#{context.ref_node.absolute_lcn}>" }
+            context.dest_node.dirty = true
+          end
+        rescue URI::InvalidURIError => e
+          log(:error) { "Error while parsing path for tag relocatable in <#{context.ref_node.absolute_lcn}>: #{e.message}" }
+          context.dest_node.dirty = true
+        end
+      end
+      result
+    end
+
+    #######
+    private
+    #######
+
+    # Resolve the path +uri+ using the reference node and return the correct relative path from the
+    # destination node.
+    def resolve_path(uri, context)
+      dest_node = context.ref_node.resolve(uri, context.dest_node.lang)
+      (dest_node ? context.dest_node.route_to(dest_node) : '')
+    end
+
+  end
+
+end

data/lib/webgen/tree.rb

@@ -0,0 +1,80 @@
+require 'webgen/websiteaccess'
+require 'webgen/node'
+
+module Webgen
+
+  # Represents a tree of nodes.
+  class Tree
+
+    include WebsiteAccess
+
+    # The dummy root. This is the default node that gets created when the Tree is created sothat the
+    # real root node can be treated like any other node. It has only one child, namely the real root
+    # node of the tree.
+    attr_reader :dummy_root
+
+    # Direct access to the hashes for node resolving. Only use this for reading purposes! If you
+    # just want to get a specific node for an alcn/acn/output path, use #node instead.
+    attr_reader :node_access
+
+    # The hash containing processing information for each node. This is normally not accessed
+    # directly but via the Node#node_info method.
+    attr_reader :node_info
+
+    # Create a new Tree object.
+    def initialize
+      @node_access = {:alcn => {}, :acn => {}, :path => {}}
+      @node_info = {}
+      @dummy_root = Node.new(self, '', '')
+    end
+
+    # The real root node of the tree.
+    def root
+      @dummy_root.children.first
+    end
+
+    # Access a node via a +path+ of a specific +type+. If type is +alcn+ then +path+ has to be an
+    # absolute localized canonical name, if type is +acn+ then +path+ has to be an absolute
+    # canonical name and if type is +path+ then +path+ needs to be an output path.
+    #
+    # Returns the requested Node or +nil+ if such a node does not exist.
+    def node(path, type = :alcn)
+      (type == :acn ? @node_access[type][path] && @node_access[type][path].first : @node_access[type][path])
+    end
+    alias_method :[], :node
+
+    # A utility method called by Node#initialize. This method should not be used directly!
+    def register_node(node)
+      if @node_access[:alcn].has_key?(node.absolute_lcn)
+        raise "Can't have two nodes with same absolute lcn: #{node.absolute_lcn}"
+      else
+        @node_access[:alcn][node.absolute_lcn] = node
+      end
+      (@node_access[:acn][node.absolute_cn] ||= []) << node
+      if @node_access[:path].has_key?(node.path)
+        raise "Can't have two nodes with same output path: #{node.path}" unless node['no_output']
+      else
+        @node_access[:path][node.path] = node
+      end
+    end
+
+    # Delete the node identified by +node_or_alcn+ and all of its children from the
+    # tree. Directories are only deleted if +delete_dir+ is +true+.
+    def delete_node(node_or_alcn, delete_dir = false)
+      n = node_or_alcn.kind_of?(Node) ? node_or_alcn : @node_access[:alcn][node_or_alcn]
+      return if n.nil? || n == @dummy_root || (n.is_directory? && !delete_dir)
+
+      n.children.dup.each {|child| delete_node(child, true)}
+
+      website.blackboard.dispatch_msg(:before_node_deleted, n)
+      n.parent.children.delete(n)
+      @node_access[:alcn].delete(n.absolute_lcn)
+      @node_access[:acn][n.absolute_cn].delete(n)
+      @node_access[:path].delete(n.path)
+
+      node_info.delete(n.absolute_lcn)
+    end
+
+  end
+
+end