tabs_on_rails 2.2.0 → 3.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f8b05c093bf3ea463e7286064ae18e3f3b443785
+  data.tar.gz: b795ffa146e76d820ba77a693f8646787b11257d
+SHA512:
+  metadata.gz: acb18c671a6d0ff4dca1d4ec50b510c070a520d9372a5db4815c52d7b905159aa395daa5bd2350e509eff7820e15064a85774df87be89450aded8ab7ad399a2c
+  data.tar.gz: a9c0c4e43a517f34534769ecde22c3f9c73e628237e6c93d722f355d773d7ac6f7ba12aa5705b7f6013f42c6960c62dcd13a61793eee004e4f1bd21bf952681b

data/.gitignore

@@ -1,11 +1,12 @@
 # Bundler
-.bundle
-pkg/*
-Gemfile.lock
-
-# RVM
-.rvmrc
+/.bundle/
+/Gemfile.lock
+gemfiles/*.gemfile.lock
 
 # YARD
-.yardoc
-yardoc/
+/.yardoc
+/_yardoc/
+
+# Artifacts
+/pkg/
+/tmp/

data/.ruby-gemset

@@ -0,0 +1 @@
+tabs_on_rails

data/.travis.yml

@@ -1,12 +1,15 @@
 rvm:
-  - 1.8.7
-  - 1.9.2
-  - 1.9.3
-  - ree
+  - 2.2.5
+  - 2.3.1
+  - 2.4.0
+
 gemfile:
-  - gemfiles/3.0.gemfile
-  - gemfiles/3.1.gemfile
-  - gemfiles/3.2.gemfile
-notifications:
-  recipients:
-    - weppos@weppos.net
+  - gemfiles/4.2.gemfile
+  - gemfiles/5.0.gemfile
+
+before_install:
+  - gem install bundler
+
+env:
+  global:
+  - NOKOGIRI_USE_SYSTEM_LIBRARIES=true

data/Appraisals

@@ -1,11 +1,6 @@
-appraise "3.0" do
-  gem "activerecord", "~> 3.0"
+appraise "4.2" do
+  gem "rails", "~> 4.2.0"
 end
-
-appraise "3.1" do
-  gem "activerecord", "~> 3.1"
+appraise "5.0" do
+  gem "rails", "~> 5.0.0"
 end
-
-appraise "3.2" do
-  gem "activerecord", "~> 3.2"
-end

data/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
 
+## Release 3.0.0
+
+- CHANGED: Compatible with Rails 5.
+- CHANGED: Dropped support for Rails before 4.2 and Ruby before 2.2.
+
+
 ## Release 2.2.0
 
 * NEW: Ability to configure a default builder (GH-20). [Thanks @ilstar]

data/Gemfile

@@ -1,3 +1,3 @@
-source "http://rubygems.org"
+source 'https://rubygems.org'
 
 gemspec

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2009-2013 Simone Carletti
+Copyright (c) 2009-2017 Simone Carletti <weppos@weppos.net>
 
 MIT License
 

data/README.md

@@ -1,81 +1,343 @@
 # Tabs on Rails
 
-*TabsOnRails* is a simple Rails plugin for creating tabs and navigation menus. It provides helpers for generating navigation menus with a flexible interface.
+<tt>TabsOnRails</tt> is a simple Rails plugin for creating tabs and navigation menus. It provides helpers for generating navigation menus with a flexible interface.
 
 
 ## Requirements
 
-* Rails 3
+- Rails 4.2 or Rails 5
 
-Please note 
-
-* TabsOnRails 2.x requires Rails 3. Use TabsOnRails 1.3.x with Rails 2.
-* TabsOnRails doesn't work with Rails 2.1 or lower
-([comment](http://www.simonecarletti.com/blog/2009/04/tabsonrails/#comment-2901) and [commit](http://github.com/weppos/tabs_on_rails/commit/d5ae9f401e3d0acc87251fa8957a8625e90ba4b3)).
+For older versions of Ruby or Ruby on Rails, see the [CHANGELOG](CHANGELOG.md).
 
 
 ## Installation
 
-[RubyGems](http://rubygems.org) is the preferred way to install *TabsOnRails* and the best way if you want install a stable version.
+Add this line to your application's `Gemfile`:
 
-    $ gem install tabs_on_rails
+    gem "tabs_on_rails"
 
-Specify the Gem dependency in the [Bundler](http://gembundler.com) `Gemfile`.
+And then execute `bundle` to install the dependencies:
 
-    gem "tabs_on_rails"
+    $ bundle
 
-Use [Bundler](http://gembundler.com) and the [:git option](http://gembundler.com/v1.0/git.html) if you want to grab the latest version from the Git repository.
+Use [Bundler](http://bundler.io/) and the `:git` option if you want to grab the latest version from the Git repository.
 
 
 ## Usage
 
 In your template use the `tabs_tag` 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 %>
+```ruby
+<%= 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.
+renders
 
-    <ul>
-      <li><a href="/">Homepage</a></li>
-      <li><a href="/dashboard">Dashboard</a></li>
-      <li><a href="/account">Account</a></li>
-    </ul>
+```html
+<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.
 
+```ruby
+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 class="custom"><span>Dashboard</span></li>
-      <li><a href="/account">Account</a></li>
-    </ul>
+```html
+<ul>
+  <li><a href="/">Homepage</a></li>
+  <li class="custom"><span>Dashboard</span></li>
+  <li><a href="/account">Account</a></li>
+</ul>
+```
 
 Use the `current_tab` helper method if you need to access the value of current tab in your controller or template.
 
-    class DashboardController < ApplicationController
-      set_tab :dashboard
+```ruby
+class DashboardController < ApplicationController
+  set_tab :dashboard
+end
+```
+
+In your view
+
+```html
+<p>The name of current tab is <%= current_tab %>.</p>
+```
+
+### Customizing a Tab
+
+You can pass a hash of options to customize the style and the behavior of the tab item.
+Behind the scenes, each time you create a tab, the `#tab_for` method is invoked.
+
+```ruby
+<%= tabs_tag do |tab| %>
+  <%= tab.home      'Homepage', root_path, :style => "padding: 10px" %>
+  <%= tab.dashboard 'Dashboard', dashboard_path %>
+<% end %>
+```
+
+renders
+
+```
+<ul>
+  <li style="padding: 10px"><a href="/">Homepage</a></li>
+  <li class="custom"><span>Dashboard</span></li>
+  <li><a href="/account">Account</a></li>
+</ul>
+```
+
+See `TabsOnRails::Tabs::TabsBuilder#tab_for` for more details.
+
+### Customizing `open_tabs` and `close_tabs`
+
+The `open_tabs` and the `close_tabs` methods can be customized with the `:open_tabs` and `:close_tabs` option.
+
+```ruby
+<%= tabs_tag :open_tabs => { :id => "tabs", :class => "cool" } do |tab| %>
+  <%= tab.home      'Homepage', root_path %>
+  <%= tab.dashboard 'Dashboard', dashboard_path %>
+  <%= tab.account   'Account', account_path %>
+<% end %>
+```
+
+renders
+
+```html
+<ul id="tabs" class="cool">
+  <li><a href="/">Homepage</a></li>
+  <li><a href="/dashboard">Dashboard</a></li>
+  <li><a href="/account">Account</a></li>
+</ul>
+```
+
+Further customizations require a custom `Builder` (see below).
+
+
+## Restricting `set_tab` scope
+
+The `set_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 store the tab in the `@tab_stack` variable.
+
+Taking advantage of Rails filter options, you can restrict a tab to a selected group of actions in the same controller.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+set_tab :projects
+set_tab :projects, :default
+```
+
+### Rendering Tabs with Namespaces
+
+To switch namespace in your template, just pass the `:namespace` option to the `tabs_tag` helper method.
+
+```ruby
+<%= 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', project_first_path %>
+  <%= tab.second  'Second', project_second_path %>
+  <%= tab.third   'Account', project_third_path %>
+<% end %>
+```
+
+### Namespace scope
+
+As a bonus feature, the namespace needs 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.
+
+```ruby
+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 `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 encapsulates 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 `MenuTabBuilder`.
+
+```ruby
+class MenuTabBuilder < TabsOnRails::Tabs::Builder
+  def open_tabs(options = {})
+    @context.tag("ul", options, open = true)
+  end
+
+  def close_tabs(options = {})
+    "</ul>".html_safe
+  end
+
+  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.
+
+```ruby
+<%= 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 %>
+```
+
+renders
+
+```html
+<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>
+```
+
+
+## Credits
+
+<tt>TabsOnRails</tt> was created and is maintained by [Simone Carletti](https://simonecarletti.com/). Many improvements and bugfixes were contributed by the [open source community](https://github.com/weppos/tabs_on_rails/graphs/contributors).
+
+
+## Contributing
+
+Direct questions and discussions to [Stack Overflow](http://stackoverflow.com/questions/tagged/tabs-on-rails).
 
-    # In your view
-    <p>The name of current tab is <%= current_tab %>.</p>
+[Pull requests](https://github.com/weppos/tabs_on_rails) are very welcome! Please include tests for every patch, and create a topic branch for every separate change you make.
 
-Read the [documentation](http://www.simonecarletti.com/code/tabs_on_rails/docs/) to learn more about advanced usage, builders and namespaces.
+Report issues or feature requests to [GitHub Issues](https://github.com/weppos/tabs_on_rails/issues).
 
 
-## Resources
+## More Information
 
-* [Homepage](http://www.simonecarletti.com/code/tabs_on_rails)
-* [Documentation](http://www.simonecarletti.com/code/tabs_on_rails/docs/)
-* [API](http://rubydoc.info/gems/tabs_on_rails)
-* [Repository](https://github.com/weppos/tabs_on_rails)
-* [Issue Tracker](http://github.com/weppos/tabs_on_rails/issues)
+- [Homepage](https://simonecarletti.com/code/tabs-on-rails)
+- [RubyGems](https://rubygems.org/gems/tabs_on_rails)
+- [Issues](https://github.com/weppos/tabs_on_rails/issues)
 
 
 ## License
 
-Copyright (c) 2009-2013 Simone Carletti. This is Free Software distributed under the MIT license.
+Copyright (c) 2009-2017 Simone Carletti. This is Free Software distributed under the MIT license.