tabulous 1.3.2 → 2.0.0

data/CHANGELOG.md

@@ -0,0 +1,53 @@
+### 2.0.0 (May 12, 2013)
+* Introduced a completely new, non-backwards-compatible syntax for app/tabs/tabulous.rb.
+* You can have more than one tab navigation bar on the same page.
+* You can customize the generated tab markup by creating your own renderer class.
+* Namespaced controllers are now fully supported.
+* The active tab is now clickable by default.
+* When tabulous cannot determine which tab to make active based on the controller action, the
+  default behavior used to be to throw an error.  Now it is to not render the tabs.
+* The default markup uses class="tabs" and class="subtabs" instead of id="tabs" and id="subtabs".
+* The default markup no longer adds the classes "enabled" or "inactive" to tabs, as these are a bit
+  redundant in the presence of "disabled" and "active" classes.
+* Ruby 1.8 is no longer supported.
+
+### 1.3.2 (April 12, 2013)
+* Fixed a bug where the gem's gemspec did not include all of the files.
+
+### 1.3.1 (April 6, 2013)
+* Ensured compatibility with Rails 4.0.0.beta1 and Ruby 2.0.
+* Maintained compatibility with Rails 3.0, 3.1 and 3.2 and Ruby 1.8 and 1.9.
+* Complete overhaul of the test applications to make them easier to test across multiple versions of
+  Rails and Ruby.
+
+### 1.3.0 (March 20, 2012)
+* Added config.subtabs_ul_class.
+* Verified that tabulous works with Ruby 1.9.3.
+
+### 1.2.0 (February 8, 2012)
+* Added support for Twitter Bootstrap (version 2).
+* Noted in the documentation that tabulous works with Rails 3.2.
+
+### 1.1.0 (January 10, 2012)
+* Deprecated the raise_error_if_no_tab_found configuration setting.  Replaced it with
+  config.when_action_has_no_tab.
+* Changed some gem versions in the development dependencies.
+
+### 1.0.3 (November 6, 2011)
+* Added support for Rails 3.1 (finally!).
+
+### 1.0.2 (April 19, 2011)
+* Fixed bug where the tabs generator would crash if there were index routes that were not named.
+
+### 1.0.1 (March 9, 2011)
+* No longer requires Rubygems version > 1.4.0; requires > 1.3.7 instead.
+
+### 1.0.0 (March 4, 2011)
+* Moved tab file from config/initializers/tabulous.rb to app/tabs/tabulous.rb.
+* Changed syntax so that config.tabs and config.actions accepts a block.
+
+### 0.0.2 (March 2, 2011)
+* Changed homepage in gemspec.
+
+### 0.0.1 (March 2, 2011)
+* Initial release.

data/CHANGES_FROM_VERSION_ONE.md

@@ -0,0 +1,40 @@
+# Changes From Version One
+
+Tabulous 2 introduces significant, non-backwards-compatible changes.  If you are using an earlier version of tabulous, you will have to make some code changes when upgrading to tabulous 2.
+
+The most significant change is to the syntax of app/tabs/tabulous.rb.
+
+## New Syntax
+
+Tabulous started out with a syntax where you specified tab behavior by adding Ruby code inside a grid of options.  This syntax was an experiment in code readability and communication, and provided a new way of thinking about how to interact with Ruby code.
+
+There are three reasons this syntax was abandoned:
+
+* Tabulous became popular enough that a syntax more in line with the typical conventions of Ruby and Rails programming would be more appropriate.
+* A fair amount of newbies were using tabulous.  Experimental, boundary-pushing syntax is not appropriate for beginners as it may confuse their tastes in what constitutes good software design.
+* Developers had mixed feelings about the syntax.  Some liked it, some hated it.  No one _loved_ it.
+
+## Additions
+
+* You can have more than one tab navigation bar on the same page.
+* You can easily customize the generated tab markup.
+* Namespaced controllers are now fully supported.
+
+## Changes
+
+* The active tab is now clickable by default.
+* When tabulous cannot determine which tab to make active based on the controller action, the default behavior used to be to throw an error.  Now it is to not render the tabs.
+* The default markup uses class="tabs" and class="subtabs" instead of id="tabs" and id="subtabs".
+* The default markup no longer adds the classes "enabled" or "inactive" to tabs, as these are a bit redundant in the presence of "disabled" and "active" classes.
+* Ruby 1.8 is no longer supported.
+
+## Upgrading
+
+Tabulous 1.3.2 was tested against Rails 4.0.0.beta, so is expected to work with Rails 4.  This means that if you are upgrading to Rails 4, you don't have to upgrade to tabulous 2.  However, keep in mind that the old tabulous syntax will not be supported for future versions of Rails.
+
+To upgrade to tabulous 2, do the following:
+
+* Make sure you're using Ruby 1.9 or later.
+* You'll need to rewrite your tabulous.rb file according to the new syntax.
+* Pay special attention to all the available settings in the customize block and their defaults, some of which have changed.
+* After you've got tabulous 2 working, notice the tab HTML that's generated.  It's different enough that it can throw off any CSS or JavaScript you have related to this tab markup.  If it's causing you problems, you can either adjust your CSS and JavaScript, or tabulous lets you write your own tab HTML renderer to generate exactly the markup you desire.

data/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing to Tabulous
+
+If you have ideas, suggestions or problems, bring them up by opening an [issue on GitHub](https://github.com/techiferous/tabulous/issues).
+
+If you have an idea for new behavior, please start a discussion before going to the trouble of coding up a solution since there might be a good reason why I left that behavior out.
+
+Pull requests are welcome.  If you want your pull request to be more than a discussion starter but be a candidate for actually getting merged, please do the following:
+
+* your code should be well-written and follow the style of the rest of the tabulous code
+* you should write new specs for your code if existing specs do not offer good coverage
+* you should make sure the specs pass in all versions of Rails 3.0 or later and Ruby 1.9 and 2.0
+
+## Running Specs
+
+Unfortunately, it's really difficult to get all of the tabulous specs running so I apologize for that.  I found it difficult to set up specs to easily test tabulous across various versions of Rails and Ruby at the same time.  The process for getting the specs up and running is documented in [spec/applications/README.md](spec/applications/README.md).
+
+For instructions on how to run specs, run the default rake task in tabulous:
+
+    rake

data/OVERVIEW.md

@@ -0,0 +1,272 @@
+# Tabulous Overview
+
+## Why Tabulous Exists
+
+Tabulous was created so that you can quickly create a tabbed navigation bar with minimal effort.  It is perfect for quick prototyping, robust enough for production use, and flexible enough to grow with your app.
+
+## When to Use Tabulous
+
+Tabulous is the right tool for the job if:
+
+* you want to click on a tab to take you to a different page (URL) in your app
+
+Tabulous is the wrong tool for the job if:
+
+* you want to use Ajax to switch tabs
+* you want to embed tabbed content within a page
+
+## The Basics
+
+You describe your tabs in app/tabs/tabulous.rb like this:
+
+    Tabulous.setup do
+
+      tabs do
+        pictures_tab do
+          text          { 'My Pictures' }
+          link_path     { root_path }
+          visible_when  { true }
+          enabled_when  { true }
+          active_when   { in_action('any').of_controller('pictures') }
+        end
+
+        music_tab do
+          text          { 'My Music' }
+          link_path     { songs_path }
+          visible_when  { true }
+          enabled_when  { current_user.has_music? }
+          active_when   { a_subtab_is_active }
+        end
+
+        songs_subtab do
+          text          { 'Songs' }
+          link_path     { songs_path }
+          visible_when  { true }
+          enabled_when  { true }
+          active_when   { in_action('any').of_controller('songs') }
+        end
+
+        artists_subtab do
+          text          { 'Artists' }
+          link_path     { artists_path }
+          visible_when  { true }
+          enabled_when  { true }
+          active_when   { in_action('any').of_controller('artists') }
+        end
+
+        account_tab do
+          text          { 'My Account' }
+          link_path     { account_path(current_user) }
+          visible_when  { true }
+          enabled_when  { true }
+          active_when   { in_actions('show', 'edit', 'update').of_controller('user_profiles') }
+        end
+
+        admin_tab do
+          text          { 'Admin' }
+          link_path     { admin_path }
+          visible_when  { current_user.admin? }
+          enabled_when  { true }
+          active_when   { in_action('any').of_controller('admin') }
+        end
+      end
+
+    end
+
+Then, in your layout, you render the tabs like this:
+
+    <%= tabs %>
+    <%= subtabs %>
+
+This will produce markup that looks like this:
+
+    <div class="tabs">
+      <ul>
+        <li class="disabled">
+          <span class="tab">My Pictures</span>
+        </li>
+        <li class="active">
+          <a href="/songs" class="tab">My Music</a>
+        </li>
+        <li>
+          <a href="/account" class="tab">My Account</a>
+        </li>
+        <li>
+          <a href="/admin" class="tab">Admin</a>
+        </li>
+      </ul>
+    </div>
+
+    <div class="subtabs">
+      <ul>
+        <li>
+          <a href="/songs" class="tab">Songs</a>
+        </li>
+        <li>
+          <a href="/artists" class="tab">Artists</a>
+        </li>
+      </ul>
+    </div>
+
+## Getting Started
+
+### Installing
+
+Add tabulous to your Gemfile:
+
+    gem 'tabulous'
+
+And install the gem:
+
+    $ bundle install
+
+### Tabs
+
+Run the tabulous generator:
+
+    $ rails generate tabs
+
+This creates app/tabs/tabulous.rb.  The generator guesses what your tabs might look like based on your controllers.  So you'll need to edit this file.
+
+Tabs are displayed in the order they appear.  So if you want a set of tabs that looks like this:
+
+     ,____________, ,____________, ,__________,
+    _|  UNICORNS  |_|  RAINBOWS  |_|  PONIES  |_
+
+your tabs block should look like this:
+
+    tabs do
+      unicorns_tab do
+        ...
+      end
+
+      rainbows_tab do
+        ...
+      end
+
+      ponies_tab do
+        ...
+      end
+    end
+
+For each tab, you must specify these five declarations:
+
+* **text** -- what words to put on the tab
+* **link_path** -- where to go when you click the tab
+* **visible_when** -- whether to draw the tab at all
+* **enabled_when** -- when this tab should not be clickable
+* **active_when** -- when this tab should appear selected
+
+Let's say you wanted the unicorns tab to:
+
+* take you to '/unicorns' when clicked
+* be visible only if the user loves unicorns
+* be disabled if it's May
+* and be active whenever the UnicornsController ends up rendering the page.
+
+Your tab declaration would look like this:
+
+    unicorns_tab do
+      text          { 'Unicorns' }
+      link_path     { '/unicorns' }
+      visible_when  { current_user.loves_unicorns? }
+      enabled_when  { Time.now.month == 5 }
+      active_when   { in_action('any').of_controller('unicorns') }
+    end
+
+All of the blocks above (except for active_when) are executed in the context of your view layout, so any helper methods such as current_user or unicorns_path would be available.
+
+Read the [REFERENCE](REFERENCE.md) for more details.
+
+### Subtabs
+
+Let's say you wanted to add two subtabs to the rainbows tab.  Do this by adding the tabs right after the rainbows tab and making sure their names end with _subtab:
+
+    rainbows_tab do
+      text          { 'Rainbows' }
+      link_path     { rainbows_path }
+      visible_when  { true }
+      enabled_when  { true }
+      active_when   { a_subtab_is_active }
+    end
+
+    monorainbows_subtab do
+      text          { 'Monorainbows' }
+      link_path     { monorainbows_path }
+      visible_when  { true }
+      enabled_when  { true }
+      active_when   { in_action('any').of_controller('monorainbows') }
+    end
+
+    double_rainbows_subtab do
+      text          { 'Double Rainbows' }
+      link_path     { double_rainbows_path}
+      visible_when  { true }
+      enabled_when  { true }
+      active_when   { in_action('any').of_controller('double_rainbows') }
+    end
+
+Note also that the active_when declaration in rainbows_tab must contain a_subtab_is_active since it has subtabs.
+
+Read the [REFERENCE](REFERENCE.md) for more details.
+
+### Rendering
+
+Put these somewhere in your layout:
+
+    <%= tabs %>
+    <%= subtabs %>
+
+They do not have to appear together.
+
+Each tab is wrapped in an li tag.  If the tab is disabled, its li tag will have a "disabled" class.  If the tab is selected, its li tag will have an "active" class.
+
+If you used the generator to create your tabulous.rb file, you'll see the following:
+
+    use_css_scaffolding do
+      background_color '#ccc'
+      text_color '#444'
+      active_tab_color '#fff'
+      hover_tab_color '#ddd'
+      inactive_tab_color '#aaa'
+      inactive_text_color '#888'
+    end
+
+This puts some inline CSS into your web page to give your tabs some basic styling.  The purpose of the CSS scaffolding is quick prototyping.  It should eventually be removed and replaced by your own CSS.  Just delete the use_css_scaffolding block.
+
+Read the [REFERENCE](REFERENCE.md) for more details.
+
+### Advanced Usage
+
+You can customize the behavior of tabulous by adding a customize block inside Tabulous.setup:
+
+    customize do
+      renderer :bootstrap                      # generate Twitter Bootstrap-style HTML for tabs
+      active_tab_clickable = false             # don't allow the selected tab to be clicked
+      when_action_has_no_tab = :raise_error    # error out if there is no selected tab
+      render_subtabs_when_empty = true         # always include subtab markup, even if empty
+    end
+
+Read the [REFERENCE](REFERENCE.md) for more details.
+
+## Software Design Decisions
+
+### Controller Actions Drive Tab Selection
+
+Which tab is selected depends on the controller action that rendered the current view.  This is a deliberate design decision that works very well in the vast majority of use cases.  For the edge cases, it's usually easy enough to adjust your controller actions to conform to this expectation.
+
+### Separated
+
+Rendering a tab navigation bar is a view concern, not a controller concern, so tab-related code should not appear in controllers at all.  Also, consolidating all of the tab behavior into the tabulous.rb file keeps complex logic out of your views.
+
+### Simple
+
+Tabulous is not designed to handle all tab-related use cases.  It is designed to have features for common use cases and provide options to override default behavior.  This keeps tabulous simple enough to be learned quickly and used for easy prototyping.  Tabulous does, however, aim to be complete enough and flexible enough so that most applications will never have to replace it with custom tab code.
+
+### Harmonious
+
+Tabulous aims to integrate well in a variety of situations, which is why it supports Twitter Bootstrap, allows for you to generate custom tab HTML, and works with many versions of Rails and Ruby.
+
+### Declarative
+
+Tabulous uses a declarative DSL such as is used by config/routes.rb.  Using a declarative style makes it easy to specify _what_ your tabs should do without exposing anything about _how_ tabulous does it.  It also makes the code short and readable.

data/README.md

@@ -0,0 +1,17 @@
+# Tabulous
+
+## Description
+
+Tabulous provides an easy way to add tabs to your Rails application.
+
+## Requirements
+
+Tabulous works with Rails 3.0, 3.1, 3.2 and 4.0.  It has been tested on MRI Ruby 1.9.3 and 2.0.0.  It does not work with Ruby 1.8.
+
+## Getting Started
+
+* [OVERVIEW](OVERVIEW.md) -- if you're new to tabulous, start here
+* [CHANGES FROM VERSION ONE](CHANGES_FROM_VERSION_ONE.md) -- if you've been using version one of tabulous, read this
+* [REFERENCE](REFERENCE.md) -- complete documentation on the usage of tabulous
+* [CONTRIBUTING](CONTRIBUTING.md) -- if you want to help out
+