duck_map 0.8.0

data/lib/duck_map/mapper.rb

@@ -0,0 +1,216 @@
+require 'active_support/concern'
+
+module DuckMap
+    
+  ##################################################################################
+  # Add functionality to ActionDispatch::Routing::Mapper  The purpose of this module
+  # is to provide methods that can be used within config/routes.rb to define sitemaps
+  # and configure sitemap options.
+  module Mapper
+    extend ActiveSupport::Concern
+
+    ##################################################################################
+    # Defines a sitemap for a Rails app.
+    # @return [Nil]
+    def sitemap(name = :sitemap, options = {}, &block)
+      options = name.kind_of?(Hash) ? name : options
+      name = name.kind_of?(String) || name.kind_of?(Symbol) ? name : :sitemap
+      config = {controller: :sitemap, url_limit: nil}.merge(options)
+
+      sitemap_raw_route_name = "#{name}_sitemap"
+
+      # create a route for the sitemap using the name that was passed to the sitemap method inside config/routes.
+      match %(/#{name}.:format), controller: config[:controller], action: name, as: sitemap_raw_route_name
+
+      # the current Rails implementation keeps the routes in an array.  Also, it does nothing to prevent duplicate routes from being added.
+      # at the time of development, the route is always at the end of the list, so, it is pretty safe to assume
+      # the last route in the list is the sitemap route we just added.
+      
+      # last_route_name is used after we check to see if we just added a duplicate route.
+      last_route_name = @set.routes.last.route_name
+
+      # identify the route as a "sitemap" route and build it's full name.
+      @set.routes.last.is_sitemap = true
+      @set.routes.last.url_limit = config[:url_limit]
+      @set.routes.last.sitemap_route_name = last_route_name
+      @set.routes.last.sitemap_raw_route_name = sitemap_raw_route_name
+
+      # determine if we added a duplicate route.
+      # The gem defines a default sitemap in config/routes.rb (inside the gem, not the app).
+      # So, it is very likely that most apps will be creating duplicates since most of the code is geared towards
+      # automagically configuring as much as possible.
+      sitemap_routes = @set.routes.find_all {|route| route.is_sitemap? && route.name.eql?(last_route_name) }
+      
+      # if there are more than one routes with the same name, then, we must have added a duplicate.  so, remove it.
+      #@set.routes.pop if sitemap_routes.length > 1
+      @set.routes.routes.pop if sitemap_routes.length > 1
+
+      # now, find the route again.
+      sitemap_route = @set.routes.find {|route| route.is_sitemap? && route.name.eql?(last_route_name) }
+
+      # once a sitemap route has been flagged as being defined with a block, then, you should never set it back to false.
+      # one of the features is to be able to encapsulate a set of routes within a sitemap as many times as you need.
+      # meaning, you might want to wrap five routes at the top of the file, three in the middle, and two at the bottom and
+      # have all of them included in the default sitemap.
+      # Since all routes within a sitemap block will be marked with the same name, 
+      # I am not keeping track of sitemaps being defined with or without a block, so, all I need to know is about one of them.
+      unless sitemap_route.sitemap_with_block?
+        sitemap_route.sitemap_with_block = true if block_given?
+      end
+
+      # DuckMap::SitemapControllerHelpers is a module that is included in SitemapBaseController and contains
+      # methods such as sitemap_build, etc.  Define a method to handle the sitemap on DuckMap::SitemapControllerHelpers
+      # so that method is visible to the default sitemap controller as well as any custom controllers that inherit from it.
+      # originally, I was simply defining the method directly on SitemapBaseController, however, it was causing problems
+      # during the development cycle of edit and refresh.  Defining methods here seemed to cure that problem.
+      # for example, the default sitemap: /sitemap.xml will define a method named: sitemap
+      # on the DuckMap::SitemapControllerHelpers module.
+      unless DuckMap::SitemapControllerHelpers.public_method_defined?(name)
+        DuckMap::SitemapControllerHelpers.send :define_method, name do
+
+          if DuckMap::Config.attributes[:sitemap_content].eql?(:xml)
+
+            sitemap_build
+
+          end
+
+          respond_to do |format|
+            format.xml { render }
+          end
+        end
+      end
+
+      # determine if the sitemap definition included a block.
+      if block_given?
+
+        # the starting point would be after the current set of routes and would be length plus one.
+        # however, the starting point index is the length of routes, since arrays are zero based.
+        start_point = @set.routes.length
+
+        # push a copy of the current filter settings onto an array.
+        # this will allow you to specify criteria setting within a sitemap definition without affecting
+        # the default settings after the block is finished executing.
+        @set.sitemap_filters.push
+
+        # yield to the block.  all standard route code should execute just fine and define namespaces, resource, matches, etc.
+        yield
+
+        total = run_filter(sitemap_route.sitemap_route_name, start_point)
+
+        # knock the current filter setting off of the stack
+        @set.sitemap_filters.pop
+
+        DuckMap.logger.debug %(total routes filtered: #{@set.routes.length - start_point}  included? #{total})
+
+        @set.routes.each do |route|
+          DuckMap.logger.debug %(  Route name: #{route.name}) if route.sitemap_route_name.eql?(sitemap_route.sitemap_route_name)
+        end
+
+      end
+
+      return nil
+    end
+
+    ##################################################################################
+    def run_filter(sitemap_route_name = nil, start_point = 0)
+      total = 0
+
+      # assign the sitemap_route_name to the sitemap_route_name attribute of every route that has just been added during the execution of the above block.
+      start_point.upto(@set.routes.length + 1) do |index|
+
+        # this is where the actual filtering of routes occurs and is based on the current sitemap filter settings.
+        # if the route passes the criteria, then, it is "marked" as part of the sitemap.
+        # no need to evaluate it every time a sitemap is requested.  evaluate it now and mark it.
+
+        if !@set.routes.routes[index].blank? && @set.routes.routes[index].sitemap_route_name.blank?
+          if @set.include_route?(@set.routes.routes[index]) && !sitemap_route_name.blank?
+            @set.routes.routes[index].sitemap_route_name = sitemap_route_name
+            total += 1
+          else
+            @set.routes.routes[index].sitemap_route_name = "do_not_use"
+          end
+        end
+
+      end
+
+      return total
+    end
+
+  end
+
+  ##################################################################################
+  module MapperMethods
+    extend ActiveSupport::Concern
+
+    ##################################################################################
+    # See {DuckMap::Sitemap::RouteFilter::InstanceMethods#blank_route_name blank_route_name}
+    def allow_blank_route_name(value)
+      @set.blank_route_name = value
+    end
+
+    ##################################################################################
+    def clear_filters
+      @set.sitemap_filters.clear_filters
+    end
+
+    ##################################################################################
+    def clear_filter(key)
+      @set.sitemap_filters.clear_filter(key)
+    end
+
+    ##################################################################################
+    def exclude_actions(*args)
+      args.insert(0, :actions)
+      @set.sitemap_filters.exclude_filter(*args)
+    end
+
+    ##################################################################################
+    def exclude_controllers(*args)
+      args.insert(0, :controllers)
+      @set.sitemap_filters.exclude_filter(*args)
+    end
+
+    ##################################################################################
+    def exclude_names(*args)
+      args.insert(0, :names)
+      @set.sitemap_filters.exclude_filter(*args)
+    end
+
+    ##################################################################################
+    def exclude_verbs(*args)
+      args.insert(0, :verbs)
+      @set.sitemap_filters.exclude_filter(*args)
+    end
+
+    ##################################################################################
+    def include_actions(*args)
+      args.insert(0, :actions)
+      @set.sitemap_filters.include_filter(*args)
+    end
+
+    ##################################################################################
+    def include_controllers(*args)
+      args.insert(0, :controllers)
+      @set.sitemap_filters.include_filter(*args)
+    end
+
+    ##################################################################################
+    def include_names(*args)
+      args.insert(0, :names)
+      @set.sitemap_filters.include_filter(*args)
+    end
+
+    ##################################################################################
+    def include_verbs(*args)
+      args.insert(0, :verbs)
+      @set.sitemap_filters.include_filter(*args)
+    end
+
+    ##################################################################################
+    def reset_filters
+      @set.sitemap_filters.reset
+    end
+
+  end
+
+end

data/lib/duck_map/model.rb

@@ -0,0 +1,27 @@
+# DONE
+require 'active_support/concern'
+
+module DuckMap
+
+  ##################################################################################
+  # Model has a very specific purpose.  To hold the Array of Hash objects that represent
+  # the contents of a single sitemap.
+  module Model
+    extend ActiveSupport::Concern
+
+    ##################################################################################
+    # Array containing all of the Hash objects that represent the contents of a single sitemap.
+    # Originally, this method was part of {DuckMap::ControllerHelpers}, however, it was separated
+    # and moved here to minimize the number of methods being added to controllers.
+    # @return [Array]
+    def sitemap_model
+      @sitemap_model ||= []
+    end
+
+    def sitemap_model=(value)
+      @sitemap_model = value
+    end
+
+  end
+
+end

data/lib/duck_map/route.rb

@@ -0,0 +1,275 @@
+require 'active_support/concern'
+
+module DuckMap
+
+  ##################################################################################
+  # Conveience methods that wrap standard ActionDispatch::Routing::Route methods and data.
+  # The purpose is to harness the existing code to allow extra config arguments to be included
+  # on routes within config/routes.rb.  ActionDispatch::Routing::Route has a couple of instance variables
+  # (defaults and requirements).
+  #   - defaults is a Hash that contains the arguments passed to methods within config/routes.rb such as
+  #     resources, match, etc.  The arguments passed to most routes config methods will actually make a call
+  #     to match to add a route and will include any extra arguments you pass in the defaults Hash.
+  #     The methods of this module extract those values.
+  #   - requirements is a Hash that contains the controller and action name of the current route.
+  module Route
+    extend ActiveSupport::Concern
+    include DuckMap::ArrayHelper
+
+    ##################################################################################
+    #module InstanceMethods
+
+      # Identifies the current routes as being a sitemap route.
+      attr_accessor :is_sitemap
+
+      # The route name of the sitemap which the current route is assigned.
+      attr_accessor :sitemap_route_name
+
+      # The route name of the sitemap without the namespace.
+      attr_accessor :sitemap_raw_route_name
+
+      # Identifies that the current sitemap route was defined with a block.
+      attr_accessor :sitemap_with_block
+
+      # Total amount of URL nodes allowed in the sitemap.
+      attr_accessor :url_limit
+
+      ##################################################################################
+      # Identifies the current routes as being a sitemap route.
+      # @return [Boolean]  True if the route is a sitemap route, otherwise, false.
+      def is_sitemap?
+        @is_sitemap = @is_sitemap.nil? ? false : @is_sitemap
+      end
+
+      ##################################################################################
+      # @return [String] Namespace prefix used when creating the route.
+      def namespace_prefix
+        value = nil
+
+        unless self.sitemap_raw_route_name.blank?
+          value = self.sitemap_route_name.gsub(self.sitemap_raw_route_name, "")
+        end
+
+        return value
+      end
+
+      ##################################################################################
+      def namespace_prefix_underscores
+        value = 0
+
+        buffer = self.namespace_prefix
+        unless buffer.blank?
+          value = buffer.split("_").length
+        end
+
+        return value
+      end
+
+      ##################################################################################
+      # Identifies that the current sitemap route was defined with a block.
+      # @return [Boolean]  True if the route was defined with a block, otherwise, false.
+      def sitemap_with_block?
+        @sitemap_with_block = @sitemap_with_block.nil? ? false : @sitemap_with_block
+      end
+
+      ##################################################################################
+      # Conveience method to return the name assigned to the route.  There is no need for nil
+      # checking the return value of this method.  It will simply return an empty String.
+      # @return [String] Name assigned to the route.
+      def route_name
+        return "#{self.name}"
+      end
+
+      ##################################################################################
+      # Returns the controller_name assigned to the route.
+      # @return [String] Controller_name name assigned to the route.
+      def controller_name
+        return self.requirements[:controller].blank? ? "" : self.requirements[:controller].to_s
+      end
+
+      ##################################################################################
+      # Returns the action assigned to the route.
+      # @return [String] Action name assigned to the route.
+      def action_name
+        return self.requirements[:action].blank? ? "" : self.requirements[:action].to_s
+      end
+
+      ##################################################################################
+      # The class name (as a String) of a model to be used as the source of rows for a route
+      # when generating sitemap content.
+      # @return [String]
+      def model
+        return self.defaults[:model]
+      end
+
+      ##################################################################################
+      # Setting changefreq directly on the route will override values set within a controller and model.
+      # This value will be used when generating a sitemap for the specific route.
+      #
+      #    MyApp::Application.routes.draw do
+      #
+      #      resources :trucks, :changefreq => "daily"
+      #
+      #    end
+      #
+      # produces url's like the following:
+      #
+      #    <url>
+      #      <loc>http://localhost:3000/trucks/1.html</loc>
+      #      <lastmod>2011-10-13T06:16:24+00:00</lastmod>
+      #      <changefreq>daily</changefreq>
+      #      <priority>0.5</priority>
+      #    </url>
+      #
+      # @return [String] Current value of changefreq.
+      def changefreq
+        return self.defaults[:changefreq]
+      end
+
+      ##################################################################################
+      # Setting priority directly on the route will override values set within a controller and model.
+      # This value will be used when generating a sitemap for the specific route.
+      #
+      #    MyApp::Application.routes.draw do
+      #
+      #      resources :trucks, :priority => "0.4"
+      #
+      #    end
+      #
+      # produces url's like the following:
+      #
+      #    <url>
+      #      <loc>http://localhost:3000/trucks/1.html</loc>
+      #      <lastmod>2011-10-13T06:16:24+00:00</lastmod>
+      #      <changefreq>monthly</changefreq>
+      #      <priority>0.4</priority>
+      #    </url>
+      #
+      # @return [String] Current value of priority.
+      def priority
+        return self.defaults[:priority]
+      end
+
+      ##################################################################################
+      # Specifies the extension that should be used when generating a url for the route within a sitemap.
+      #
+      #    MyApp::Application.routes.draw do
+      #
+      #      resources :trucks, :url_format => "xml"
+      #
+      #    end
+      #
+      # produces url's like the following:
+      #
+      #    <loc>http://localhost:3000/trucks/1.xml</loc>
+      #    <loc>http://localhost:3000/trucks/2.xml</loc>
+      #
+      # @return [String]
+      def url_format
+        # a quick hack to default the extension for the root url to :none
+        return self.defaults[:url_format].blank? && self.route_name.eql?("root") ? :none : self.defaults[:url_format]
+      end
+
+      ##################################################################################
+      def exclude_actions
+        return self.duckmap_defaults(:exclude_actions)
+      end
+
+      ##################################################################################
+      def exclude_controllers
+        return self.duckmap_defaults(:exclude_controllers)
+      end
+
+      ##################################################################################
+      def exclude_names
+        return self.duckmap_defaults(:exclude_names)
+      end
+
+      ##################################################################################
+      def exclude_verbs
+        return self.duckmap_defaults(:exclude_verbs)
+      end
+
+      ##################################################################################
+      def include_actions
+        return self.duckmap_defaults(:include_actions)
+      end
+
+      ##################################################################################
+      def include_controllers
+        return self.duckmap_defaults(:include_controllers)
+      end
+
+      ##################################################################################
+      def include_names
+        return self.convert_to(self.duckmap_defaults(:include_names), :string)
+      end
+
+      ##################################################################################
+      def include_verbs
+        return self.duckmap_defaults(:include_verbs)
+      end
+
+      ##################################################################################
+      def verb_symbol
+        value = nil
+          unless self.verb.blank?
+            buffer = self.verb.to_s.downcase
+            if buffer.include?("delete")
+              value = :delete
+
+            elsif buffer.include?("get")
+              value = :get
+
+            elsif buffer.include?("post")
+              value = :post
+
+            elsif buffer.include?("put")
+              value = :put
+
+            end
+
+          end
+        return value
+      end
+
+      ##################################################################################
+      # Indicates if the current route requirements segments keys to generate a url.
+      # @return [Boolean] True if keys are required to generate a url, otherwise, false.
+      def keys_required?
+        keys = self.segment_keys.dup
+        keys.delete(:format)
+        return keys.length > 0 ? true : false
+      end
+
+      ##################################################################################
+      # Looks for a key within ActionDispatch::Routing::Route.defaults.
+      # If found:
+      #   - determine the type of value:
+      #     - If Array, return the array.
+      #     - If String, create an array, add the String to it, and return the array.
+      #     - If Symbol, create an array, add the Symbol to it, and return the array.
+      # If nothing found, return an empty array.
+      # returns [Array]
+      def duckmap_defaults(key)
+        values = []
+
+        if self.defaults && self.defaults[key]
+          if self.defaults[key].kind_of?(Array)
+            values = self.defaults[key]
+
+          elsif self.defaults[key].kind_of?(String)
+            values.push(self.defaults[key])
+
+          elsif self.defaults[key].kind_of?(Symbol)
+            values.push(self.defaults[key])
+
+          end
+        end
+
+        return values
+      end
+    #end
+
+  end
+end

data/lib/duck_map/route_filter.rb

@@ -0,0 +1,177 @@
+# the rule is the filter criteria acts as a list of things to include.  period.
+# include methods will add to the list of criteria to include.
+# exclude methods will remove from the list of criteria to include.
+# for route level evaluations, the list of criteria to include is empty.  therefore, meaning nothing is included.
+# the include attributes are added to the list of criteria to include, then, the exclude attributes are processed
+# to remove attributes from the list of criteria to include.
+# this will match the default behavior of nothing being included unless explicitly included.
+require 'active_support/concern'
+
+module DuckMap
+
+  class DuckmapExclude < StandardError
+  end
+
+  class DuckmapInclude < StandardError
+  end
+
+  class ExplicitExclude < StandardError
+  end
+
+  class ExplicitInclude < StandardError
+  end
+
+  class RouteNameMissing < StandardError
+  end
+
+  ##################################################################################
+  # Mixin module for ActionDispatch::Routing::RouteSet.  This module is responsible for evaluating each route
+  # for consideration to be included in a sitemap.
+  module RouteFilter
+    extend ActiveSupport::Concern
+
+    # Indicates to the route filter to exclude / include routes that are missing names.
+    attr_accessor :blank_route_name
+
+    ##################################################################################
+    # Indicates to the route filter to exclude / include routes that are missing names.
+    # @return [Boolean]
+    def blank_route_name?
+      return self.blank_route_name.nil? ? false : self.blank_route_name
+    end
+
+    ##################################################################################
+    # A Hash containing all of the values for exlude sitemap_filters.
+    # @return [Hash]
+    def sitemap_filters
+      return @sitemap_filters ||= FilterStack.new
+    end
+
+    ##################################################################################
+    # Determines if the current routes passes the current filter criteria.
+    # @return [Boolean]  True if it passes, otherwise, false.
+    def include_route?(route)
+      value = false
+
+      unless route.blank? || route.path.spec =~ %r{/rails/info/properties|^/assets}
+        # this block looks very busy, but, actually all that is really going on here is we are matching
+        # parts of the current route against sitemap_filter data configured via config/routes.rb, then,
+        # raising and catching exceptions based on the outcome of each evaluation.
+        # the rule is all routes excluded, unless included via some type of filter criteria.
+
+        begin
+
+          DuckMap.logger.debug "\r\n  Route: #{route.verb_symbol} #{route.route_name.ljust(30)} #{route.controller_name} => #{route.action_name}"
+          DuckMap.logger.debug route
+          DuckMap.logger.debug %(#{"Path:".rjust(30)} #{route.path.spec})
+
+          # we don't want to include routes without a name.
+          if route.name.blank?
+            unless self.blank_route_name?
+              raise RouteNameMissing, "route name blank"
+            end
+          end
+
+          if match_any?(route.action_name, route.exclude_actions) ||
+              match_any?(route.controller_name, route.exclude_controllers) ||
+              match_any?(route.name, route.exclude_names) ||
+              match_any?(route.verb_symbol, route.exclude_verbs)
+
+            raise DuckmapExclude, "exclude"
+
+          end
+
+          if match_any?(route.action_name, route.include_actions) ||
+              match_any?(route.controller_name, route.include_controllers) ||
+              match_any?(route.name, route.include_names) ||
+              match_any?(route.verb_symbol, route.include_verbs)
+
+            raise DuckmapInclude, "include"
+
+          end
+
+          if match_any?(route.action_name, self.sitemap_filters.current_filter[:actions])
+            raise ExplicitInclude, "include"
+          end
+
+          if match_any?(route.verb_symbol, self.sitemap_filters.current_filter[:verbs])
+            raise ExplicitInclude, "include"
+          end
+
+          if match_any?(route.controller_name, self.sitemap_filters.current_filter[:controllers])
+            raise ExplicitInclude, "include"
+          end
+
+          if match_any?(route.name, self.sitemap_filters.current_filter[:names])
+            raise ExplicitInclude, "include"
+          end
+
+        rescue DuckmapExclude => e
+          DuckMap.logger.debug %(#{"Duckmap Exclude".rjust(30)} -> #{e})
+
+          if match_any?(route.action_name, route.include_actions) ||
+              match_any?(route.controller_name, route.include_controllers) ||
+              match_any?(route.name, route.include_names) ||
+              match_any?(route.verb_symbol, route.include_verbs)
+
+            DuckMap.logger.debug %(#{"Duckmap Exclude".rjust(30)} -> included again...)
+            value = true
+          end
+
+        rescue DuckmapInclude => e
+          DuckMap.logger.debug %(#{"Duckmap Include".rjust(30)} -> #{e})
+          value = true
+
+        rescue ExplicitInclude => e
+          DuckMap.logger.debug %(#{"Explicit Include".rjust(30)} -> #{e})
+          value = true
+
+        rescue RouteNameMissing => e
+          DuckMap.logger.debug %(#{"Route Name Missing".rjust(30)} -> #{e})
+
+        rescue Exception => e
+          DuckMap.logger.info %(#{"Unknown Exception".rjust(30)} -> #{e})
+          DuckMap.logger.info e.backtrace.join("\r\n")
+        end
+
+      end
+
+      return value
+    end
+
+    ##################################################################################
+    # Matches a single value against an array of Strings, Symbols, and Regexp's.
+    # @param [String] data    Any value as a String to compare against any of the Strings, Symbols, or Regexp's in the values argument.
+    # @param [Array] values   An array of Strings, Symbols, or Regexp's to compare against the data argument.  The array can be a mix of all three possible types.
+    # @return [Boolean] True if data matches any of the values or expressions in the values argument, otherwise, false.
+    def match_any?(data = nil, values = [])
+
+      unless data.blank?
+
+        unless values.kind_of?(Array)
+          # wow, this worked!!??
+          # values was not an array, so, add values to a new array and assign back to values
+          values = [values]
+        end
+
+        values.each do |value|
+
+          if value.kind_of?(String) && (data.to_s.downcase.eql?(value.downcase) || value.eql?("all"))
+            return true
+
+          elsif value.kind_of?(Symbol) && (data.downcase.to_sym.eql?(value) || value.eql?(:all))
+            return true
+
+          elsif value.kind_of?(Regexp) && data.match(value)
+            return true
+
+          end
+        end
+
+      end
+
+      return false
+    end
+
+  end
+end