tabs_on_rails 0.8.1

data/CHANGELOG.rdoc

@@ -0,0 +1,50 @@
+= Changelog
+
+
+== Release 0.8.1
+
+* CHANGED: Controller#set_tab now uses #send instead of #instance_eval (better performance and more security)
+
+* CHANGED: run test against Rails ~> 2.3.0 but ensure compatibility with Rails 2.2.x.
+
+
+== Release 0.8.0
+
+* FIXED: Invalid usage of the word namescope instead of namespace.
+
+* FIXED: :current_tab? not available as helper method (closes #229).
+
+* FIXED: GitHub now requires the Manifest file to be included in the repos.
+
+* FIXED: Controller methods should be protected/private (closes #228).
+
+* CHANGED: Status to Beta and bumped release (closes #227).
+
+* REMOVED: Deprecated current_tab setter method. Use set_tab instead.
+
+
+== Release 0.3.0
+
+* ADDED: Support for namespaces in order to manage concurrent tab menus (closes #144).
+
+* FIXED: `Uninitialized constant RAILS_DEFAULT_LOGGER (NameError)' error message when running tests outside a Rails environment.
+
+* FIXED: Tests complains when Rails 2.3.2 is installed. This library is 100% compatible with Rails 2.3.2 but for now let's force tests to use Rails 2.2.2.
+
+* CHANGED: current_tab= controller instance/class methods are now deprecated. Use set_tab instead.
+
+* CHANGED: Calling tabs_tag with a custom builder as first parameter is now deprecated. Use :builder option instead.
+
+
+== Release 0.2.0
+
+* ADDED: The README file is definitely more useful now, filled up with some basic documentation.
+
+* CHANGED: Use the standard way to initialize a Rails plugin when packaged as a GEM (closes #146).
+
+* CHANGED: Removed development version warning (closes #145).
+
+
+== Release 0.1.0
+
+* Initial version

data/LICENSE.rdoc

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Simone Carletti
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest

@@ -0,0 +1,23 @@
+CHANGELOG.rdoc
+init.rb
+install.rb
+lib/tabs_on_rails/controller_mixin.rb
+lib/tabs_on_rails/tabs.rb
+lib/tabs_on_rails/version.rb
+lib/tabs_on_rails.rb
+LICENSE.rdoc
+Manifest
+rails/init.rb
+Rakefile
+README.rdoc
+tabs_on_rails.gemspec
+tasks/tabs_on_rails_tasks.rake
+test/builder_test.rb
+test/controller_mixin_helpers_test.rb
+test/controller_mixin_test.rb
+test/controller_mixin_with_controller_test.rb
+test/fixtures/mixin/standard.html.erb
+test/tabs_builder_test.rb
+test/tabs_on_rails_test.rb
+test/test_helper.rb
+uninstall.rb

data/README.rdoc

@@ -0,0 +1,270 @@
+= TabsOnRails
+
+TabsOnRails is a simple Rails plugin for creating and managing Tabs.
+It provides helpers for creating tabs with a flexible interface.
+
+
+== Requirements
+
+* Ruby >= 1.8.6
+* Rails >= 2.2
+
+Note. TabsOnRails doesn't work with Rails 2.1 or previous versions (see {Ticket #245}[http://code.simonecarletti.com/issues/show/245]).
+
+
+== Rails Installation
+
+=== As a Gem
+
+This is the preferred way to install TabsOnRails and the best way if you want install a stable version.
+
+  $ gem install weppos-tabs_on_rails --source http://gems.github.com
+
+You can specify the GEM dependency in your application environment.rb file:
+
+  Rails::Initializer.run do |config|
+    
+    # other configurations
+    
+    config.gem "weppos-tabs_on_rails", :lib => "tabs_on_rails", :source => "http://gems.github.com"
+  end
+
+=== As a Plugin
+
+This is the preferred way if you want to live on the edge and install a development version.
+
+  $ script/plugin install git://github.com/weppos/tabs_on_rails.git
+
+
+== Quick Start
+
+In your template use the <tt>tabs_tag</tt> helper to create your tab.
+
+  <% tabs_tag do |tab| %>
+    <%= tab.home      'Homepage', root_path %>
+    <%= tab.dashboard 'Dashboard', dashboard_path %>
+    <%= tab.account   'Account', account_path %>
+  <% end %>
+
+The example above produces the following HTML output.
+
+  <ul>
+    <li><a href="/">Homepage</a></li>
+    <li><a href="/dashboard">Dashboard</a></li>
+    <li><a href="/account">Account</a></li>
+  </ul>
+
+The usage is similar to the Rails route file.
+You create named tabs with the syntax <tt>tab.name_of_tab</tt>. 
+
+The name you use creating a tab is the same you're going to refer to in your controller
+when you want to mark a tab as the current tab.
+
+  class DashboardController < ApplicationController
+    set_tab :dashboard
+  end
+
+Now, if the action belongs to DashboardController, the template will automatically render the following HTML code.
+
+  <ul>
+    <li><a href="/">Homepage</a></li>
+    <li><span>Dashboard</span></li>
+    <li><a href="/account">Account</a></li>
+  </ul>
+
+Use the <tt>current_tab</tt> helper method if you need to access the value of current tab in your controller or template.
+
+  class DashboardController < ApplicationController
+    set_tab :dashboard
+  end
+
+  # In your view
+  <p>The name of current tab is <%= current_tab %>.</p>
+
+
+== Restricting set_tab scope
+
+The <tt>set_tab</tt> method understands all options you are used to pass to a Rails controller filter.
+In fact, behind the scenes this method uses a <tt>before_filter</tt> to store the tab in the <tt>@tab_stack</tt> variable.
+
+Taking advantage of Rails filter options, you can restrict a tab to a selected group of actions in the same controller.
+
+  class PostsController < ApplicationController
+    set_tab :admin
+    set_tab :posts, :only => %w(index show)
+  end
+  
+  class ApplicationController < ActionController::Base
+    set_tab :admin, :if => :admin_controller?
+    
+    def admin_controller?
+      self.class.name =~ /^Admin(::|Controller)/
+    end
+  end
+
+
+== Using Namespaces to create Multiple Tabs
+
+Namespaces enable you to create and manage tabs in parallels. The best way to demonstrate namespace usage is with an example.
+
+Let's assume your application provides a first level navigation menu with 3 elements: :home, :dashboard, :projects. The relationship between your tabs and your controllers is 1:1 so you should end up with the following source code.
+
+  class HomeController
+    set_tab :home
+  end
+
+  class DashboardController
+    set_tab :dashboard
+  end
+
+  class ProjectsController
+    set_tab :projects
+    
+    def first; end
+    def second; end
+    def third; end
+  end
+
+The project controller contains 3 actions and you might want to create a second-level navigation menu. This menu should reflect the navigation status of the user in the project page.
+
+Without namespaces, you wouldn't be able to accomplish this task because you already set the current tab value to :projects. You need to create a parallel navigation menu and uniquely identify it with a custom namespace.
+Let's call it :navigation.
+
+  class ProjectsController
+    set_tab :projects
+  
+    # Create an other tab navigation level
+    set_tab :first, :navigation, :only => %w(first)
+    set_tab :second, :navigation, :only => %w(second)
+    set_tab :third, :navigation, :only => %w(third)
+  
+    def first; end
+    def second; end
+    def third; end
+  end
+
+Voilà! That's all you need to do. And you can create an unlimited number of namespaces as long as you use an unique name to identify them.
+
+The default namespace is called :default. Passing :default as name is the same as don't using any namespace at all. The following lines are equivalent.
+
+  set_tab :projects
+  set_tab :projects, :default
+
+
+=== Rendering Tabs with Namespaces
+
+To switch namespace in your template, just pass the :namespace option to the <tt>tabs_tag</tt> helper method.
+
+  <% tabs_tag do |tab| %>
+    <%= tab.home      'Homepage', root_path %>
+    <%= tab.dashboard 'Dashboard', dashboard_path %>
+    <%= tab.projects  'Projects', projects_path %>
+  <% end %>
+
+  <% tabs_tag :namespace => :navigation do |tab| %>
+    <%= tab.first   'First', first_project_path %>
+    <%= tab.second  'Second', second_project_path %>
+    <%= tab.third   'Account', third_project_path %>
+  <% end %>
+
+=== Namespace scope
+
+As a bonus feature, the namespace name does need to be unique within current request scope, not necessarily across the entire application.
+
+Back to the previous example, you can reuse the same namespace in the other controllers. In this way, you can reuse your templates as well.
+
+  class HomeController
+    set_tab :home
+  end
+
+  class DashboardController
+    set_tab :dashboard
+
+    set_tab :index,  :navigation, :only => %w(index)
+    set_tab :common, :navigation, :only => %w(foo bar)
+    
+    # ...
+  end
+
+  class ProjectsController
+    set_tab :projects
+  
+    set_tab :first,  :navigation, :only => %w(first)
+    set_tab :second, :navigation, :only => %w(second)
+    set_tab :third,  :navigation, :only => %w(third)
+    
+    # ...
+  end
+
+== Tab Builders
+
+The <tt>Builder</tt> is responsible for creating the tabs HTML code. This library is bundled with two <tt>Builders</tt>:
+
+<tt>Tabs::Builder</tt>:: this is the abstract interface for any custom builder.
+<tt>Tabs::TabsBuilder</tt>:: this is the default builder.
+
+=== Understanding the Builder
+
+Builders act as formatters. A Builder incapsulates all the logic behind the tab creation including the code required to toggle tabs status.
+
+When the <tt>tabs_tag</tt> helper is called, it creates a new <tt>Tabs</tt> instance with selected Builder.
+If you don't provide a custom builder, then <tt>Tabs::TabsBuilder</tt> is used by default.
+
+=== Creating a custom Builder
+
+All builders must extend the base <tt>Tabs::Builder</tt> class and implement at least the <tt>tab_for</tt> method.
+Additional overridable methods include:
+
+<tt>open_tabs</tt>:: the method called before the tab set
+<tt>close_tabs</tt>:: the method called after the tab set
+<tt>tab_for</tt>:: the method called to create a single tab item
+
+The following example creates a custom tab builder called MainTabBuilder.
+
+  class MenuTabBuilder < TabsOnRails::Tabs::Builder
+    def tab_for(tab, name, options, item_options = {})
+      item_options[:class] = (current_tab?(tab) ? 'active' : '')
+      @context.content_tag(:li, item_options) do
+        @context.link_to(name, options)
+      end
+    end
+  end
+
+=== Using a custom Builder
+
+In your view, simply pass the builder class to the <tt>tabs_tag</tt> method.
+
+  <% tabs_tag(:builder => MenuTabBuilder) do |tab| %>
+    <%= tab.home        'Homepage', root_path %>
+    <%= tab.dashboard,  'Dashboard', dashboard_path %>
+    <%= tab.account     'Account', account_path, :style => 'float: right;' %>
+  <% end %>
+  
+This is the final result.
+
+  <ul>
+    <li class=""><a href="/">Homepage</a></li>
+    <li class="active"><a href="/dashboard">Dashboard</a></li>
+    <li class="" style="float: right;"><a href="/account">Account</a></li>
+  </ul>
+
+== Documentation
+
+The library is still under development and this README file might not be contain the latest changes.
+For the full documentation, development roadmap and more information please visit the {project page}[http://code.simonecarletti.com/wiki/tabsonrails].
+
+
+== Credits
+
+Author:: {Simone Carletti}[http://www.simonecarletti.com/] <weppos@weppos.net>
+
+
+== Resources
+
+* {Homepage}[http://code.simonecarletti.com/tabsonrails]
+* {GitHub}[http://github.com/weppos/tabs_on_rails/]
+
+
+== License
+
+Copyright (c) 2009 Simone Carletti, TabsOnRails is released under the MIT license.

data/Rakefile

@@ -0,0 +1,52 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+$:.unshift(File.dirname(__FILE__) + "/lib")
+require 'tabs_on_rails'
+
+
+PKG_NAME    = ENV['PKG_NAME']    || TabsOnRails::GEM
+PKG_VERSION = ENV['PKG_VERSION'] || TabsOnRails::VERSION
+PKG_SUMMARY = "A simple Ruby on Rails plugin for creating and managing Tabs."
+PKG_FILES   = FileList.new("{lib,rails,tasks,test}/**/*") do |files|
+  files.include %w(*.{rdoc,rb})
+  files.include %w(Rakefile)
+end
+RUBYFORGE_PROJECT = nil
+
+if ENV['SNAPSHOT'].to_i == 1
+  PKG_VERSION << "." << Time.now.utc.strftime("%Y%m%d%H%M%S")
+end
+ 
+ 
+Echoe.new(PKG_NAME, PKG_VERSION) do |p|
+  p.author        = "Simone Carletti"
+  p.email         = "weppos@weppos.net"
+  p.summary       = PKG_SUMMARY
+  p.description   = <<-EOD
+    TabsOnRails is a simple Ruby on Rails plugin for creating and managing Tabs. \
+    It provides helpers for creating tabs with a flexible interface.
+  EOD
+  p.url           = "http://code.simonecarletti.com/tabsonrails"
+  p.project       = RUBYFORGE_PROJECT
+
+  p.need_zip      = true
+  p.rcov_options  = ["--main << README.rdoc -x Rakefile -x rcov"]
+  p.rdoc_pattern  = /^(lib|CHANGELOG.rdoc|README.rdoc|LICENSE.rdoc)/
+
+  p.development_dependencies += ["rake  >=0.8",
+                                 "echoe >=3.1"]
+end
+
+
+begin
+  require 'code_statistics'
+  desc "Show library's code statistics"
+  task :stats do
+    CodeStatistics.new(["TabsOnRails", "lib"],
+                       ["Tests", "test"]).to_s
+  end
+rescue LoadError
+  puts "CodeStatistics (Rails) is not available"
+end

data/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), 'rails', 'init')

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/tabs_on_rails/controller_mixin.rb

@@ -0,0 +1,132 @@
+# 
+# = Tabs on Rails
+#
+# A simple Ruby on Rails plugin for creating and managing Tabs.
+# 
+#
+# Category::    Rails
+# Package::     TabsOnRails
+# Author::      Simone Carletti <weppos@weppos.net>
+# License::     MIT License
+#
+#--
+# 
+#++
+
+
+module TabsOnRails
+  
+  module ControllerMixin
+    
+    def self.included(base)
+      base.extend         ClassMethods
+      base.class_eval do
+        include       InstanceMethods
+        helper        HelperMethods
+        helper_method :current_tab, :current_tab?
+      end
+    end
+
+    module ClassMethods
+
+      # Sets the value for current tab to given name.
+      #
+      #   set_tab :foo
+      #
+      # If you need to manage multiple tabs, then you can pass an optional namespace.
+      #
+      #   set_tab :foo, :namespace
+      #
+      # The <tt>set_tab</tt> method understands all options you are used to pass to a Rails controller filter.
+      # In fact, behind the scenes this method uses a <tt>before_filter</tt>
+      # to store the tab in the <tt>@tab_stack</tt> variable.
+      # For example, you can set the tab only for a restricted group of actions in the same controller
+      # using the <tt>:only</tt> and <tt>:except</tt> options.
+      #
+      # ==== Examples
+      # 
+      #   set_tab :foo
+      #   set_tab :foo, :except => :new
+      #   set_tab :foo, :only => [ :index, :show ]
+      #
+      #   set_tab :foo, :namespace
+      #   set_tab :foo, :namespace, :only => [ :index, :show ]
+      #
+      def set_tab(*args)
+        options = args.extract_options!
+        name, namespace = args
+        
+        before_filter(options) do |controller|
+          controller.send(:set_tab, name, namespace)
+        end
+      end
+
+    end
+
+    module InstanceMethods
+      protected
+
+        # Sets the value for current tab to given name.
+        # If you need to manage multiple tabs, then you can pass an optional namespace.
+        #
+        # ==== Examples
+        #
+        #   set_tab :homepage
+        #   set_tab :dashboard, :menu
+        #
+        def set_tab(name, namespace = nil)
+          tab_stack[namespace || :default] = name
+        end
+
+        # Returns the value for current tab in the default namespace,
+        # or nil if no tab has been set before.
+        # You can pass <tt>namespace</tt> to get the value of current tab for a different namespace.
+        #
+        # ==== Examples
+        #
+        #   current_tab           # => nil
+        #   current_tab :menu     # => nil
+        #
+        #   set_tab :homepage
+        #   set_tab :dashboard, :menu
+        #
+        #   current_tab           # => :homepage
+        #   current_tab :menu     # => :dashboard
+        #
+        def current_tab(namespace = nil)
+          tab_stack[namespace || :default]
+        end
+
+        # Returns whether the current tab in <tt>namespace</tt> matches <tt>name</tt>.
+        def current_tab?(name, namespace = nil)
+          current_tab(namespace).to_s == name.to_s
+        end
+
+        # Initializes and/or returns the tab stack.
+        # You won't probably need to use this method directly
+        # unless you are trying to hack the plugin architecture.
+        def tab_stack
+          @tab_stack ||= {}
+        end
+
+    end
+
+    module HelperMethods
+
+      def tabs_tag(options = {}, &block)
+        raise LocalJumpError, "no block given" unless block_given?
+
+        unless options.is_a?(Hash)
+          ActiveSupport::Deprecation.warn('tabs_tag takes a Hash of options, no longer a builder class. Use :builder => BuilderClass.', caller)
+          options = { :builder => options }
+        end
+        tabs  = Tabs.new(self, { :namespace => :default }.merge(options))
+
+        concat(tabs.open_tabs.to_s)
+        yield  tabs
+        concat(tabs.close_tabs.to_s)
+      end
+
+    end
+  end
+end