site_map 0.3.0 → 0.3.1

data/README.rdoc

@@ -2,31 +2,84 @@
 
 == Description
 
-SiteMap provides a way to model out your site's views in a hierarchal fashion. You configure your views and then it builds a tree structure from it that is easy to lookup specific nodes and also traverse their relationships, such as parent or children.
+SiteMap provides a way to model out your site's views in a hierarchal fashion. You configure your views and then it builds a tree structure from it that is easy to lookup specific nodes and also traverse their relationships, such as parents or children.
 
 == Installation
 
-    sudo gem install site_map
+    gem install site_map
 
-== Basic Usage
+== Usage
 
-SiteMap by default looks for "config/site_map.rb" to try and load configurations from. Defining your site map is easy with a syntax similar to Rails routes:
+=== Basic Definition
 
+SiteMap provides a simple syntax for defining a site's views.
+
+    require 'site_map'
+    SiteMap.define do |map|
+      map.view :home
+      map.view :about
+      map.view :contact
+    end
+
+This defines three views home, about and contact. The +view+ method is the most basic way to configure your site map and only requires a unique index as it's first parameter. It simply creates within the site map a view node with the index provided (in this case +home+, +about+ or +contact+).
+
+=== Setting Attributes
+
+Every site map view node also has a +label+, +url+ and +visible+ attribute. The label is the name of the page the node represents and the url is how you navigate to that page. The visible attribute specifies whether this node should be shown. Using these options is simple:
+
+    require 'site_map'
     SiteMap.define do |map|
-      map.view :user
+      map.view(:home, {
+        :label => "Home :app_name",
+        :url => "'/home'"
+      })
+      map.view(:about, {
+        :url => "about_path"
+      })
+      map.view(:contact, {
+        :visible => "can_contact?"
+      })
     end
 
-This creates a single view in your map that can be found with the index :user. Finding view node's is easy as well:
+So same basic configuration, but I've added custom options for the previously mentioned attributes. Firstly, url and visible attributes are intended to be eav'd within the view space of an app. This allows you to specify very custom ways to determine a path or check if a node should be shown. Label's are not intended to be eval'd, but are dynamic in a different way, by subbing out symbol names with an options hash, again in the view space. This is explained more and used within site map's view helpers.
+
+Secondly, not every attribute has to be set. By default, a site map's visible is always +true+, and it's url is +nil+. Label also has a default, based on the index. For labels, site map will try to use a +titleize+ method on the string version of it's index. If defined, the titleized string is returned, otherwise just the string version of the index is.
 
-    SiteMap[:user]
+=== Groups and nesting
 
-If the a view node with the index :user exists in the site map, then it will return it and can be used as needed. SiteMap can also be used to define views in a resource based method. You can define a collection of view node's with the collection method:
+Site map provides other ways to define nodes and also allows nesting nodes within other nodes.
 
+    require 'site_map'
     SiteMap.define do |map|
-      map.collection :users
+      map.view :home
+      map.view :about
+      map.group :community do |community_group|
+        community_group.view :forum
+        community_group.view :blog
+      end
     end
 
-This defines a single view node with an index of :users__index. It then uses the alias method, to also allow looking up the view node with :users__new and :users_create. SiteMap also defines a member method, which creates a node with :users__show, and alias' :users__edit, :users__update and :users__destroy.
+In this definition, we are using a new method +group+. A group node is very similar to a regular view node, and is intended to group similar views. In this case, we have created a group, called community with a blog and forum view as children. A group's definition syntax is the same as a view's, but it has different defaulting logic and behavior within the site map. A group's url will default to it's first child's url, in this case the forum view's url. I'll explain the differences in how a group behaves in the looking up views and traversing the site map sections later.
+
+=== Looking up a view node
+
+Enough we defining the site map, on to actually retrieving what's been defined. Assuming the previous definition:
+
+    view_node = SiteMap[:forum]
+    view_node = SiteMap[:community] # => returns nil, can't look up group nodes
+
+Specifying the index of a node will return that view node. When you look up a group node's index, it isn't returned. Group node's are not intended to be looked up, but still exist in the relationships of a view node.
+
+=== View node relationships
+
+After looking up a view node, you can access it's relationships.
+
+  view_node = SiteMap[:forum]
+  view_node.parent                # => returns community group node
+  view_node.siblings              # => returns an array with blog view node in it, [SiteMap[:blog]]
+  view_node.parent.children       # => returns an array with blog and forum view nodes, [SiteMap[:forum], SiteMap[:blog]]
+
+Other relationship methods include +ancestors+, +self_and_siblings+ and +self_and_ancestors+.
 
 Copyright (c) 2010 John Collin Redding
 See the attached MIT License.

data/Rakefile

@@ -17,7 +17,7 @@ spec = Gem::Specification.new do |s|
   s.files            = %w(README.rdoc Rakefile) + Dir.glob("{lib}/**/*")
   # s.executables    = ['site_map']
 
-  # s.add_dependency('gem_name', '~> 0.0.1')
+  s.add_development_dependency("shoulda", [">= 2.10.2"])
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|

data/lib/site_map.rb

@@ -6,33 +6,53 @@ end
 
 module SiteMap
 
-  def self.setup(*files)
-    files = files.first if files.first.is_a?(Array)
-    files << File.join('config', 'site_map.rb') if files.empty?
-    @@map ||= SiteMap::Map.new
-    @@map.clear_nodes!
-    files.each do |file|
-      begin
-        load file
-      rescue LoadError => exception
+  DEFAULT_FILE = File.join('config', 'site_map.rb')
+
+  class << self
+    
+    def setup(*files)
+      files = files.first if files.first.is_a?(Array)
+      files << DEFAULT_FILE if files.empty?
+      self.logger = Rails.logger if defined?(Rails)
+      @@map ||= SiteMap::Map.new
+      @@map.clear_nodes!
+      files.each do |file|
+        begin
+          load file
+        rescue LoadError => exception
+          self.logger.info("SiteMap config file: #{file} could not be loaded.") unless file == DEFAULT_FILE
+        end
       end
     end
-  end
 
-  def self.[](view_node_index)
-    self.map.find(view_node_index.to_sym)
-  end
+    def [](view_node_index)
+      self.map.find(view_node_index.to_sym)
+    end
 
-  def self.view_nodes
-    self.map.view_nodes
-  end
+    def view_nodes
+      self.map.view_nodes
+    end
+    alias_method :views, :view_nodes
+    
+    def visible_views
+      self.map.visible_views
+    end
 
-  def self.map
-    @@map
-  end
+    def map
+      @@map
+    end
+
+    def define(&block)
+      yield @@map
+    end
+
+    def logger
+      @@logger ||= Logger.new(STDOUT)
+    end
+    def logger=(new_logger)
+      @@logger = new_logger
+    end
 
-  def self.define(&block)
-    yield @@map
   end
 
 end

data/lib/site_map/exceptions.rb

@@ -1,6 +1,8 @@
 module SiteMap
   module Exceptions
 
+    # This is an exception raised when an alias mapping is used and the node to be aliased does not
+    # exist
     class NonExistantViewNode < StandardError
     end
 

data/lib/site_map/helpers/mapping.rb

@@ -31,9 +31,9 @@ module SiteMap
       end
       def collection_view(resource, action, options={})
         options.merge!({:resource => resource.to_sym, :action => action.to_sym})
-        view_node = self.add_node([resource, action].join('__').to_sym, :collection, options)
+        view_node = self.add_node(self.index_for(resource, action), :collection, options)
         (DEFAULT_ALIAS[action] || []).each do |action|
-          view_node.alias([resource, action].join('__').to_sym, view_node.index)
+          view_node.alias(self.index_for(resource, action), view_node.index)
         end
         block_given? ? (yield view_node) : view_node
       end
@@ -43,15 +43,19 @@ module SiteMap
       end
       def member_view(resource, action, options={})
         options.merge!({:resource => resource.to_sym, :action => action.to_sym})
-        view_node = self.add_node([resource, action].join('__').to_sym, :member, options)
+        view_node = self.add_node(self.index_for(resource, action), :member, options)
         (DEFAULT_ALIAS[action] || []).each do |action|
-          view_node.alias([resource, action].join('__').to_sym, view_node.index)
+          view_node.alias(self.index_for(resource, action), view_node.index)
         end
         block_given? ? (yield view_node) : view_node
       end
 
       protected
 
+      def index_for(resource, action)
+        [resource, action].join('__').to_sym
+      end
+
       def add_node(new_index, node_type, options={})
         view_node = SiteMap::ViewNode.new(*view_node_params(new_index, node_type, options))
         self.add_to_children(view_node)

data/lib/site_map/map.rb

@@ -5,6 +5,7 @@ module SiteMap
     include SiteMap::Helpers::Mapping
     ATTRIBUTES = [:view_nodes, :index_of_nodes]
     ATTRIBUTES.each{|attribute| attr_reader attribute }
+    alias_method :views, :view_nodes
 
     def initialize
       self.clear_nodes!
@@ -34,6 +35,12 @@ module SiteMap
     def inspect
       "#<#{self.class}>"
     end
+    
+    def visible_views
+      @view_nodes.select do |view|
+        view.visible?
+      end
+    end
 
     protected
 

data/lib/site_map/tasks/view_nodes.rake

@@ -2,7 +2,7 @@ namespace :site_map do
 
   desc 'Print out all defined view nodes based on the current SiteMap configuration'
   task :nodes => :environment do
-    index_length = SiteMap.map.index_of_nodes.collect{|key, value| key.inspect.length}.max
+    index_length = SiteMap.map.index_of_nodes.collect{|key, value| key.inspect.length}.max + 1
     index_length += (SiteMap.map.index_of_nodes.collect{|key, value| value.ancestors.size}.max * 2)
     label_length = SiteMap.map.index_of_nodes.collect{|key, value| value.label.inspect.length}.max
     url_length = SiteMap.map.index_of_nodes.collect{|key, value| value.url.inspect.length}.max

data/lib/site_map/version.rb

@@ -3,7 +3,7 @@ module SiteMap
 
     MAJOR = 0
     MINOR = 3
-    TINY  = 0
+    TINY  = 1
 
     def self.to_s # :nodoc:
       [MAJOR, MINOR, TINY].join('.')

data/lib/site_map/view_helpers.rb

@@ -6,7 +6,7 @@ module SiteMap
       {}
     end
 
-    # subbing hash options into view node label code thanks to kelredd-useful
+    # subbing hash options into view node label, code thanks to kelredd-useful
     def view_node_label(view_node)
       label_string = view_node.label
       view_node_label_options.each do |label_key, value|
@@ -18,9 +18,23 @@ module SiteMap
       eval(view_node.url)
     end
     def view_node_visible(view_node)
-      eval(view_node.visible)
+      eval(view_node.visible.to_s)
     end
     alias :view_node_visible? :view_node_visible
 
+    def display_title(options = {})
+      options = { :connector => " > " }.merge(options)
+      [ view_node_label(@view_node.parent),
+        view_node_label(@view_node)
+      ].join(options[:connector])
+    end
+    def display_crumbs
+
+    end
+    def display_menu
+
+    end
+
+
   end
 end

data/lib/site_map/view_node.rb

@@ -46,8 +46,15 @@ module SiteMap
       @url ? @url : self.default_url
     end
     def visible
-      @visible ? @visible : 'true'
+      if @visible.nil?
+        true
+      elsif @visible.kind_of?(::String)
+        @visible
+      else
+        !!@visible
+      end
     end
+    alias_method :visible?, :visible
 
     def aliases
       @aliases ||= self.map.index_of_nodes.collect do |key, view_node|
@@ -102,7 +109,7 @@ module SiteMap
       when :member
         self.resource_label(self.single_string)
       else
-        @index.to_s
+        @index.to_s.titleize
       end
     end
     def default_url
@@ -114,7 +121,7 @@ module SiteMap
       when :member
         self.resource_url
       else
-        @url
+        "/#{@index.to_s.underscore.dasherize}"
       end
     end
 
@@ -123,40 +130,38 @@ module SiteMap
       template.gsub(':action', self.title_string(@action.to_s)).gsub(':resource', resource_text)
     end
     def resource_url
+      action_str = unless (action_template = URL_ACTION_TEMPLATES[@action])
+        @action.to_s
+      end
+      template = (action_template || BASE_URL_TEMPLATE[@node_type])
       resource_text = if @node_type == :collection
-        action_str = unless URL_ACTION_TEMPLATES[@action]
-          @action.to_s
-        end
         parent_str = if self.parent && [:member, :collection].include?(self.parent.node_type)
           self.single_string(self.parent.resource)
         end
-        template = (URL_ACTION_TEMPLATES[@action] || BASE_URL_TEMPLATE[@node_type])
         resourced_url = [action_str, parent_str, template].flatten.compact.join('_')
         resourced_url = [resourced_url, ("(@#{parent_str})" if parent_str)].compact.join
         resourced_url.gsub(':resource', (@action == :new ? self.single_string : @resource.to_s))
       else
-        action_str = unless URL_ACTION_TEMPLATES[@action]
-          @action.to_s
-        end
-        template = (URL_ACTION_TEMPLATES[@action] || BASE_URL_TEMPLATE[@node_type])
         resourced_url = [action_str, template].flatten.compact.join('_')
         resourced_url.gsub(':resource', self.single_string)
       end
     end
 
-    def single_string(string = nil)
-      string ||= @resource
-      string.to_s.respond_to?(:singularize) ? string.to_s.singularize : string.to_s
+    def single_string(string = @resource)
+      self.format_string(string, :singularize)
     end
-    def title_string(string = nil)
-      string ||= @resource
-      string.to_s.respond_to?(:titleize) ? string.to_s.titleize : string.to_s
+    def title_string(string = @resource)
+      self.format_string(string, :titleize)
     end
 
     def view_node_params(new_index, node_type, options)
       [new_index, self.map, node_type, options.merge(:parent => self)]
     end
 
+    def format_string(string, format)
+      (string = string.to_s).respond_to?(format) ? string.send(format) : string
+    end
+
   end
 
 end

metadata

@@ -1,7 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: site_map
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  prerelease: false
+  segments: 
+  - 0
+  - 3
+  - 1
+  version: 0.3.1
 platform: ruby
 authors: 
 - Collin Redding
@@ -9,10 +14,23 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-19 00:00:00 -06:00
+date: 2010-04-16 00:00:00 -05:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 10
+        - 2
+        version: 2.10.2
+  type: :development
+  version_requirements: *id001
 description: 
 email: TempestTTU@gmail.com
 executables: []
@@ -49,18 +67,20 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: SiteMap provides a way to model out your site's views in a hierarchal fashion.