xebec 1.0.0

data/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+*/.DS_Store
+doc/rdoc
+.yardoc
+pkg

data/README.md

@@ -0,0 +1,105 @@
+## Xebec ##
+
+Xebec is a Gem and Rails plugin that helps you build navigation for your website.
+Tired of building custom navigation code for each site?
+
+Have you seen Ryan Heath's [Navigation Helper](http://github.com/rpheath/navigation_helper)? It's very usable, but it only does one navigation bar. I often have sites where there are many, e.g.
+
+    +-----------------------------------------------------------+
+    | MyApp                           | Home | Sign Out | FAQ | | # "site" nav bar
+    |===========================================================|
+    | | *Projects* | Friends |                                  | # "area" nav bar
+    |===========================================================|
+    | | Project Overview | *Budget* | History |                 | # "tabs" nav bar
+    |                                                           |
+    |                                                           |
+    | Project "Foo" Budget                                      |
+    | ====================                                      |
+    | ...                                                       |
+    +-----------------------------------------------------------+
+
+Each navigation bar has dynamic content. The *site* one will often have a "Sign In" and "Sign Up" link when no user is signed-in, but will have a "Sign Out" link otherwise. The *area* bar will often change based on the permissions/roles of the person signed in. The *tabs* bar will certainly depend on the area and the permissions/roles, and possibly also the features of the item being viewed. (Do all projects have budgets? If the "Budget" link goes to "./budget" then it doesn't have to be generated for each project, but it might not be so easy in other cases.)
+
+(Of course, these *site*, *area*, and *tabs* aren't the only possibilities, merely a common pattern.)
+
+Another common pattern is to differentiate the currently-selected navigation item in each applicable bar. (The asterisks in the above display.) In the case above, it probably makes sense to leave the "Projects" *area* item as a link when browsing a specific project so the user may easily return to the projects listing page. On the other hand, the currently active *tabs* item probably doesn't need to be a link. Clicking that would be the equivalent of a refresh.
+
+Thus, Xebec.
+
+### Installing Xebec in a Rails Application ###
+
+#### Add the Gem Dependency ####
+
+If you're using Bundler, add this to your `Gemfile`:
+
+    gem "xebec"
+    
+If not, add this to `config/environment.rb`:
+
+    config.gem 'xebec'
+
+#### Add the Helpers ####
+
+Add this to your `ApplicationController`:
+
+    class ApplicationController < ActionController::Base
+      helper Xebec::NavBarHelper
+    end
+
+### Rendering a Navigation Bar ###
+
+To render a navigation bar, render `nav_bar` in your view, passing the name of the bar:
+
+    <%= nav_bar :site %>
+    
+If you want to render the navigation bar only if it contains any items, use `nav_bar_unless_empty`:
+
+    <%= nav_bar_unless_empty :area >
+    
+If you only have one navigation bar on your site, you can leave off the name, like so:
+
+    <%= nav_bar %>
+    
+Xebec will assign this navigation bar the name `:default` in case you need to refer to it elsewhere, but you probably won't.
+
+### Populating a Navigation Bar ###
+
+To add items to your navigation bar in a view, call `nav_bar` with a block containing any number of `nav_item` calls:
+
+    <%
+      nav_bar :site do |nb|
+        nb.nav_item :home,     root_path
+        nb.nav_item :sign_in   unless signed_in? # assumes sign_in_path
+      end
+    %>
+    
+### Highlighting the "Current" Element of a Navigation Bar ###
+
+The `nav_bar` helper method will add the "current" class to the currently-selected item of each navigation bar. Highlighting the item requires just some basic CSS:
+
+    ul.navbar { color: green; }
+    ul.navbar li.current { color: purple; }
+    
+Each rendered navigation bar will include its name as a CSS class if you want to style them differently:
+
+    ul.navbar.site { color: green; }
+    ul.navbar.area { color: white; background-color: green; }
+    
+### Setting the "Current" Element of a Navigation Bar ###
+
+A navigation bar will automatically set an item as selected if its URL matches the current page URL. That will work for pages like "FAQ" above, but what if you want "Projects" to be highlighted not only for the projects list page but also for any page in the "Projects" area, such as an individual project's "Budget" tab? You can manually set the *current* item in a navigation bar like so:
+
+    <% nav_bar(:area).current = :projects %>
+
+### Example Application ###
+
+To see the full range of features that Xebec supports, including internationalization and `before_filter`s for your controllers, check out the example application in `doc/example_app/`.
+
+## What's a *xebec*? ##
+
+Apple's dictionary provides the following entry:
+
+> **xe‧bec** |ˈzēˌbek| (also **ze‧bec**)
+noun historical
+a small three-masted Mediterranean sailing ship with lateen and sometimes square sails.
+ORIGIN mid 18th cent.: alteration (influenced by Spanish ***xabeque***) of French ***chebec***, via Italian from Arabic ***šabbāk***.

data/Rakefile

@@ -0,0 +1,6 @@
+require 'rake'
+
+Dir['developer_tasks/*.rake'].each { |f| load(f) }
+
+desc "Default: run all tests"
+task :default => ['test']

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/developer_tasks/doc.rake

@@ -0,0 +1,29 @@
+desc "Generate RDoc"
+task :doc => ['doc:generate']
+
+namespace :doc do
+  project_root = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+  doc_destination = File.join(project_root, 'doc', 'rdoc')
+  
+  begin
+    require 'yard'
+    require 'yard/rake/yardoc_task'
+
+    YARD::Rake::YardocTask.new(:generate) do |yt|
+      yt.files   = Dir.glob(File.join(project_root, 'lib', '**', '*.rb')) + 
+                   [ File.join(project_root, 'README.md') ]
+      yt.options = ['--output-dir', doc_destination, '--readme', 'README.md']
+    end
+  rescue LoadError
+    desc "Generate YARD Documentation"
+    task :generate do
+      abort "Please install the YARD gem to generate rdoc."
+    end
+  end
+
+  desc "Remove generated documenation"
+  task :clean do
+    rm_r doc_dir if File.exists?(doc_destination)
+  end
+  
+end

data/developer_tasks/gem.rake

@@ -0,0 +1,34 @@
+namespace :gem do
+  begin
+    require 'jeweler'
+    Jeweler::Tasks.new do |gemspec|
+      gemspec.name = "xebec"
+      gemspec.summary = "Navigation helpers"
+      gemspec.description = "Helpers for generating navigation bars"
+      gemspec.email = "james.a.rosen@gmail.com"
+      gemspec.homepage = "http://github.com/jamesarosen/xebec"
+      gemspec.authors = ["James Rosen"]
+      gemspec.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Xebec Documentation", "--charset", "utf-8"]
+      gemspec.platform = Gem::Platform::RUBY
+      gemspec.add_development_dependency 'shoulda', '~> 2.10.3'
+      gemspec.add_development_dependency 'mocha', '~> 0.9.8'
+      gemspec.add_development_dependency 'redgreen', '~> 1.2.2'
+    end
+  rescue LoadError
+    puts "Jeweler not available. Install it with [sudo] gem install jeweler -s http://gemscutter.org"
+  end
+  
+  task :push do
+    command = ('gem push')
+    command << " -p $#{ENV['http_proxy']}" if ENV['http_proxy']
+    command << " #{latest_gem}"
+    puts "Pushing gem..."
+    IO.popen(command) { |io| io.each { |line| puts '  ' + line } }
+  end
+  
+  def latest_gem
+    result = File.expand_path(Dir.glob(File.join(File.dirname(__FILE__), '..', 'pkg', '*.gem')).sort.last)
+    abort "No gems found in pkg/. Did you run gem:build?" if result.nil?
+    result
+  end
+end

data/developer_tasks/test.rake

@@ -0,0 +1,20 @@
+require 'rake/testtask'
+
+project_root = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+lib_directories = FileList.new do |fl|
+  fl.include "#{project_root}/lib"
+  fl.include "#{project_root}/test/lib"
+end
+ 
+test_files = FileList.new do |fl|
+  fl.include "#{project_root}/test/**/*_test.rb"
+  fl.exclude "#{project_root}/test/test_helper.rb"
+  fl.exclude "#{project_root}/test/lib/**/*.rb"
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs = lib_directories
+  t.test_files = test_files
+  t.verbose = true
+end

data/doc/example_app/Gemfile

@@ -0,0 +1,2 @@
+source :gemcutter
+gem 'xebec'

data/doc/example_app/README.md

@@ -0,0 +1,9 @@
+This is an example Rails application that shows off the features of Xebec. Things to check out:
+
+* declaring the Xebec dependency in your [Gemfile](./Gemfile)
+* adding the Xebec helpers in your [ApplicationController](./app/controllers/application_controller.rb)
+* how to render navigation bars in your [layout](./app/views/layouts/application.html.erb)
+* how to declare and populate a navigation bar in a [view](./app/views/layouts/_site_nav_bar.html.erb)
+* how to declare and populate a navigation bar in a [controller](./app/controllers/application_controller.rb)
+* how to declare and populate a navigation bar in an [action](./app/controllers/projects_controller.rb)
+* how to change the text that is displayed for a navigation item using [i18n](./config/locales/en.yml)

data/doc/example_app/app/controllers/application_controller.rb

@@ -0,0 +1,22 @@
+class ApplicationController < ActionController::Base
+  
+  # Add Xebec's view helper methods:
+  helper Xebec::NavBarHelper
+  
+  # If you prefer to declare your navigation in your
+  # controllers, start by including Xebec's controller support:
+  include Xebec::ControllerSupport
+  
+  # then declare and populate some navigation bars:
+  nav_bar :area do |nb|
+    nb.nav_item :projects         # assumes projects_path
+  end
+  
+  nav_bar :footer do |nb|
+    nb.nav_item :about_us,        page_path(:about_us)
+    nb.nav_item :faq,             page_path(:faq)
+    nb.nav_item :feedback,        page_path(:feedback)
+    nb.nav_item :privacy_policy,  page_path(:privacy_policy)
+  end
+  
+end

data/doc/example_app/app/controllers/pages_controller.rb

@@ -0,0 +1,7 @@
+class PagesController < ApplicationController
+
+  def show
+    render :action => params[:page]
+  end
+  
+end

data/doc/example_app/app/controllers/projects_controller.rb

@@ -0,0 +1,49 @@
+class ProjectsController < ApplicationController
+  
+  # set the selected item for the :area navigation bar
+  # for all actions in this controller:
+  nav_bar :area { |nb| nb.selected = :projects }
+  
+  def index
+    params[:sort] ||= 'recent'
+    # set up tabs for the project-list view:
+    nav_bar(:tabs) do |nb|
+      nb.nav_item :by_alpha, projects_path(:sort => 'by_alpha')
+      nb.nav_item :recent,   projects_path(:sort => 'recent')
+      nb.selected = params[:sort]
+    end
+    @projects = Project.ordered_by(params[:sort])
+  end
+  
+  def show(selected_tab = :overview)
+    @project = Project.find(params[:id])
+    prepare_project_tabs selected_tab
+  end
+  
+  def budget
+    show :budget
+  end
+  
+  def history
+    show :history
+  end
+  
+  def edit
+    show :edit
+  end
+  
+  protected
+  
+  # Extract navigation bar setup that is common to
+  # multiple methods:
+  def prepare_project_tabs(selected)
+     nav_bar(:tabs) do |nb|
+      nb.nav_item :overview, project_path(@project)
+      nb.nav_item :budget,   budget_project_path(@project)
+      nb.nav_item :history,  history_project_path(@project)
+      nb.nav_item :edit,     edit_project_path(@project)
+      nb.selected = selected
+    end
+  end
+  
+end

data/doc/example_app/app/views/layouts/_site_nav_bar.html.erb

@@ -0,0 +1,16 @@
+<%= 
+  # If you want to keep your navigation code in your views, you might
+  # want to use partials like this one. Notice that this tag is an
+  # "output" tag (%= as opposed to %). That means that the
+  # navigation bar will be rendered as an HTML list here. If you want to
+  # modify a navigation bar in a view without rendering it, use a
+  # non-outputting tag.
+  nav_bar :site do |nb|
+    nb.nav_item :home,     root_path
+    nb.nav_item :sign_in                                 unless signed_in?
+    nb.nav_item :sign_up                                 unless signed_in?
+    nb.nav_item :sign_out                                if signed_in?
+    nb.nav_item :profile,  edit_user_path(current_user)  if signed_in?
+    nb.nav_item :company,  'http://example.com'
+  end
+%>

data/doc/example_app/app/views/layouts/application.html.erb

@@ -0,0 +1,15 @@
+<body>
+  <div id='header'>
+    <h1>My Site</h1>
+    <%= render :partial => '/layouts/site_nav_bar' %>
+  </div>
+  <%= nav_bar_unless_empty :area %>
+  <div id='content'>
+    <%= nav_bar_unless_empty :tabs %>
+    <%= yield %>
+  </div>
+  <div id='footer'>
+    &copy; 2293 My Happy Company
+    <%= nav_bar :footer %>
+  </div>
+</body>

data/doc/example_app/app/views/pages/about_us.html.erb

@@ -0,0 +1 @@
+<h2>About Us</h2>

data/doc/example_app/app/views/pages/faq.html.erb

@@ -0,0 +1 @@
+<h2>Frequently Asked Questions</h2>

data/doc/example_app/app/views/pages/feedback.html.erb

@@ -0,0 +1 @@
+<h2>Feedback</h2>

data/doc/example_app/app/views/pages/home.html.erb

@@ -0,0 +1 @@
+<h2>Welcome!</h2>

data/doc/example_app/app/views/pages/privacy_policy.html.erb

@@ -0,0 +1 @@
+<h2>Privacy Policy</h2>

data/doc/example_app/app/views/projects/budget.html.erb

@@ -0,0 +1 @@
+<h2>Project Budget</h2>

data/doc/example_app/app/views/projects/edit.html.erb

@@ -0,0 +1 @@
+<h2>Edit Project</h2>

data/doc/example_app/app/views/projects/history.html.erb

@@ -0,0 +1 @@
+<h2>Project History</h2>

data/doc/example_app/app/views/projects/index.html.erb

@@ -0,0 +1 @@
+<h2>Projects</h2>

data/doc/example_app/app/views/projects/show.html.erb

@@ -0,0 +1 @@
+<h2>Project Overview</h2>

data/doc/example_app/config/locales/en.yml

@@ -0,0 +1,7 @@
+en:
+  navbar:
+    site:
+      profile: My Profile
+      company: Spiffy Labs
+    footer:
+      faq: <abbr title="Frequently Asked Questions">FAQ</abbr>

data/doc/example_app/config/routes.rb

@@ -0,0 +1,10 @@
+ExampleApp::Application.routes.draw do |map|
+  root 'pages#show', :page => :home
+  resources :projects do
+    member do
+      get :budget
+      get :history
+    end
+  end
+  get '/pages/:page' => 'pages#show', :as => :page
+end

data/init.rb

@@ -0,0 +1,7 @@
+# Rails uses rails/init.rb, not this file. Put any Rails-specific
+# initialization in that file.
+
+lib_path = File.expand_path(File.join(File.dirname(__FILE__), 'lib'))
+$: << lib_path unless $:.include?(lib_path)
+
+require 'xebec'

data/lib/xebec.rb

@@ -0,0 +1,6 @@
+module Xebec
+  
+  autoload :NavBarHelper,       'xebec/nav_bar_helper'
+  autoload :ControllerSupport,  'xebec/controller_support'
+  
+end

data/lib/xebec/controller_support.rb

@@ -0,0 +1,77 @@
+require 'xebec/has_nav_bars'
+
+module Xebec
+  
+  # Include this module in Rails controllers if you want to declare
+  # navigation bars in your controllers instead of or in addition to
+  # in your views.
+  module ControllerSupport
+    
+    def self.included(base)
+      base.extend Xebec::ControllerSupport::ClassMethods
+      base.send :include, Xebec::ControllerSupport::InstanceMethods
+      base.send :include, Xebec::HasNavBars
+    end
+    
+    module ClassMethods
+      
+      # Declare and populate a navigation bar. This method
+      # is a shorthand for creating a +before_filter+ that looks
+      # up and populates a navigation bar.
+      #
+      # @param [String, Symbol] name the name of the navigation bar;
+      #                         optional
+      #
+      # @param [Hash] options the options for the +before_filter+;
+      #                       optional.
+      #
+      # @yield [Xebec::NavBar] nav_bar the navigation bar -- NB: does
+      #                        NOT yield at call-time, but at action
+      #                        run-time, as a before filter. The block
+      #                        is evaluated in the scope of the controller
+      #                        instance.
+      #
+      # @return [nil]
+      #
+      # @example
+      #   nav_bar :tabs, :only => [:index, :sent, :received, :new] do |nb|
+      #     nb.nav_item :received, received_messages_path(current_user)
+      #     nb.nav_item :sent,     sent_messages_path(current_user)
+      #     nb.nav_item :new,      new_message_path
+      #   end
+      def nav_bar(name = Xebec::NavBar::DEFAULT_NAME, options = {}, &block)
+        append_before_filter options do
+          nav_bar name, &block
+        end
+        nil
+      end
+      
+    end
+    
+    module InstanceMethods
+      
+      # Declare and populate a navigation bar.
+      #
+      # @param [String, Symbol] name the name of the navigation bar
+      #
+      # @yield [Xebec::NavBar] nav_bar the navigation bar. The block
+      #                        is evaluated in the scope of the
+      #                        controller instance.
+      # 
+      # @return [Xebec::NavBar]
+      #
+      # @example
+      #   nav_bar :tabs do |nb|
+      #     nb.nav_item :overview, @project
+      #     nb.nav_item :budget,   project_budget_path(@project)
+      #     nb.nav_item :edit,     edit_project_path(@project)
+      #   end
+      def nav_bar(name = Xebec::NavBar::DEFAULT_NAME, &block)
+        look_up_nav_bar_and_eval name, &block
+      end
+      
+    end
+    
+  end
+  
+end

data/lib/xebec/has_nav_bars.rb

@@ -0,0 +1,31 @@
+require 'xebec/nav_bar'
+
+module Xebec
+  
+  # A supporting mixin for NavBarHelper and ControllerSupport.
+  # Looks up navigation bars by name.
+  module HasNavBars #:nodoc:
+    
+    protected
+    
+    # Looks up the named nav bar, creates it if it
+    # doesn't exist, and evaluates the the block, if
+    # given, in the scope of +self+, yielding the nav bar.
+    def look_up_nav_bar_and_eval(name = nil, &block)
+      name ||= Xebec::NavBar::DEFAULT_NAME
+      look_up_nav_bar(name).tap do |bar|
+        block.bind(self).call(bar) if block_given?
+      end
+    end
+    
+    def look_up_nav_bar(name)
+      nav_bars[name] ||= NavBar.new(name)
+    end
+    
+    def nav_bars
+      @nav_bars ||= {}
+    end
+    
+  end
+  
+end

data/lib/xebec/nav_bar.rb

@@ -0,0 +1,50 @@
+require 'xebec/nav_item'
+
+module Xebec
+  
+  class NavBar
+    
+    DEFAULT_NAME = :default
+    
+    attr_reader :name
+    attr_reader :items
+    attr_accessor :current
+    
+    # Create a new NavBar object.
+    #
+    # @param [String] name the name of the navigation bar; defaults to :default
+    def initialize(name = nil)
+      @name = name || DEFAULT_NAME
+      @items = []
+      @current = nil
+    end
+    
+    # Add a navigation item to this bar.
+    #
+    # @param [String, Symbol] name the name of the item
+    # @param [String, Proc] href the URL of the item; optional
+    #
+    # To customize the link text, set the internationalization key
+    # <tt>navbar.{{nav bar name}}.{{nav item name}}</tt>.
+    #
+    # @see Xebec::NavBarHelper#nav_bar
+    # @see Xebec::NavBarProxy#to_s
+    def nav_item(name, href = nil)
+      items << Xebec::NavItem.new(name, href)
+    end
+    
+    def empty?
+      items.empty?
+    end
+    
+    def to_s
+      "<NavBar #{name}>"
+    end
+    
+    def inspect
+      to_s
+    end
+    
+  end
+  
+end

data/lib/xebec/nav_bar_helper.rb

@@ -0,0 +1,61 @@
+require 'xebec/nav_bar'
+require 'xebec/nav_bar_proxy'
+require 'xebec/has_nav_bars'
+
+module Xebec
+  
+  module NavBarHelper
+    
+    include Xebec::HasNavBars
+    
+    # If called in an output expression ("<%= navbar %>" in ERB
+    # or "=navbar" in HAML), renders the navigation bar.
+    #
+    # @example
+    #   <%= navbar :tabs%>
+    #   # => <ul class="navbar tabs">...</ul>
+    #
+    # @see Xebec::NavBarProxy#to_s
+    # 
+    # If called with a block, yields the underlying NavBar for
+    # modification.
+    #
+    # @example
+    #   <% navbar do |nb|
+    #     nb.nav_item :home
+    #     nb.nav_item :faq, pages_path(:page => :faq)
+    #   end %>
+    #
+    # @see Xebec::NavBar#nav_item
+    # @see Xebec::HasNavBars#nav_bar
+    #
+    # @return [Xebec::NavBarProxy]
+    def nav_bar(name = nil, &block)
+      look_up_nav_bar_and_eval name, &block
+    end
+    
+    # Renders a navigation bar if and only if it contains any
+    # navigation items. Unlike +nav_bar+, this method does not
+    # accept a block.
+    #
+    # @return [String, Xebec::NavBarProxy]
+    def nav_bar_unless_empty(name = nil)
+      bar = look_up_nav_bar name
+      bar.empty? ? '' : bar
+    end
+    
+    protected
+    
+    # Override HasNavBars#look_up_nav_bar to replace with a
+    # proxy if necessary.
+    def look_up_nav_bar(name)
+      bar = super(name)
+      if bar.kind_of?(Xebec::NavBar)
+        bar = nav_bars[bar.name] = NavBarProxy.new(bar, self)
+      end
+      bar
+    end
+    
+  end
+  
+end

data/lib/xebec/nav_bar_proxy.rb

@@ -0,0 +1,88 @@
+require 'xebec/nav_bar'
+
+module Xebec
+  
+  # A proxy for a Xebec::NavBar that knows how to turn the NavBar
+  # into an HTML list using ActionView helper methods.
+  class NavBarProxy
+    
+    # Create a new NavBar proxy object. The proxy will pass all
+    # methods on to the NavBar except for +to_s+, which will 
+    # render the NavBar as an HTML list.
+    #
+    # @param [Xebec::NavBar] bar the navigation bar to proxy
+    # @param [#tag AND #content_tag AND #link_to] helper the ActionView helper
+    def initialize(bar, helper)
+      raise ArgumentError.new("#{bar || '<nil>'} is not a NavBar") unless bar.kind_of?(NavBar)
+      raise ArgumentError.new("#{helper || '<nil>'} does not seem to be a view helper") unless
+        helper.respond_to?(:content_tag) && helper.respond_to?(:link_to_unless_current)
+      @bar, @helper = bar, helper
+    end
+    
+    # @return [String] the proxied navigation bar as an HTML list.
+    #
+    # The HREF for each navigation item is generated as follows:
+    #
+    # * if the item was declared with a link
+    #   (e.g. <tt>nav_item :faq, page_path(:page => :faq)</tt>),
+    #   use that link
+    # * else, try to use the route named after the navigation item
+    #   (e.g. <tt>nav_item :home</tt> uses <tt>home_path</tt>)
+    #
+    # The link text for each navigation is generated as follows:
+    #
+    # * if the internationalization key
+    #   <tt>navbar.{{nav bar name}}.{{nav item name}}</tt> is
+    #   defined, use that value
+    # * else, use <tt>nav_item.name.titleize</tt>
+    def to_s
+      klass = "navbar #{bar.name}"
+      if bar.empty?
+        helper.tag(:ul, { :class => klass }, false)
+      else
+        helper.content_tag :ul, { :class => klass } do
+          bar.items.map do |item|
+            render_nav_item item
+          end
+        end
+      end
+    end
+    
+    def respond_to?(sym)
+      return true if bar.respond_to?(sym)
+      super
+    end
+    
+    def method_missing(sym, *args, &block)
+      return bar.send(sym, *args, &block) if bar.respond_to?(sym)
+      super
+    end
+    
+    protected
+    
+    attr_reader :bar, :helper
+    
+    def render_nav_item(item)
+      text = text_for_nav_item item
+      href = href_for_nav_item item
+      klass = is_current_nav_item?(item, href) ? 'current' : ''
+      helper.content_tag :li, :class => klass do
+        helper.link_to_unless_current text, href
+      end
+    end
+    
+    def text_for_nav_item(item)
+      I18n.t "navbar.#{bar.name}.#{item.name}", :default => item.name.to_s.titleize
+    end
+    
+    def href_for_nav_item(item)
+      item.href or helper.send("#{item.name}_path")
+    end
+    
+    def is_current_nav_item?(item, href)
+      bar.current == item.name || bar.current.blank? && helper.current_page?(href)
+    end
+    
+  end
+  
+end

data/lib/xebec/nav_item.rb

@@ -0,0 +1,21 @@
+module Xebec
+  
+  class NavItem
+    
+    attr_reader :name, :href
+    
+    # Create a new navigation item.
+    #
+    # @param [String, Symbol] name the name of the item
+    # @param [String, Hash, ActiveRecord::Base] href whither the navigation item links;
+    #         defaults to the named route, "#{name}_path"
+    #
+    # @see ActionView::Helpers::UrlHelper#url_for
+    def initialize(name, href = nil)
+      raise ArgumentError.new("#{name || '<nil>'} is not a valid name for a navigation item") if name.blank?
+      @name, @href = name, href
+    end
+    
+  end
+  
+end

data/rails/init.rb

@@ -0,0 +1,3 @@
+load File.join(File.dirname(__FILE__), '..', 'init.rb')
+
+# do any Rails-specific initialization here:

data/tasks/README.md

@@ -0,0 +1,3 @@
+This directory holds tasks that users of the gem will use. If a user adds this gem to a Rails project, Rails will automatically load all tasks in this directory.
+
+Tasks for the development of this gem go in the `developer_tasks` (a sibling directory to this one).

data/test/controller_support_test.rb

@@ -0,0 +1,47 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+require 'xebec'
+
+class ControllerSupportTest < Test::Unit::TestCase
+  
+  def setup
+    @controller_class = Class.new(ActionController::Base).tap do |c|
+      c.instance_eval do
+        include Xebec::ControllerSupport
+        def public_nav_bar(*args, &block)
+          nav_bar(*args, &block)
+        end
+      end
+    end
+    @controller = @controller_class.new
+  end
+  
+  def call_before_filters
+    @controller_class.before_filters.each do |filter|
+      filter.bind(@controller).call
+    end
+  end
+  
+  context 'ControllerSupport::ClassMethods#nav_bar' do
+    
+    should 'append a before_filter that looks up the named navigation bar' do
+      @controller_class.public_nav_bar :turtles
+      @controller.expects(:nav_bar).with(:turtles)
+      call_before_filters
+    end
+    
+    should 'append a before_filter with the given options' do
+      options = { :only => :show }
+      @controller_class.expects(:append_before_filter).with(options)
+      @controller_class.public_nav_bar :foo, options
+    end
+  
+    should 'append a before_filter that passes the given block to the named nav bar instance' do
+      @controller_class.public_nav_bar(:baz) { |nb| nb.nav_item :help }
+      bar = @controller.nav_bar :baz
+      bar.expects(:nav_item).with(:help)
+      call_before_filters
+    end
+    
+  end
+  
+end

data/test/nav_bar_helper_test.rb

@@ -0,0 +1,62 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+require 'xebec'
+
+class NavBarHelperTest < Test::Unit::TestCase
+  
+  context 'NavBarHelper#nav_bar' do
+    
+    setup do
+      @helper = new_nav_bar_helper
+    end
+    
+    should 'return a NavBar proxy' do
+      assert @helper.nav_bar.kind_of?(Xebec::NavBarProxy)
+    end
+    
+    should 'return a NavBar with the given name' do
+      assert_equal :snacks, @helper.nav_bar(:snacks).name
+    end
+    
+    should 'return the same NavBar for repeated calls with the same name' do
+      snacks = @helper.nav_bar(:snacks)
+      assert_equal snacks, @helper.nav_bar(:snacks)
+    end
+    
+    should "evaluate a block in the helper's scope" do
+      @helper.expects(:zoink!)
+      @helper.nav_bar do
+        zoink!
+      end
+    end
+    
+    should "yield the NavBar proxy to the given block" do
+      bar = @helper.nav_bar
+      bar.expects :zoink!
+      @helper.nav_bar do |nb|
+        nb.zoink!
+      end
+    end
+    
+  end
+  
+  context 'NavBarHelper#nav_bar_unless_empty' do
+    setup do
+      @helper = new_nav_bar_helper
+      @bar = @helper.nav_bar(:pets)
+    end
+    
+    context 'with an empty navigation bar' do
+      should 'return an empty String' do
+        assert @helper.nav_bar_unless_empty(:pets).blank?
+      end
+    end
+    
+    context 'with a non-empty navigation bar' do
+      setup { @bar.nav_item :cats, '/cats' }
+      should 'return a navigation bar' do
+        assert !@helper.nav_bar_unless_empty(:pets).blank?
+      end
+    end
+  end
+  
+end

data/test/nav_bar_proxy_test.rb

@@ -0,0 +1,136 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+require 'xebec'
+
+class NavBarProxyTest < Test::Unit::TestCase
+  
+  context 'creating a NavBar proxy' do
+    should 'require a NavBar' do
+      assert_raises(ArgumentError) do
+        Xebec::NavBarProxy.new('foobar', new_nav_bar_helper)
+      end
+    end
+    should 'require a NavBarHelper' do
+      assert_raises(ArgumentError) do
+        Xebec::NavBarProxy.new(Xebec::NavBar.new, 'baz')
+      end
+    end
+  end
+  
+  context 'a NavBar proxy' do
+    
+    setup do
+      clear_translations!
+      @bar = Xebec::NavBar.new('elephants')
+      @helper = new_nav_bar_helper
+      @proxy = Xebec::NavBarProxy.new(@bar, @helper)
+    end
+    
+    should 'respond to :name' do
+      assert @proxy.respond_to?(:name)
+    end
+    
+    should "return the NavBar's name when sent :name" do
+      assert_equal 'elephants', @proxy.name
+    end
+    
+    should 'not respond to a method that the underlying NavBar does not' do
+      assert !@proxy.respond_to?(:cromulize)
+    end
+    
+    should "render a navigation bar with the class 'navbar' and the bar's name" do
+      assert_select_from @proxy.to_s, "ul.navbar.elephants"
+    end
+    
+    context 'with an empty NavBar' do
+    
+      should 'render an empty navigation bar' do
+        assert_select_from @proxy.to_s, 'ul.navbar', /$^/
+      end
+      
+    end
+    
+    context 'with a NavBar that has a navigation item declared as a name' do
+      setup do
+        @helper.stubs(:foo_path).returns("/foo")
+        @bar.nav_item :foo
+      end
+      should 'render a navigation bar with the appropriate items' do
+        assert_select_from @proxy.to_s, 'ul.navbar' do
+          assert_select 'li' do
+            assert_select 'a[href="/foo"]', 'Foo'
+          end
+        end
+      end
+    end
+    
+    context 'with a NavBar that has a navigation item set as current' do
+      setup do
+        @bar.nav_item :foo, '/foo'
+        @bar.current = :foo
+      end
+      should 'render a navigation bar with the item marked as current' do
+        assert_select_from @proxy.to_s, 'ul.navbar' do
+          assert_select 'li.current', 'Foo'
+        end
+      end
+    end
+        
+    
+    context 'with a NavBar that has a navigation item declared as a name and URL' do
+      setup do
+        @bar.nav_item :foo, 'http://foo.com'
+      end
+      should 'render a navigation bar with the appropriate items' do
+        assert_select_from @proxy.to_s, 'ul.navbar' do
+          assert_select 'li' do
+            assert_select 'a[href="http://foo.com"]', 'Foo'
+          end
+        end
+      end
+    end
+    
+    context 'with a NavBar that has a navigation item that links to the current page' do
+      setup do
+        @helper.stubs(:current_page?).with('/').returns(true)
+        @bar.nav_item :home, '/'
+        @bar.nav_item :sign_up, '/sign_up'
+      end
+      should 'render a non-link navigation item' do
+        assert_select_from @proxy.to_s, 'ul.navbar' do
+          assert_select 'li', 'Home' do
+            assert_select 'a', 0
+          end
+        end
+      end
+      should 'render other items as links' do
+        assert_select_from @proxy.to_s, 'ul.navbar' do
+          assert_select 'li' do
+            assert_select 'a[href="/sign_up"]', 'Sign Up'
+          end
+        end
+      end
+      should 'add the "current" class to the current item' do
+        assert_select_from @proxy.to_s, 'ul.navbar' do
+          assert_select 'li.current', 'Home'
+        end
+      end
+    end
+    
+    context "with a NavBar that has a navigation item with an i18n'd title" do
+      setup do
+        define_translation 'navbar.elephants.foo', 'My Foos'
+        @helper.stubs(:foo_path).returns("/foo")
+        @bar.nav_item :foo
+      end
+      should 'render a navigation bar using the internationalized text' do
+        assert_select_from @proxy.to_s, 'ul.navbar' do
+          assert_select 'li' do
+            assert_select 'a', 'My Foos'
+          end
+        end
+      end
+    end
+    
+  end
+  
+end

data/test/nav_bar_test.rb

@@ -0,0 +1,49 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+require 'xebec'
+
+class NavBarTest < Test::Unit::TestCase
+  
+  context 'a NavBar' do
+    
+    setup do
+      @bar = Xebec::NavBar.new
+    end
+    
+    should 'use :default as its name by default' do
+      assert_equal :default, @bar.name
+    end
+    
+    should 'use a specified name' do
+      assert_equal 'fazbot', Xebec::NavBar.new('fazbot').name
+    end
+    
+    should 'be empty by default' do
+      assert @bar.empty?
+    end
+    
+    should 'not have any item specified as current by default' do
+      assert @bar.current.blank?
+    end
+    
+    context 'with some items' do
+      setup do
+        @bar.nav_item :foo
+        @bar.nav_item :bar
+      end
+      should 'not be empty' do
+        assert !@bar.empty?
+      end
+    end
+    
+    should 'not allow a nameless item to be added' do
+      assert_raises ArgumentError do
+        @bar.nav_item nil
+      end
+      assert_raises ArgumentError do
+        @bar.nav_item ''
+      end
+    end
+    
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,49 @@
+require 'test/unit'
+require 'test/unit/testcase'
+require 'rubygems'
+require 'shoulda'
+require 'mocha'
+require 'activesupport'
+require 'actionpack'
+require 'action_view'
+require 'action_controller'
+
+begin
+  require 'redgreen/unicode'
+rescue
+  require 'redgreen'
+end
+
+[['..', 'lib'], ['lib']].each do |lib_dir|
+  lib_path = File.expand_path(File.join(File.dirname(__FILE__), *lib_dir))
+  $: << lib_path unless $:.include?(lib_path)
+end
+
+require 'xebec'
+
+Test::Unit::TestCase.class_eval do
+  include ActionController::Assertions::SelectorAssertions
+  
+  def assert_select_from(text, *args, &block)
+    @selected = HTML::Document.new(text).root.children
+    assert_select(*args, &block)
+  end
+  
+  def new_nav_bar_helper
+    ActionView::Base.new.tap do |helper|
+      helper.extend Xebec::NavBarHelper
+      helper.stubs(:current_page?).returns(false)
+    end
+  end
+  
+  def clear_translations!
+    I18n.reload!
+  end
+
+  def define_translation(key, value)
+    hash = key.to_s.split('.').reverse.inject(value) do |value, key_part|
+      { key_part.to_sym => value }
+    end
+    I18n.backend.send :merge_translations, I18n.locale, hash
+  end
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification 
+name: xebec
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- James Rosen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-04 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 2.10.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.9.8
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: redgreen
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.2.2
+    version: 
+description: Helpers for generating navigation bars
+email: james.a.rosen@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- .gitignore
+- README.md
+- Rakefile
+- VERSION
+- developer_tasks/doc.rake
+- developer_tasks/gem.rake
+- developer_tasks/test.rake
+- doc/example_app/Gemfile
+- doc/example_app/README.md
+- doc/example_app/app/controllers/application_controller.rb
+- doc/example_app/app/controllers/pages_controller.rb
+- doc/example_app/app/controllers/projects_controller.rb
+- doc/example_app/app/views/layouts/_site_nav_bar.html.erb
+- doc/example_app/app/views/layouts/application.html.erb
+- doc/example_app/app/views/pages/about_us.html.erb
+- doc/example_app/app/views/pages/faq.html.erb
+- doc/example_app/app/views/pages/feedback.html.erb
+- doc/example_app/app/views/pages/home.html.erb
+- doc/example_app/app/views/pages/privacy_policy.html.erb
+- doc/example_app/app/views/projects/budget.html.erb
+- doc/example_app/app/views/projects/edit.html.erb
+- doc/example_app/app/views/projects/history.html.erb
+- doc/example_app/app/views/projects/index.html.erb
+- doc/example_app/app/views/projects/show.html.erb
+- doc/example_app/config/locales/en.yml
+- doc/example_app/config/routes.rb
+- init.rb
+- lib/xebec.rb
+- lib/xebec/controller_support.rb
+- lib/xebec/has_nav_bars.rb
+- lib/xebec/nav_bar.rb
+- lib/xebec/nav_bar_helper.rb
+- lib/xebec/nav_bar_proxy.rb
+- lib/xebec/nav_item.rb
+- rails/init.rb
+- tasks/README.md
+- test/controller_support_test.rb
+- test/nav_bar_helper_test.rb
+- test/nav_bar_proxy_test.rb
+- test/nav_bar_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/jamesarosen/xebec
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Xebec Documentation
+- --charset
+- utf-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Navigation helpers
+test_files: 
+- test/controller_support_test.rb
+- test/nav_bar_helper_test.rb
+- test/nav_bar_proxy_test.rb
+- test/nav_bar_test.rb
+- test/test_helper.rb