TabsOnRails

TabsOnRails is a simple Rails plugin for creating and managing Tabs. It provides helpers for creating tabs with a flexible interface.

Rails Installation

As a Gem

This is the preferred way to install TabsOnRails and the best way if you want install a stable version. 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 tabs_tag helper to create your tab.

<% tabs_tab 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 tab.name_of_tab.

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
  current_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>

Restricting current_tab scope

The current_tab method understands all options you are used to pass to a Rails controller filter. In fact, behind the scenes this method uses a before_filter to set a special @current_tab 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
  current_tab :admin
  current_tab :posts, :only => [ :index, :show ]
end

class ApplicationController < ActionController::Base
  current_tab :admin, :if => :admin_controller?

  def admin_controller?
    self.class.name =~ /^Admin(::|Controller)/
  end
end

Tab Builders

The Builder is responsible for creating the tabs HTML code. This library is bundled with two Builders:

Tabs::Builder: this is the abstract interface for any custom builder.
Tabs::TabsBuilder: 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 tabs_tag helper is called, it creates a new Tabs instance with selected Builder. If you don’t provide a custom builder, then Tabs::TabsBuilder is used by default.

Creating a custom Builder

All builders must extend the base Tabs::Builder class and implement at least the tab_for method. Additional overridable methods include:

open_tabs: the method called before the tab set
close_tabs: the method called after the tab set
tab_for: 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 tabs_tag method.

<% tabs_tag(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.

Credits

Author: Simone Carletti <[email protected]>