duck_map 0.8.0

data/app/controllers/sitemap_base_controller.rb

@@ -0,0 +1,13 @@
+class SitemapBaseController < ApplicationController
+
+  include DuckMap::SitemapControllerHelpers
+  helper DuckMap::Model
+  helper DuckMap::SitemapHelpers
+
+  rescue_from ActionView::MissingTemplate do |exception|
+    respond_to do |format|
+      format.xml { render :template => "sitemap/default_template"}
+    end
+  end
+
+end

data/app/controllers/sitemap_controller.rb

@@ -0,0 +1,3 @@
+class SitemapController < SitemapBaseController
+
+end

data/app/views/sitemap/default_template.xml.erb

@@ -0,0 +1,10 @@
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<%= sitemap_content do |row| %>
+  <url>
+    <loc><%= row[:loc] %></loc>
+    <lastmod><%= row[:lastmod] %></lastmod>
+    <changefreq><%= row[:changefreq] %></changefreq>
+    <priority><%= row[:priority] %></priority>
+  </url>
+<% end %>
+</urlset>

data/config/routes.rb

@@ -0,0 +1,5 @@
+Rails.application.routes.draw do
+
+  sitemap
+
+end

data/lib/duck_map/array_helper.rb

@@ -0,0 +1,50 @@
+# DONE
+module DuckMap
+
+  # This is a small helper used to ensure values in an Array of are a certain type.
+  module ArrayHelper
+
+    ##################################################################################
+    # Ensures all values in an Array are of a certain type.  This is meant to be used internally
+    # by DuckMap modules and classes.
+    #
+    #     values = ["new_book", "edit_book", "create_book", "destroy_book"]
+    #     values = obj.convert_to(values, :symbol)
+    #     puts values #=> [:new_book, :edit_book, :create_book, :destroy_book]
+    #
+    # @param [Array]    values The Array to inspect and convert.
+    # @param [Symbol]   type Valid values are :string and :symbol.
+    #                        - :string converts all values to a String.
+    #                        - :symbol converts all values to a Symbol.
+    # @return [Array]
+    def convert_to(values, type)
+      buffer = []
+
+      if values.kind_of?(Array)
+
+        values.each do |value|
+
+          begin
+
+            if type == :string
+              buffer.push(value.to_s)
+
+            elsif type == :symbol
+              buffer.push(value.to_sym)
+
+            end
+
+          rescue Exception => e
+          end
+
+        end
+
+      else
+        buffer = values
+      end
+
+      return buffer
+    end
+
+  end
+end

data/lib/duck_map/attributes.rb

@@ -0,0 +1,182 @@
+# DONE
+require 'active_support/concern'
+
+module DuckMap
+
+  ##################################################################################
+  # This module has a single purpose.  To declare a class-level attribute using the Rails class_attribute method.
+  # Also, we are using {ActiveSupport::Concern} and the included block.  This module is included in
+  # {ActionController::Base}, so, every controller object will have the attribute.
+  #
+  # See {DuckMap::Attributes::ClassMethods#sitemap_attributes} for an explanation.
+  module InheritableClassAttributes
+    extend ActiveSupport::Concern
+
+    ################################################################################
+    included do 
+      class_eval do
+
+        class_attribute :sitemap_attributes_hash
+        class_attribute :sitemap_attributes_defined
+
+      end
+    end
+
+  end
+
+  ##################################################################################
+  # Module used to add Sitemap attributes to an object.
+  module Attributes
+    extend ActiveSupport::Concern
+
+    ##################################################################################
+    module ClassMethods
+
+      ##################################################################################
+      ## See {DuckMap::Attributes#is_sitemap_attributes_defined? is_sitemap_attributes_defined?}
+      # @return [TrueClass, FalseClass]
+      def is_sitemap_attributes_defined?
+
+        if self.sitemap_attributes_defined.nil?
+          self.sitemap_attributes_defined = false
+        end
+
+        return self.sitemap_attributes_defined
+      end
+
+      ##################################################################################
+      # Returns the entire attributes Hash that has been defined for an object.  The actual Hash is maintained via an accessor method named: sitemap_attributes_hash.
+      # {#sitemap_attributes sitemap_attributes} is actually a wrapper method for sitemap_attributes_hash accessor method.
+      #
+      # There are actually two definitions of sitemap_attributes_hash accessor method.  The purpose of two definitions is to allow common code
+      # contained in {DuckMap::Attributes} to be included in the {DuckMap::Config} and all controller classes.  The code works by referencing
+      # sitemap_attributes_hash accessor method, however, the actual variable reference is different depending on the object that is referring to it.
+      #
+      # When {DuckMap::Attributes} module is included in {DuckMap::Config}, then, self.sitemap_attributes_hash is actually referencing the class
+      # level method defined on {DuckMap::Config}.
+      #
+      # When {DuckMap::Attributes} module is included in all controller classes (it is by default), then, self.sitemap_attributes_hash
+      # is actually referencing the class level method defined by {DuckMap::InheritableClassAttributes} via class_attribute method.
+      # This means that the actual variable that will contain the Hash value never gets initialized.  So, self.sitemap_attributes_hash
+      # will ALWAYS be uninitialized during the first access from within a controller and will ALWAYS copy values from {DuckMap::Config}.
+      #
+      # @return [Hash]
+      def sitemap_attributes
+
+        # check the current state of self.sitemap_attributes_hash.  If it is a Hash, then, it is considered initialized.
+        # otherwise, a new Hash is populated and assigned to self.sitemap_attributes_hash and a reference is returned.
+        #
+        # when this module is included in DuckMap::Config self.sitemap_attributes_hash is actually referencing the class
+        # level method defined on DuckMap::Config.
+        #
+        # When this module is included in all controller classes self.sitemap_attributes_hash is actually referencing the class
+        # level method defined on InheritableClassAttributes which never gets initialized.  So, self.sitemap_attributes_hash
+        # will NEVER be a Hash on the first access from within a controller and will ALWAYS copy values from {DuckMap::Config}
+        unless self.sitemap_attributes_hash.kind_of?(Hash)
+
+          # I actually have code to do a deep clone of a Hash, however, I can't release it right now.
+          # I will in a later release.  For now, I will commit another sin.
+          self.sitemap_attributes_hash = {}
+
+          source = DuckMap::Config.sitemap_attributes_hash
+
+          source.each do |item|
+            self.sitemap_attributes_hash[item.first] = {}.merge(item.last)
+            self.sitemap_attributes_hash[item.first][:handler] = {}.merge(item.last[:handler])
+          end
+
+        end
+
+        return self.sitemap_attributes_hash
+      end
+
+    end
+
+    ##################################################################################
+    # This is a simple boolean value with a specific purpose.  It is used to indicate if the object
+    # being worked on actually defined attributes using {DuckMap::SitemapObject::ClassMethods#acts_as_sitemap acts_as_sitemap},
+    # {DuckMap::SitemapObject::ClassMethods#sitemap_handler sitemap_handler} or {DuckMap::SitemapObject::ClassMethods#sitemap_segments sitemap_segments}
+    #
+    # This has special meaning for ActiveRecord::Base objects.  When {DuckMap::Handlers handler methods} evaluate a model, the model is asked
+    # if it defined it's own attributes.
+    #
+    # If the model did define it's own attributes, then, those attributes are used and override any attributes
+    # set via acts_as_sitemap, sitemap_handler, or sitemap_segments on the controller.
+    #
+    # If the model did not define it's own attributes, then, the attributes defined on the controller are used.
+    #
+    # Defaults from {DuckMap::Config} are used if neither controller nor model defined any attributes.
+    #
+    # @return [TrueClass, FalseClass]
+    def is_sitemap_attributes_defined?
+      return self.class.is_sitemap_attributes_defined?
+    end
+
+    ##################################################################################
+    # Returns a Hash associated with a key.  The Hash represents all of the attributes for
+    # a given action name on a controller.
+    #
+    #     acts_as_sitemap :index, title: "my title"   # index is the key
+    #     sitemap_attributes("index")                 # index is the key
+    #
+    # @return [Hash]
+    def sitemap_attributes(key = :default)
+      key = key.blank? ? :default : key.to_sym
+
+      # if the key exists and has a Hash value, cool.  Otherwise, go back to :default.
+      # self.class.sitemap_attributes should ALWAYS return a Hash, so, no need to test for that.
+      # however, key may or may not be a Hash.  should test for that.
+      unless self.class.sitemap_attributes[key].kind_of?(Hash)
+        key = :default
+      end
+
+      # the :default Hash SHOULD ALWAYS be there.  If not, this might cause an exception!!
+      return self.class.sitemap_attributes[key]
+    end
+
+    ##################################################################################
+    # Wrapper method for {#sitemap_attributes sitemap_attributes} that returns a Hash stripped of key/value pairs
+    # where the value is another Hash.
+    #
+    #     # normal
+    #     values = sitemap_attributes("index")
+    #     puts values #=> {:title=>:title, :keywords=>:keywords,
+    #                 #    :description=>:description, :lastmod=>:updated_at,
+    #                 #    :handler=>{:action_name=>:sitemap_index, :first_model=>true}}
+    #
+    #     # stripped
+    #     values = sitemap_stripped_attributes("index")
+    #     puts values #=> {:title=>:title, :keywords=>:keywords,
+    #                 #    :description=>:description, :lastmod=>:updated_at}
+    #
+    # @return [Hash]
+    def sitemap_stripped_attributes(key = :default)
+      values = {}
+
+      attributes = self.sitemap_attributes(key)
+      attributes.each do |pair|
+
+        # we are traversing a Hash in this loop.
+        # each item passed to the block is a two-element Array.
+        # the first element is a key and the second element is the value.
+        # given: {title: :my_title, handler: {action_name: :sitemap_index}}
+        # :title would be pair.first
+        # :my_title would be pair.last
+        # in the second case:
+        # :handler would be pair.first
+        # the Hash {action_name: :sitemap_index} would be pair.last
+        # we want to skip all the dark meat and keep the white meat.
+        # therefore, we are only interested in attributes that are on the first level.
+        # meaning, simple key/value pairs where the value is a value other than Hash.
+        unless pair.last.kind_of?(Hash)
+            values[pair.first] = pair.last
+        end
+
+      end
+
+      return values
+    end
+
+  end
+
+end

data/lib/duck_map/class_helpers.rb

@@ -0,0 +1,55 @@
+# DONE
+module DuckMap
+
+  ##################################################################################
+  # Simple helper class that tries to find controller and model classes based on a controller name.
+  class ClassHelpers
+
+    ##################################################################################
+    # Attempts to automagically determine the controller class name based on the named route.
+    # returns [Class]
+    def self.get_controller_class(controller_name)
+      controller = nil
+
+      begin
+
+        controller = "#{controller_name.camelize.pluralize}Controller".constantize
+
+      rescue Exception => e
+        # once upon a time, I was logging these exceptions, however, it made the log files very noisy.
+        # I expect to have the exceptions occur.  i plan on doing a little more on this area later.
+        controller = nil
+
+        begin
+
+          controller = "#{controller_name.camelize.singularize}Controller".constantize
+
+        rescue Exception => e
+          # once upon a time, I was logging these exceptions, however, it made the log files very noisy.
+          # I expect to have the exceptions occur.  i plan on doing a little more on this area later.
+        end
+      end
+
+      return controller
+    end
+
+    ##################################################################################
+    # Attempts to automagically determine the model class name based on the named route.
+    # returns [Class]
+    def self.get_model_class(controller_name)
+      value = nil
+
+      begin
+
+        value = controller_name.camelize.singularize.constantize
+
+      rescue Exception => e
+        # once upon a time, I was logging these exceptions, however, it made the log files very noisy.
+        # I expect to have the exceptions occur.  i plan on doing a little more on this area later.
+      end
+
+      return value
+    end
+
+  end
+end

data/lib/duck_map/config.rb

@@ -0,0 +1,367 @@
+module DuckMap
+
+  ##################################################################################
+  # Config holds default values and attributes for sitemap and meta tags.
+  # see {file:GUIDE.md#Default_values_and_attributes Guide}
+  class Config
+    include Attributes
+    include SitemapObject
+
+    ##################################################################################
+    # Resets {.sitemap_attributes_hash} and {.attributes} to the defaults.
+    #
+    # @param [Symbol, String] name  The name of the class variable to reset.
+    #                                 - :all - resets both variables.
+    #                                 - :attributes - resets the {.attributes}
+    #                                 - :sitemap_attributes_hash - resets the {.sitemap_attributes_hash}
+    # @return [NilClass]
+    def self.reset(name = :all)
+      name = name.blank? ? :all : name.to_sym
+
+      if name.eql?(:all) || name.eql?(:sitemap_attributes_hash)
+        self.sitemap_attributes_hash = nil
+      end
+
+      if name.eql?(:all) || name.eql?(:attributes)
+        self.attributes = nil
+      end
+
+      if name.eql?(:all) || name.eql?(:sitemap_attributes_defined)
+        self.sitemap_attributes_defined = nil
+      end
+
+      return nil
+    end
+
+    ##################################################################################
+    # This method needs to exist since {DuckMap::Attributes} is included in this class.
+    #
+    # See {DuckMap::Attributes#is_sitemap_attributes_defined?} for details.
+    #
+    # @return [TrueClass, FalseClass]
+    def self.sitemap_attributes_defined
+
+      if !defined?(@@sitemap_attributes_defined) || @@sitemap_attributes_defined.nil?
+        @@sitemap_attributes_defined = false
+      end
+
+      return @@sitemap_attributes_defined
+    end
+
+    ##################################################################################
+    # Setter method for sitemap_attributes_defined
+    # @return [TrueClass, FalseClass]
+    def self.sitemap_attributes_defined=(value)
+      @@sitemap_attributes_defined = value
+    end
+
+    ##################################################################################
+    # Class-level accessor method.  The value of the class variable @@sitemap_attributes_hash
+    # is checked prior to returning a reference to it.  If the variable has not been defined or is nil,
+    # then, it is initialized with default values.
+    #
+    # See {DuckMap::Attributes::ClassMethods#sitemap_attributes} for an explanation.
+    #
+    # @return [Hash]
+    def self.sitemap_attributes_hash
+
+      if !defined?(@@sitemap_attributes_hash) || @@sitemap_attributes_hash.nil?
+
+        # many tests are sensitive to the values generated by this method.
+        # changes to this structure will make tests fails until you edit
+        # some of the .yml file(s) in the tests directory
+        values = {
+                  title: :title,
+                  keywords: :keywords,
+                  description: :description,
+                  lastmod: :updated_at,
+                  changefreq: nil,
+                  priority: nil,
+                  canonical: nil,
+                  canonical_host: nil,
+                  canonical_port: nil,
+                  #compression: nil,      # don't need it here.
+                  #sitemap_content: nil,  # don't need it here.
+                  static_host: nil,
+                  static_port: nil,
+                  #static_target: nil,    # don't need it here.
+                  url_format: nil,
+                  url_limit: nil
+                  }
+
+        @@sitemap_attributes_hash = {}
+        @@sitemap_attributes_hash[:default] = {}.merge(values)
+        @@sitemap_attributes_hash[:default][:handler] = {action_name: :sitemap_index, first_model: false}
+
+        @@sitemap_attributes_hash[:edit] = {}.merge(values)
+        @@sitemap_attributes_hash[:edit][:handler] = {action_name: :sitemap_edit, first_model: true}
+
+        @@sitemap_attributes_hash[:index] = {}.merge(values)
+        @@sitemap_attributes_hash[:index][:handler] = {action_name: :sitemap_index, first_model: true}
+
+        @@sitemap_attributes_hash[:new] = {}.merge(values)
+        @@sitemap_attributes_hash[:new][:handler] = {action_name: :sitemap_new, first_model: true}
+
+        @@sitemap_attributes_hash[:show] = {}.merge(values)
+        @@sitemap_attributes_hash[:show][:handler] = {action_name: :sitemap_show, first_model: true}
+
+      end
+
+      return @@sitemap_attributes_hash
+    end
+
+    ###################################################################################
+    # Returns a copy of the entire sitemap_attributes_hash Hash.
+    # return [Hash]
+    def self.copy_sitemap_attributes_hash
+      values = {}
+
+      # I actually have code to do a deep clone of a Hash, however, I can't release it right now.
+      # I will in a later release.  For now, I will commit another sin.
+
+      self.sitemap_attributes_hash.each do |item|
+        values[item.first] = {}.merge(item.last)
+        values[item.first][:handler] = {}.merge(item.last[:handler])
+      end
+
+      return values
+    end
+
+    ###################################################################################
+    # Class-level accessor method.  Sets the value of the class variable @@sitemap_attributes_hash.
+    # Setting the value to nil will cause it to be re-initialized on the next call to the get
+    # method: class variable {.sitemap_attributes_hash}
+    # @return [Hash]
+    def self.sitemap_attributes_hash=(value)
+      @@sitemap_attributes_hash = value
+      return @@sitemap_attributes_hash
+    end
+
+    ###################################################################################
+    # Returns the entire attributes Hash.
+    # return [Hash]
+    def self.attributes
+
+      # set the default values.
+      if !defined?(@@attributes) || @@attributes.nil?
+        # set default values
+        @@attributes = {
+                        title: "Untitled",
+                        keywords: nil,
+                        description: nil,
+                        lastmod: Time.now,
+                        changefreq: "monthly",
+                        priority: "0.5",
+                        canonical: nil,
+                        canonical_host: nil,
+                        canonical_port: nil,
+                        compression: :compressed,
+                        sitemap_content: :xml,
+                        static_host: nil,
+                        static_port: nil,
+                        static_target: nil,
+                        url_format: "html",
+                        url_limit: 50000
+                        }
+      end
+
+      return @@attributes
+    end
+
+    ###################################################################################
+    # Sets the entire attributes Hash.
+    # return [Hash]
+    def self.attributes=(value)
+      @@attributes = value
+    end
+
+    ###################################################################################
+    # Returns a copy of the entire attributes Hash.
+    # return [Hash]
+    def self.copy_attributes
+      return {}.merge(self.attributes)
+    end
+
+    ###################################################################################
+    # Performs a get or set on all of the key/values contained in the attributes class variable.
+    # To get a value, simply call DuckMap::Config with the method name.
+    #
+    #    DuckMap::Config.title    # => Untitled
+    #
+    # To set a value, simply call DuckMap::Config with the method name and an assignment.
+    #
+    #    DuckMap::Config.title    # => Untitled
+    #    DuckMap::Config.title = "My App"
+    #    DuckMap::Config.title    # => My App
+    #
+    # I choose to go this route since this ONLY applies to DuckMap::Config and to reduce the amount of accessor
+    # methods needed to get/set attributes.
+    #
+    # return [Object] Value stored via key.
+    def self.method_missing(meth, *args, &block)
+      value = nil
+
+
+      if meth.to_s =~ /=$/
+        key = meth.to_s
+        key = key.slice(0, key.length - 1).to_sym
+        self.attributes[key] = args.first
+      else
+        # all tests showed that meth is a Symbol
+        value = self.attributes[meth]
+      end
+
+      return value
+    end
+
+  end
+
+  ##################################################################################
+  # A mixin the provide helper methods that gain access for configuration values from config/routes.rb.
+  module ConfigHelpers
+    extend ActiveSupport::Concern
+
+    ##################################################################################
+    # Sets the logging level.
+    #
+    #     # sets the logging level to :debug and full stack traces for exceptions.
+    #     MyApp::Application.routes.draw do
+    #       log_level :debug, full: true
+    #     end
+    #
+    # @param [Symbol] value The logger level to use.  Valid values are:
+    #                       - :debug
+    #                       - :info
+    #                       - :warn
+    #                       - :error
+    #                       - :fatal
+    #                       - :unknown
+    # @param [Hash] options Options Hash.
+    # @option options [Symbol] :full Including full: true will include full stack traces for exceptions.
+    #                          Otherwise, stack traces are stripped and attempt to only include application traces.
+    def log_level(value, options = {})
+      DuckMap::Logger.log_level = value
+      if options.has_key?(:full)
+        DuckMap.logger.full_exception = options[:full]
+      end
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def title(value)
+      Config.title = value
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def keywords(value)
+      Config.keywords = value
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def description(value)
+      Config.description = value
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def lastmod(value)
+      Config.lastmod = LastMod.to_date(value)
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def changefreq(value)
+      Config.changefreq = value
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def priority(value)
+      unless value.blank?
+        Config.priority = value.to_s
+      end
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def url_format(value)
+      Config.url_format = value
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def canonical(value)
+      Config.canonical = value
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def canonical_host(value)
+      Config.canonical_host = value
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def canonical_port(value)
+      Config.canonical_port = value
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def compression(value)
+      Config.compression = value
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def sitemap_content(value)
+      Config.sitemap_content = value
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def static_host(value)
+      Config.static_host = value
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def static_port(value)
+      Config.static_port = value
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def static_target(value)
+      Config.static_target = value
+    end
+
+    #################################################################################
+    # See {DuckMap::ConfigHelpers} Overview for details.
+    def url_limit(value)
+      Config.url_limit = value
+    end
+
+    #################################################################################
+    # See {DuckMap::SitemapObject::ClassMethods#acts_as_sitemap}
+    def acts_as_sitemap(*args)
+      Config.acts_as_sitemap(*args)
+    end
+
+    #################################################################################
+    # See {DuckMap::SitemapObject::ClassMethods#sitemap_handler}
+    def sitemap_handler(*args)
+      Config.sitemap_handler(*args)
+    end
+
+    #################################################################################
+    # See {DuckMap::SitemapObject::ClassMethods#sitemap_segments}
+    def sitemap_segments(*args)
+      Config.sitemap_segments(*args)
+    end
+
+  end
+
+end