bettertabs 1.0 → 1.1

data/CHANGELOG

@@ -0,0 +1,30 @@
+Bettertabs Changelog
+====================
+
+
+2011-04-28  Mario Izquierdo Martinez <tothemario@gmail.com>
+  
+  * Tag v1.1
+  * Added :ajax_url option to tab builder, defaults to :url plus the ajax=true param to prevent browser cache issues.
+  * bettertabs helper :class html_option replace the 'bettertabs' default class instead of adding it (there was no way to remove that class).
+  * Bugfix: don't add .hidden CSS class to non active tabs (it should only be added to non active content).
+  * Documentation improvement:
+    * Added jquery.bettertabs documentation (REAMDE.md)
+    * Added some CSS examples and documentation (lib/bettertabs/stylesheets/README.md)
+    * README.md review and clean-up, moved examples to EXAMPLES.md.
+    * Added Routes examples (README.md)
+    * Added bettertabs helper documentation (params and options in the method comment)
+  
+2011-04-22  Mario Izquierdo Martinez <tothemario@gmail.com>
+
+  * Tag v1.0
+  * bettertabs rails helper, with static, link and ajax tabs
+  * jquery.bettertabs plugin, that activate the clicked tab, loads ajax content and change the url using HTML history.replaceState() javascript method.
+  * README.md documentation improved with examples
+  * Rails3 (ruby 1.9.2) test application (in the test folder) with some use cases and some basic rspec tests.
+  
+2011-03-31  Mario Izquierdo Martinez <tothemario@gmail.com>
+
+  * Tag v0.0.1
+  * Initial development and structure for the gem
+  * Initial documentation (README.md file)

data/EXAMPLES.md

@@ -0,0 +1,212 @@
+# Bettertabs Usage and Examples #
+
+## Link Tabs Example ##
+
+A simple tabbed content can be created using linked tabs:
+
+In view `app/views/home/simple.html.erb`:
+
+    <%= bettertabs :simpletabs do |tab| %>
+      <%= tab.link :tab1, 'Tab One' do %>
+        Hello world.
+      <% end %>
+      <%= tab.link :tab2, 'Tab Two' do %>
+        This is the <b>dark side</b> of the moon.
+      <% end %>
+    <% end %>
+
+
+This will define a linked two-tabs widget. The second tab ("Tab Two") is a link to the same url, but with the extra param `?simpletabs_selected_tab=tab2`, that will make the bettertabs helper activate the :tab2 tab.
+
+In this case no JavaScript is required, and a new request will be performed when click the tabs links.
+
+
+## Static Tabs Example ##
+
+This example will show three tabs: "Home", "Who am I?" and "Contact Me".
+The partials and files organization used in this examples are not mandatory but recommended, to make the change to ajax tabs very easy if needed.
+
+In view `app/views/home/index.html.erb`:
+
+    <h1>Static Tabs Example</h1>
+    <%= render 'mytabs' %>
+
+In partial `app/views/home/_mytabs.html.erb`:
+
+    <%= bettertabs :mytabs do |tab| %>
+      <%= tab.static :home do %>
+        <h2>Home</h2>
+        <%= raw @content_for_home %>
+      <% end %>
+      <%= tab.static :about, 'Who am I?', :partial => '/shared/about' %>
+      <%= tab.static :contact_me %>
+    <% end %>
+     
+
+The :about and :contact_me tabs will get the content from the referenced partials. Put any content there, for example:
+
+In partial `app/views/shared/_about.html.erb`:
+
+    Hello, my name is <%= @myname %>.
+
+In partial `app/views/home/_contact_me.html.erb`:
+
+    <h2>How to contact me:<h2/>
+    <p><%= @contact_info.inspect %></p>
+    
+In controller `app/controllers/home_controller.rb`:
+
+    class HomeController < ApplicationController
+
+      def index
+        # Declare instance variables as usual
+        @content_for_home = very_slow_function()
+        @myname = 'Lucifer'
+        @contact_info = { :address => 'The Hell', :telephone => '666'}
+      end
+
+    end
+
+This will work with and without JavaScript, anyway, all vars and content should be loaded in the request because all static tabs need to render its content.
+
+
+## AJAX tabs ##
+
+Ajax tabs perform an asynchronous call to get the content before showing it. Giving the tab.ajax definition:
+
+    tab.ajax :home, :url => '/home/index', :ajax_url => '/home/ajax_tab'
+
+supposing the bettertabs_id is :mytabs, it will generate the following markup for the tab item:
+
+    <li id="home_mytabs_tab">
+      <a data-tab-type="ajax" 
+         data-show-content-id="home_mytabs_content" 
+         data-ajax-url="/home/ajax_tab" 
+         href="/home/index">
+         Home
+      </a>
+    </li>
+    
+The attributes *data-tab-type*, *data-show-content-id* and *data-ajax-url* will be used by the jquery.bettertabs plugin.
+
+So here there are two important options:
+
+  * :url => The tag link href. Is used to change the browser url (html5 browsers only) and as url when JavaScript is off. Default to current url plus the param `#{bettertabs_id}_selected_tab=#{tab_id}`.
+  * :ajax_url => Defaults to :url plus the param `ajax=true`. Is used to perform the ajax request.
+  
+Both options have a default value, so if you just write:
+
+    tab.ajax :home
+
+supposing the bettertabs_id is :mytabs, and the current url is '/home', it will generate the following markup for the tab item:
+
+    <li id="home_mytabs_tab">
+      <a data-tab-type="ajax" 
+         data-show-content-id="home_mytabs_content" 
+         data-ajax-url="/home?mytabs_selected_tab=home&ajax=true" 
+         href="/home?mytabs_selected_tab=home">
+         Home
+      </a>
+    </li>
+
+In the controller you can check if you are receiving an ajax request just looking `if params[:ajax].present?`, or also using `request.xhr?` (that is a header that jQuery uses when perform an ajax request).
+
+**Note**: The :url and :ajax_url values should not be the same because some browsers fetch the cache by url (ignoring the xhr header), and if we use the same url, we may go to a page and see the last ajax response instead of the whole page.
+
+
+### Improve the Static Tabs Example with ajax ###
+
+In the previous example, `@content_for_home = very_slow_function()` has to be executed even if the user see another tab content. Using ajax or link tabs, the content is only loaded when needed.
+
+Lets create some tabs with ajax:
+
+In view `app/views/home/index.html.erb`:
+
+    <h1>Ajax Tabs Example</h1>
+    <%= render 'mytabs' %>
+
+In partial `app/views/home/_mytabs.html.erb`:
+
+    <%= bettertabs :mytabs do |tab| %>
+      <%= tab.ajax :home do %>
+        <h2>Home</h2>
+        <%= raw @content_for_home %>
+      <% end %>
+      <%= tab.ajax :about, 'Who am I?', :partial => '/shared/about' %>
+      <%= tab.ajax :contact_me %>
+    <% end %>
+     
+**Note** that the only difference between this example and the *static tabs example* is to use `tab.ajax` declaration instead of `tab.static`.
+
+Partials `app/views/shared/_about.html.erb` and `app/views/home/_contact_us.html.erb` (same as in the *static tabs example*).
+
+### The Controller Side ###
+
+In controller `app/controllers/home_controller.rb`, you can load only the needed data for each tab:
+
+    class HomeController < ApplicationController
+
+      def index
+        # Execute only the selected tab needed code (optimization).
+        case params[:mytabs_selected_tab]
+        when 'home' then
+          @content_for_home = very_slow_function()
+        when 'about' then
+          @myname = 'Lucifer'
+        when 'contact_us' then
+          @contact_info = { :address => 'The Hell', :telephone => '666'}
+        end
+        
+        # When ajax, render only the selected tab content (handled by bettertabs helper)
+        render :partial => 'mytabs' and return if request.xhr? # you can also check if params[:ajax].present?
+      end
+
+    end
+
+The only needed code in the controller to make it work with ajax is the `render :partial => 'mytabs' and return if request.xhr?` line.
+
+Since the *mytabs* partial just contains the bettertabs helper, and bettertabs helper will just render the selected content when request.xhr?, this line is enough to return the selected content to the ajax call, no matter which tab is selected (because it uses params[:mytabs_selected_tab] to select the right content to render).
+
+
+### Advantages of having the bettertabs helper alone in a separated partial ###
+
+  * It works without JavaScript out-of-the-box (using default values)
+  * Since the URL is changed in the browser when a tab is clicked and it works without JavaScript, a permalink is defined for each tab, so it allows:
+    * to bookmark the page on any selected tab
+    * to reload the page keeping the selected tab
+    * to send the link to other person and he/she will open the selected tab
+  * Easily change the behavior of a tab to be `ajax`, `static` or `link`. It always work.
+  * Keep your views DRY, clean and readable
+  
+
+## Example using HAML and ruby1.9.2 ##
+
+Is easy to mix all types of tabs, and customize them using the provided options:
+  
+    = bettertabs :bettertabs_example, :selected_tab => :chooseme, :class => 'bettertabs example' do |tab|
+    
+      = tab.static :simplest_tab, class: 'awesome-tab' do
+        Click this tab to see this content.
+        
+      = tab.static :chooseme, 'Please, Click me!' # as default, renders partial: 'chooseme'
+        
+      = tab.static :render_another_partial, partial: 'another_partial'
+      
+      = tab.link :link_to_another_place, url: go_to_other_place_url  # will make a new request
+        
+      = tab.ajax :cool_ajax, ajax_url: remote_call_path, partial: 'cool_partial'
+      -# In this case, you shoud take care of that remote_call_path is using the same partial: 'cool_partial'
+      
+      = tab.ajax :album, url: url_for(@album), partial: 'shared/album'
+      -# This one will make the ajax call to the ajax_url: url_for(@album, :ajax => true)
+      
+      = tab.ajax :ajax_tab, title: 'Content is loaded only once'
+
+
+## More documentation ##
+
+  * [Main README document](https://github.com/agoragames/bettertabs/blob/master/README.md)
+  * [Bettertabs Styles reference guide](https://github.com/agoragames/bettertabs/blob/master/lib/bettertabs/stylesheets/README.md)
+  * [Bettertabs helper](https://github.com/agoragames/bettertabs/blob/master/lib/bettertabs/bettertabs_helper.rb) (params and options)
+  * [Rails3 test demo application](https://github.com/agoragames/bettertabs/tree/master/test/ruby_1_9/rails_3_0)
+  * Anyway, don't be afraid of digging into the code, it's very straightforward.

data/README.md

@@ -6,18 +6,19 @@ We know that splitting content into several tabs is easy, but doing well, clean,
 Bettertabs is a helper for Rails that renders the markup for a tabbed area in a easy and declarative way, forcing you to keep things simple and ensuring accessibility and usability, no matter if the content is loaded statically or via ajax.
 
 
-## Features and Key Points ##
+## Features ##
 
-  * Generate markup with a rails helper and add JavaScript behavior with a jQuery plugin
+  * Rails helper to easily generate the tabs and content markup
+  * Provides a jQuery plugin to handle the JavaScript behavior
   * Simplicity: Easy to install and easy to use
+  * Flexible and customizable
   * Forces you to DRY-up your views for your tabbed content
   * Forces you to make it awesome accessible and usable:
     * Designed to work with and without JavaScript
-    * When click on a tab, the address bar url is changed (feature supported only in HTML5 browsers), so:
+    * When click on a tab, the address bar url is changed (only in HTML5 browsers), so:
       * The browser's back and reload buttons will still work as expected
       * All tabbed sections can be permalinked, keeping the selected tab
-  * Flexible and customizable
-  * Makes testing views simple. Because it works without javascript, you can assert view components with the rails built-in functional and integration tests.
+  * Makes testing views simple. Because its easy to make it works without javascript, you can assert view components with the rails built-in functional and integration tests.
   * The CSS styles are up to you.
 
 
@@ -26,7 +27,7 @@ Bettertabs is a helper for Rails that renders the markup for a tabbed area in a
   * Rails 3
   * The [Bettertabs jQuery plugin](https://github.com/agoragames/bettertabs/raw/master/lib/bettertabs/javascripts/jquery.bettertabs.min.js) (that requires [jQuery](http://jquery.com/) 1.3, 1.4 or 1.5)
 
-Although you can use bettertabs without javascript, and also should be possible to use another javascript for this, since the bettertabs helper only generates the appropiate markup.
+Although you can use bettertabs without javascript, and also it should not be so difficult to create another JavaScript that handle the server side behavior, since the bettertabs helper only generates the appropiate markup.
 
 
 ## Install ##
@@ -51,238 +52,122 @@ Bettertabs supports three kinds of tabs:
   * **Static Tabs**: Loads all content of all static tabs, but only show the active content; when click on another tab, activate its related content. When JavaScript disabled, it behaves like *link tabs*.
   * **Ajax Tabs**: Loads only the active tab contents; when click on another tab, loads its content via ajax and show. When JavaScript disabled, it behaves like *link tabs*.
 
+An usage example should be self explanatory (using HAML, but it also works with ERB and other template systems):
 
-### Link Tabs Example ###
-
-A simple tabbed content can be created using linked tabs:
-
-In view `app/views/home/simple.html.erb`:
-
-    <%= bettertabs :simpletabs do |tab| %>
-      <%= tab.link :tab1, 'Tab One' do %>
-        Hello world.
-      <% end %>
-      <%= tab.link :tab2, 'Tab Two' do %>
-        This is the <b>dark side</b> of the moon.
-      <% end %>
-    <% end %>
-
-
-This will define a linked two-tabs widget. The second tab ("Tab Two") is a link to the same url, but with the extra param `?simpletabs_selected_tab=tab2`, that will make the bettertabs helper activate the :tab2 tab.
-
-In this case no JavaScript is required, and a new request will be performed when click the tabs links.
-To change this to a javascript static tabs, you only need to change `tab.link` declarations for `tab.static`.
-To change this to ajax tabs, in this case, is only needed to change the `tab.link` declarations for `tab.ajax`.
-
-
-### Static Tabs Example ###
-
-This example will show three tabs: "Home", "Who am I?" and "Contact Me".
-The partials and files organization used in this examples are not mandatory but recommended, it will make easier to change to ajax tabs if needed.
-
-In view `app/views/home/index.html.erb`:
-
-    <h1>Static Tabs Example</h1>
-    <%= render 'mytabs' %>
-
-In partial `app/views/home/_mytabs.html.erb`:
-
-    <%= bettertabs :mytabs do |tab| %>
-      <%= tab.static :home do %>
-        <h2>Home</h2>
-        <%= raw @content_for_home %>
-      <% end %>
-      <%= tab.static :about, 'Who am I?', :partial => '/shared/about' %>
-      <%= tab.static :contact_me %>
-    <% end %>
-     
-
-The :about and :contact_me tabs will get the content from the referenced partials. Put any content there, for example:
-
-In partial `app/views/shared/_about.html.erb`:
+    = bettertabs :profile_tabs do |tab|
+      = tab.static :general, 'My Profile' do
+        %h2 General Info
+        = show_user_general_info(@user)
+          
+      = tab.ajax :friends, :partial => 'shared/friends'
+      
+      = tab.link :groups do
+        =  render :partial => 'groups/user_groups', :locals => {user => @user}
 
-    Hello, my name is <%= @myname %>.
+### More examples and documentation: ###
 
-In partial `app/views/home/_contact_me.html.erb`:
+  * [EXAMPLES document](https://github.com/agoragames/bettertabs/blob/master/EXAMPLES.md)
+  * [Bettertabs Styles reference guide](https://github.com/agoragames/bettertabs/blob/master/lib/bettertabs/stylesheets/README.md)
+  * [Bettertabs helper](https://github.com/agoragames/bettertabs/blob/master/lib/bettertabs/bettertabs_helper.rb) (params and options)
+  * [Rails3 test demo application](https://github.com/agoragames/bettertabs/tree/master/test/ruby_1_9/rails_3_0)
+  * Anyway, don't be afraid of digging into the code, it's very straightforward.
+  
 
-    <h2>How to contact me:<h2/>
-    <p><%= @contact_info.inspect %></p>
-    
-In controller `app/controllers/home_controller.rb`:
+## Tabs Routes ##
 
-    class HomeController < ApplicationController
+By default, all tab links have the current url plus the `{bettertabs_id}_selected_tab` param with the tab_id value.
 
-      def index
-        # Declare instance variables as usual
-        @content_for_home = very_slow_function()
-        @myname = 'Lucifer'
-        @contact_info = { :address => 'The Hell', :telephone => '666'}
-      end
+For example, if you are rendering the next bettertabs widget:
 
-    end
+    = bettertabs :profile_tabs do |tab|
+      = tab.static :general
+      = tab.static :friends
 
-This will work with and without JavaScript, anyway, all vars and content should be loaded in the request because all static tabs need to render its content.
+in a view accessible by a route like this:
 
+    match 'profile/:nickname', :to => 'profiles#lookup', :as => 'profile'
 
-### Improve with AJAX ###
+When you go to `/profile/dude`, your tabs links will have the following hrefs: 
 
-Ajax tabs call the same URL as link tabs but loading the content asynchronously.
+  * :general tab href: `/profile/dude?profile_tabs_selected_tab=general`
+  * :friends tab href: `/profile/dude?profile_tabs_selected_tab=friends`
 
-In the previous example, `@content_for_home = very_slow_function()` has to be executed even if the user see another tab content. Using ajax or link tabs, the content is only loaded when needed.
+If you're in a modern HTML5 browser then when click on a tab, the URL will change for one of the urls listed before (jquery.bettertabs), otherwise, you can turn the JavaScript off and the static tabs will become link tabs, so the URL will change as well.
 
-Lets create some tabs with ajax:
+To show a pretty url, you can just modify your named route to:
 
-In view `app/views/home/index.html.erb`:
+    match 'profile/:nickname(/:profile_tabs_selected_tab)', :to => 'profiles#lookup', :as => 'profile'
 
-    <h1>Ajax Tabs Example</h1>
-    <%= render 'mytabs' %>
+So now the tabs links will point to the following URLs:
 
-In partial `app/views/home/_mytabs.html.erb`:
+  * :general tab href: `/profile/dude/general`
+  * :friends tab href: `/profile/dude/friends`
+  
+  
+## JavaScript with the jquery.bettertabs plugin ##
 
-    <%= bettertabs :mytabs do |tab| %>
-      <%= tab.ajax :home do %>
-        <h2>Home</h2>
-        <%= raw @content_for_home %>
-      <% end %>
-      <%= tab.ajax :about, 'Who am I?', :partial => '/shared/about' %>
-      <%= tab.ajax :contact_me %>
-    <% end %>
-     
-**Note** that the only difference between this example and the *static tabs example* is to use `tab.ajax` declaration instead of `tab.static`.
+Installing the `bettertabs` gem in a rails project makes the bettertabs helper instantly available. This helper will generate markup that is prepared to be modified by JavaScript, and also includes an inline script at the bottom:
 
-Partials `app/views/shared/_about.html.erb` and `app/views/home/_contact_us.html.erb` (same as the static tabs example).
-    
-In controller `app/controllers/home_controller.rb`, you can load only the needed data for each tab:
+    jQuery(function($){ $('#bettertabs_id').bettertabs(); });
 
-    class HomeController < ApplicationController
+Which expects jQuery and jquery.bettertabs plugin to be loaded.
 
-      def index
-        # Execute only the selected tab needed code (optimization).
-        case params[:mytabs_selected_tab]
-        when 'home' then
-          @content_for_home = very_slow_function()
-        when 'about' then
-          @myname = 'Lucifer'
-        when 'contact_us' then
-          @contact_info = { :address => 'The Hell', :telephone => '666'}
-        end
-        
-        # When ajax, load only the selected tab content (handled by bettertabs helper)
-        respond_to do |format|
-          format.js { render :partial => 'mytabs' } # when ajax call, bettertabs only renders the active content.
-        end
-      end
+The jquery.bettertabs plugin can be downloaded directly from the github repo:
 
-    end
+  * [CoffeeScript version](https://github.com/agoragames/bettertabs/raw/master/lib/bettertabs/javascripts/jquery.bettertabs.coffee)
+  * [JavaScript (generated by coffee) version](https://github.com/agoragames/bettertabs/raw/master/lib/bettertabs/javascripts/jquery.bettertabs.js)
+  * [Compressed JavaScript](https://github.com/agoragames/bettertabs/raw/master/lib/bettertabs/javascripts/jquery.bettertabs.min.js)
+  
+The plugin defines one single jQuery method `jQuery(selector).bettertabs();` that is applied to the generated markup.
 
-The only needed code in the controller to make it work with ajax is the `format.js { render :partial => 'mytabs' }` line.
+This script will take the tab type from each tab link `data-tab-type` attribute (that can be "link", "static" or "ajax"), and will match each tab with its content using the tab link `data-show-content-id` attribute, that is the id of the related content.
 
-Since the *_mytabs* partial only contains the bettertabs helper, and bettertabs helper only renders the selected content when ajax call, this line is enough to return the selected content to the ajax call.
+Tabs of type "link" will be ignored (no JavaScript), while "static" and "ajax" tabs will change the active content (using the `.active` css class), and also will try to change the current URL.
 
-#### Advantages if you follow this file structure ####
 
-Having the bettertabs helper in a separated partial gives you the following advantages:
+### Browser history and url manipulation ###
 
-  * It works without JavaScript out-of-the-box
-  * Since the URL is changed in the browser when a tab is clicked and it works without JavaScript, a permalink is defined for each tab, so it allows:
-    * to bookmark the page on any selected tab
-    * to reload the page keeping the selected tab
-  * Easily change the behavior of a tab to be `ajax`, `static` or `link`. It always work.
-  * Keep your views DRY, clean and readable
+When activate a tag, the URL is changed using [history.replaceState()](https://developer.mozilla.org/en/DOM/Manipulating_the_browser_history), which only works on modern HTM5 browsers (older browsers can not change the URL, and I prefer not trying to use History.js or any other approach to give them support for them).
 
+### Manipulating the bettertabs widget from other scripts ###
 
-### Mixed Example ###
+All parts of the bettertabs generated markup are identified using ids, so it is very easy to identify and modify any part of the inner content (just open your firebug and browse the generated markup).
 
-Is easy to mix all types of tabs, and customize them using the provided options. For example (Using ruby 1.9.2 with HAML):
+  * To activate a tab, simulate a click on the tab link: `jQuery('#bettertabsid_tabid_tab a').click();`
+  * To hook some behavior when someone clicks on a tab, attach a 'click' handler to the tab link or use any of the provided custom events.
+  * To show a loading clock or any other kind of feedback to the user while ajax is loading, use any of the provided custom events.
   
-    = bettertabs :bettertabs_example, :selected_tab => :chooseme do |tab|
-      = tab.static :simplest_tab, class: 'awesome-tab' do
-        Click this tab to see this content.
-        
-      = tab.static :chooseme, 'Please, Click me!' # as default, renders partial: 'chooseme'
-        
-      = tab.static :render_another_partial, partial: 'another_partial'
-      
-      = tab.link :link_to_another_place, url: go_to_other_place_url  # will make a new request
-        
-      = tab.ajax :simple_ajax, title: 'Content is loaded when needed and only once.'
-      
-      = tab.ajax :album, url: show_remote_album_path, partial: 'shared/album'
-        
-
-#### From the Controller: ####
-
-The default tab :url option value is the current path but with `param[:"{bettertabs_id}_selected_tab"]` to the current tab id.
-This means that, by default, you can handle all needed information in the same controller action for all tab contents. Of course you can change this using a different value for the :url option.
-
-If the tab is ajax, the ajax call will be performed to the same url provided in the :url option.
-You can know if a call is ajax checking if `controller.request.xhr?` is true.
+Custom events that are attached to each tab content:
+
+  * 'bettertabs-before-deactivate':   fired on content that is active and will be deactivated
+  * 'bettertabs-before-activate':     fired on content that will be activated
+  * 'bettertabs-before-ajax-loading': fired on content container that will be activated just before be loaded using ajax
+  * 'bettertabs-after-deactivate':    fired on content that was deactivated
+  * 'bettertabs-after-activate':      fired on content that was activated
+  * 'bettertabs-after-ajax-loading':  fired on content after it was loaded via ajax. Remember that the content is loaded via ajax only once.
+  
+If you want to do something on a content that was just loaded using ajax, you can do something like the following:
 
-So, if `request.xhr?` is *true* then you should render a partial to be used as content.
+    $("#bettertabsid_tabid_content").bind('bettertabs-after-ajax-loading', function(){
+      $(this).doSomething();
+    });
 
-If `request.xhr?` is *false* then you can just render the action as usual, bettertabs helper will auto select the appropriate tab based on `params[:"{bettertabs_id}_selected_tab"]` value.
 
-When a call is AJAX, the bettertabs helper only render the active content (no tabs, no wrappers, no other content), so you can just render the partial where the bettertabs helper is used and it will work for any selected tab.
+## CSS Styles ##
 
-You can write your controller code as follows, assuming that bettertabs_id is :example, and it's placed alone in the partial 'bettertabs_example':
+Bettertabs provides a rails helper to generate HTML and a jQuery plugin as JavaScript, but not any CSS styles because those are very different for each project and can not be abstracted into a common purpose CSS stylesheet.
+  
+Perhaps the most important CSS rule here is to define `display: none;` for `div.content.hidden`, because contents are never hidden using the jquery.hide() method or similar. The jquery.bettertabs plugin just adds the `.active` class to the active tab and active content, and the `.hidden` class to the non active content. You will need to use a CSS rule like this:
 
-    def show_bettertabs_example
-      @common_for_all_tabs = code_here
-    
-      # A simple way of execute code only for the selected tab.
-      # Note that static tabs are always rendered, even if they are not selected.
-      case params[:example_selected_tab]
-      when 'chooseme' then
-        code_only_for_this_tab
-      else
-        code_for_all_other_tabs
-      end
-      
-      # Ready for ajax ...
-      # You can check request.xhr? or use the common method respond_to
-      respond_to do |format|
-        format.js { render :partial => 'bettertabs_example' } # render only the selected content
-      end
-    end
+      div.bettertabs div.content.hidden { display: none; }
 
+Use the [Bettertabs Styles Reference Guide](https://github.com/agoragames/bettertabs/blob/master/lib/bettertabs/stylesheets/README.md) to get a stylesheet that you can use as a starting point.
 
 
-## TODO ##
+## Future work ##
 
-  * Improve the Rails testing application.
+  * Improve the Rails testing application
     * it should use rspec and capybabra to test even the javascript (http://media.railscasts.com/videos/257_request_specs_and_capybara.mov)
     * Try to make it work with ruby 1.8.x
-  * Create a basic CSS stylesheet that may serve as base (and add the links here in the documentation)
+  * Allow disabling the change-url functionality with an option like `:change_browser_url => false`
   
-  
-## Current Spec sheet (will become automatic tests) ##
-  * Should always work with javascript disabled (using the urls of the tabs links)
-  * The bettertabs hepler should accept:
-    * args: (bettertabs_id, options)
-    * options can be:
-       * :selected_tab => tab_id to select by default
-         * :selected_tab should be overridden with params[:"#{bettertabs_id}_selected_tab"] if present
-       * any other option is used as wrapper html_options (wrapper is the top-level widget dom element).
-  * The bettertabs helper should render clear markup:
-     * A wrapper with class 'bettertabs'
-     * Tabs markup
-        * ul.tabs > li > a  
-        * selected tab is ul.tabs > li.active > a
-        * each a element has element attributes:
-           * data-tab-type (for javascript: change click behavior depending on type "static", "link" or "ajax")
-           * data-show-content-id (for javascript: element id to show when select this tab)
-     * sections for each tab content.
-     * use a unique html id (based on bettertabs_id and tab_id) for each Tab and Content
-  * The bettertabs builder ".from" method should accept:
-     * args: (tab_id, tab_name, options, &block)
-     * args: (tab_id, options, &block)
-    * If block_given? the block is used as content related to this tab
-     * options can be:
-       * :partial => to use as content. Defaults to tab_id
-          * if block_given? this option can not be used (if used, raise an error)
-       * :url => for the tab link, that should go to this selected tab when javascript is disabled. Defaults to { :"#{bettertabs_id}_selected_tab" => tab_id }
-       * :tab_type => used in the markup as the link data-tab-type value. Can be :static, :link or :ajax (or the corresponding strings). Raise error otherwise. Defaults to :static.
-  * The bettertabs builder ".static", ".link" and ".ajax" methods are only a convenient way to use ".for" method with :tab_type set to :static, :link or :ajax respectively.
-  * Content is rendered only for active tab, except when tab_type is :static, where content is always rendered (ready to show when select that tab using javascript).
-  * When ajax call (format.js), the bettertabs helper should return ONLY the content of the selected tab (to simplify the controller render partial calls.).
-