bettertabs 1.0 → 1.1

data/bettertabs.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |s|
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Mario Izquierdo"]
   s.email       = ["tothemario@gmail.com"]
-  s.homepage    = ""
-  s.summary     = %q{The better (simple, accessible, usable, flexible and fast) way to split content in tabs.}
-  s.description = %q{The bettertabs helper defines the markup for a tabbed area in a easy and declarative way, using the appropiate JavaScript but ensuring accessibility and usability, no matter if the content is loaded statically, via ajax or the tabs are links. In the other hand, the CSS styles are up to you. }
+  s.homepage    = "https://github.com/agoragames/bettertabs"
+  s.summary     = %q{The better (simple, accessible, usable, flexible and fast) way to split content in tabs for Rails.}
+  s.description = %q{Bettertabs Rails helper (and jQuery plugin) defines the markup for a tabbed area in a easy and declarative way, using the appropiate JavaScript but ensuring accessibility and usability, no matter if the content is loaded statically, via ajax or the tabs are links. In the other hand, the CSS styles are up to you. }
 
   s.rubyforge_project = "bettertabs"
 

data/lib/bettertabs/bettertabs_builder.rb

@@ -1,4 +1,5 @@
 class BettertabsBuilder
+  require 'uri' # from standard library
   
   TAB_TYPE_STATIC = :static
   TAB_TYPE_LINK = :link
@@ -45,6 +46,7 @@ class BettertabsBuilder
     url = options.delete(:url) || { :"#{@bettertabs_id}_selected_tab" => tab_id }
     tab_type = (options.delete(:tab_type) || TAB_TYPE_STATIC).to_sym
     raise "Bettertabs: #{tab_type.inspect} tab type not supported. Use one of #{TAB_TYPES.inspect} instead." unless TAB_TYPES.include?(tab_type)
+    ajax_url = options.delete(:ajax_url) || url_for_ajax(url) if tab_type == TAB_TYPE_AJAX
     @selected_tab_id ||= tab_id # defaults to first tab
     
     if @render_only_active_content
@@ -54,7 +56,7 @@ class BettertabsBuilder
     else
       # Tabs
       tab_html_options = options # any other option will be used as tab html_option
-      @tabs << { tab_id: tab_id, text: tab_text, url: url, html_options: tab_html_options, tab_type: tab_type, active: active?(tab_id) }
+      @tabs << { tab_id: tab_id, text: tab_text, url: url, ajax_url: ajax_url, html_options: tab_html_options, tab_type: tab_type, active: active?(tab_id) }
     
       # Content
       content_html_options = { id: content_html_id_for(tab_id), class: "content #{active?(tab_id) ? 'active' : 'hidden'}" }
@@ -65,7 +67,7 @@ class BettertabsBuilder
       end
       @contents << { tab_id: tab_id, tab_text: tab_text, content: content, html_options: content_html_options, tab_type: tab_type, active: active?(tab_id) }
     end
-    nil
+    nil # returning nil allows the user to call this using <%= tab.for :xxx %> or <% tab.for :xxx %>
   end
   
   # Renders the bettertabs markup.
@@ -103,6 +105,7 @@ class BettertabsBuilder
              tag(:li, class: ('active' if tab[:active]), id: tab_html_id_for(tab[:tab_id])) do
                tab[:html_options][:"data-tab-type"] ||= tab[:tab_type] # for javascript: change click behavior depending on type :static, :link or :ajax
                tab[:html_options][:"data-show-content-id"] ||= content_html_id_for(tab[:tab_id]) # for javascript: element id to show when select this tab
+               tab[:html_options][:"data-ajax-url"] ||= tab[:ajax_url] if tab[:tab_type] == TAB_TYPE_AJAX # for javascript: url to make ajax call
                @template.link_to(tab[:text], tab[:url], tab[:html_options])
              end
            end.join.html_safe
@@ -123,16 +126,6 @@ class BettertabsBuilder
   
   private
   
-  # Alias of @template.content_tag
-  def tag(name, content_or_options_with_block = nil, options = nil, escape = true, &block)
-    @template.content_tag(name, content_or_options_with_block, options, escape, &block)
-  end
-  
-  # Wraps javascript code inside a javascript_tag using the jQuery(function($){ ... }); on init call.
-  def jquery_tag(jquery_code)
-    @template.javascript_tag("jQuery(function($){ #{ jquery_code } });")
-  end
-  
   # Get the options hash from an array of args. If options are not present, create them and initialize to {}
   def get_options(args)
     args << {} unless args.last.is_a?(Hash)
@@ -159,4 +152,31 @@ class BettertabsBuilder
     "#{tab_id}_#{@bettertabs_id}_content"
   end
   
+  # Alias of @template.content_tag
+  def tag(name, content_or_options_with_block = nil, options = nil, escape = true, &block)
+    @template.content_tag(name, content_or_options_with_block, options, escape, &block)
+  end
+  
+  # Wraps javascript code inside a javascript_tag using the jQuery(function($){ ... }); on init call.
+  def jquery_tag(jquery_code)
+    @template.javascript_tag("jQuery(function($){ #{ jquery_code } });")
+  end
+  
+  # Uses @template.url_for() to create the string url, and then URI.parse to add the ajax=true extra param.
+  # This "ajax=true" extra param is important for two reasons:
+  #   * It makes easier from the controller to know when a request is ajax or not.
+  #   * It prevents the browser cache to be populated with the ajax response in the same URL as the complete page,
+  #     otherwhise when the user makes an ajax call, goes to another page and click the back button they see only the ajax response (browsers bug?).
+  def url_for_ajax(options)
+    original_url = @template.url_for(options)
+    begin
+      ajax_param = 'ajax=true'
+      uri = URI.parse original_url # URI from ruby standard library
+      uri.query = uri.query.blank? ? ajax_param : "#{uri.query}&#{ajax_param}".html_safe
+      uri.to_s
+    rescue URI::InvalidURIError
+      original_url
+    end
+  end
+  
 end

data/lib/bettertabs/bettertabs_helper.rb

@@ -1,11 +1,55 @@
 module BettertabsHelper
 
-  # Bettertabs helper
-  # Defines the bettertabs markup in the view.
+  # bettertabs(bettertabs_id, options={})
+  # Bettertabs helper that generates tabs and content markup.
+  #
+  # === Example
+  #     = bettertabs :bettertabs_id do |tab|
+  #       - tab.link :tab1_id, 'Tab1', options1
+  #       - tab.static :tab2_id, 'Tab2', options2
+  #       - tab.ajax :tab3_id, 'Tab3', options3
+  #
+  # === bettertabs params
+  #   * bettertabs_id: will be used as html id of the wrapper element, and as part of the inner ids.
+  #                     Note: is usually better to use a Symbol (with underscores) here to avoid problems defining routes.
+  #   * options:
+  #       * :selected_tab => tab_id of the default selected tab.
+  #                       This is overriden by the appropiate param params[:"#{bettertabs_id}_selected_tab"], 
+  #                       so any tab can be selected using the URL parmas. 
+  #                       :selected_tab only defines which tab is selected when no {bettertabs_id}_selected_tab param is present.
+  #       * :render_only_active_content => if true, this helper renders only the selected tab contents (no wrapper, no tabs, only content).
+  #                       Default to true only if controller.request.xhr? or params[:ajax].present? (true when its an ajax request).
+  #       * :class => html class attribute of the wrapper element. By default is 'bettertabs'
+  #       * :id => html id attribute of the wrapper element. By default is the bettertabs_id
+  #       * Any other option will be used as wrapper elmenet html attribute.
+  #
+  # ==== tab builder params
+  # Tab builder descriptor:
+  #     tab.link(tab_id, options={}, &block)
+  #     tab.link(tab_id, tab_text, options={}, &block)
+  #
+  # Params:
+  #   * tab_id: the tab item html id will be "#{tab_id}_#{bettertabs_id}_tab", 
+  #                     and the content wrapper id will be "#{tab_id}_#{bettertabs_id}_content".
+  #                     Also the tab_id is used to identify this tab in the bettertabs :selected_tab option.
+  #   * tab_text: is the content of the tab link. Defaults to tab_id.to_s.titleize
+  #   * options:
+  #       * :partial => Partial to render as content. Defaults to *tab_id*, but if &block given it captures the block instead of render partial.
+  #                     If you need to suply locals to the partial, use a block with a render(:partial => partial, :locals => {locals}) call.
+  #       * :url => href of the tab link. For link tabs, this is the href to go when click.
+  #                 For ajax and static tabs, this is the url to replace in the browser when click (HTML5 history.replaceState()), and also the url
+  #                 to use if JavaSciprt is disabled. 
+  #                 Defaults to { :"#{bettertabs_id}_selected_tab" => tab_id }, that is the current URL plus the selected tab param.
+  #       * :ajax_url => used as data-ajax-url html5 attribute in the link tab, that will be used in the jquery.bettertabs plugin as ajax href where to
+  #                 make the ajax request to get the tab content.
+  #                 By default is the same as the provided :url option, plus the { :ajax => true } param.
+  #                 Note: This extra param makes the :url and :ajax_url different for the browser and prevents a cache mistake,
+  #                 otherwise the browser may fetch the url cache with the ajax response, producing a bug when visiting again the same page.
+  #
   def bettertabs(bettertabs_id, options={})
     bettertabs_id = bettertabs_id.to_s
     selected_tab_id = params[:"#{bettertabs_id}_selected_tab"] || options.delete(:selected_tab)
-    options[:class] = "bettertabs #{options[:class]}" # keep 'bettertabs' class even when the user adds more classes.
+    options[:class] ||= "bettertabs"
     options[:id] ||= bettertabs_id
     options[:render_only_active_content] = true if controller.request.xhr?
     builder = BettertabsBuilder.new(bettertabs_id, self, selected_tab_id, options)

data/lib/bettertabs/javascripts/jquery.bettertabs.coffee

@@ -21,6 +21,7 @@ $ = jQuery
 
 tab_type_attr = 'data-tab-type' # attribute on tab links that indicate the tab type
 show_content_id_attr = 'data-show-content-id' # attribute on tab links that indicate the related content id
+ajax_url_attr = 'data-ajax-url' # attribute on ajax tab liks with the ajax href
 tab_type_of = ($tab_link) -> $tab_link.attr(tab_type_attr)
 content_id_from = ($tab_link) -> $tab_link.attr(show_content_id_attr)
 
@@ -50,8 +51,9 @@ $.fn.bettertabs = ->
           previous_active_tab = tabs.filter '.active'
           previous_active_tab_content = tabs_contents.filter '.active'
           activate_tab_and_content = ->
-            tabs_and_contents.removeClass('active').addClass('hidden')
-            this_tab.removeClass('hidden').addClass('active')
+            tabs.removeClass('active')
+            tabs_contents.removeClass('active').addClass('hidden')
+            this_tab.addClass('active')
             this_tab_content.removeClass('hidden').addClass('active')
             previous_active_tab_content.trigger 'bettertabs-after-deactivate'
             this_tab_content.trigger 'bettertabs-after-activate'
@@ -63,7 +65,7 @@ $.fn.bettertabs = ->
           if tab_type_of(this_link) is 'ajax' and not this_link.data('content-loaded-already')?
             this_link.addClass('ajax-loading')
             this_tab_content.trigger 'bettertabs-before-ajax-loading'
-            this_tab_content.load this_link.attr('href'), ->
+            this_tab_content.load this_link.attr(ajax_url_attr), ->
               this_link.removeClass('ajax-loading')
               this_link.data('content-loaded-already', yes)
               this_tab_content.trigger 'bettertabs-after-ajax-loading'

data/lib/bettertabs/javascripts/jquery.bettertabs.js

@@ -16,10 +16,11 @@
       'bettertabs-after-activate':      fired on content that was activated
       'bettertabs-after-ajax-loading':  fired on content after it was loaded via ajax
 
-  */  var $, change_url, content_id_from, show_content_id_attr, tab_type_attr, tab_type_of;
+  */  var $, ajax_url_attr, change_url, content_id_from, show_content_id_attr, tab_type_attr, tab_type_of;
   $ = jQuery;
   tab_type_attr = 'data-tab-type';
   show_content_id_attr = 'data-show-content-id';
+  ajax_url_attr = 'data-ajax-url';
   tab_type_of = function($tab_link) {
     return $tab_link.attr(tab_type_attr);
   };
@@ -52,8 +53,9 @@
             previous_active_tab = tabs.filter('.active');
             previous_active_tab_content = tabs_contents.filter('.active');
             activate_tab_and_content = function() {
-              tabs_and_contents.removeClass('active').addClass('hidden');
-              this_tab.removeClass('hidden').addClass('active');
+              tabs.removeClass('active');
+              tabs_contents.removeClass('active').addClass('hidden');
+              this_tab.addClass('active');
               this_tab_content.removeClass('hidden').addClass('active');
               previous_active_tab_content.trigger('bettertabs-after-deactivate');
               this_tab_content.trigger('bettertabs-after-activate');
@@ -64,7 +66,7 @@
             if (tab_type_of(this_link) === 'ajax' && !(this_link.data('content-loaded-already') != null)) {
               this_link.addClass('ajax-loading');
               this_tab_content.trigger('bettertabs-before-ajax-loading');
-              return this_tab_content.load(this_link.attr('href'), function() {
+              return this_tab_content.load(this_link.attr(ajax_url_attr), function() {
                 this_link.removeClass('ajax-loading');
                 this_link.data('content-loaded-already', true);
                 this_tab_content.trigger('bettertabs-after-ajax-loading');

data/lib/bettertabs/stylesheets/README.md

@@ -0,0 +1,80 @@
+Bettertabs CSS guidelines
+=========================
+
+Bettertabs provides a rails helper and a jQuery plugin. Styles are so different between projects and can not be abstracted into a common purpose CSS stylesheet.
+
+The best way to style up this is watching at the generated markup and style it according to your application styles.
+
+The following bettertabs declaration (haml):
+
+    = bettertabs :profile_tabs do |tab|
+      = tab.static :general do
+        General info of this profile
+        
+      = tab.ajax :friends, "Dudes" do
+        Friends (loaded using AJAX)
+       
+will expand in the following markup (html):
+
+    <div id="profile_tabs" data-initial-active-tab-id="profile_tabs_general_tab" class="bettertabs">
+      <ul class="tabs">
+        <li id="profile_tabs_general_tab" class="active">
+          <a data-tab-type="static" data-show-content-id="profile_tabs" href="/profile/dude/general">General</a>
+        </li>
+        <li id="profile_tabs_friends_tab">
+          <a data-tab-type="ajax" data-show-content-id="profile_tabs" href="/competition/ladder/1234/rules">RULES</a>
+        </li>
+      </ul>
+      
+      <div id="profile_tabs_general_content" class="content active">
+        General info of this profile
+      </div>
+      
+      <div id="profile_tabs_friends_content" class="content hidden">
+      </div>
+    </div>
+    
+So you can use this structure to access any bettertabs widget element (CSS):
+
+    div.bettertabs { /* Wrapper DIV (Note: this is the default class, but it can be modified in the helper html_options) */ }
+
+    div.bettertabs ul.tabs { /* tabs list */ }
+    div.bettertabs ul.tabs li { /* tab item */ }
+    div.bettertabs ul.tabs li.active { /* selected tab item */ }
+    div.bettertabs ul.tabs li.active a  { /* selected tab link */ }
+    div.bettertabs ul.tabs li a:link,
+    div.bettertabs ul.tabs li a:visited { /* tab link normal state */ }
+    div.bettertabs ul.tabs li a:hover {  }
+    div.bettertabs ul.tabs li a:active {  }
+    div.bettertabs ul.tabs li a.ajax-loading { /* tab link while ajax loading */ }
+
+    div.bettertabs div.content { }
+    div.bettertabs div.content.hidden { /* hidden content. Here you can use the property display: none; */ } 
+    div.bettertabs div.content.active { /* active content */ }
+    
+Here you are a simple example of CSS you can use to style up your bettertabs widgets (CSS):
+    
+    div.bettertabs { margin: 1em; width: 500px; }
+
+    div.bettertabs ul.tabs { margin: 0; padding: 0; position: relative; }
+    div.bettertabs ul.tabs li { 
+      background-color: #ccc;
+      border: 1px solid #999;
+      display: inline; float: left; height: 24px; line-height: 24px;
+      list-style: none outside none; 
+      margin-right: .5em; padding-right: .5em; padding-left: .5em; 
+      position: relative; top: 1px;
+    }
+    div.bettertabs ul.tabs li.active { height: 25px; background-color: #eee; border-bottom: none; }
+    div.bettertabs ul.tabs li.active a  { color: black; }
+
+    div.bettertabs ul.tabs li a { font-size: 80%; text-decoration: none; float: left; }
+    div.bettertabs ul.tabs li a:link,
+    div.bettertabs ul.tabs li a:visited { color: #444; }
+    div.bettertabs ul.tabs li a:hover { color: #000; }
+    div.bettertabs ul.tabs li a:active { color: #933; }
+    div.bettertabs ul.tabs li a.ajax-loading { color: #666; }
+
+    div.bettertabs div.content { padding: 1em; border: 1px solid #999; background-color: #eee; clear: left; }
+    div.bettertabs div.content.hidden { display: none; }
+

data/lib/bettertabs/version.rb

@@ -1,3 +1,3 @@
 module Bettertabs
-  VERSION = "1.0"
+  VERSION = "1.1"
 end

data/test/ruby_1_9/rails_3_0/Gemfile.lock

@@ -30,17 +30,17 @@ GEM
     activesupport (3.0.6)
     archive-tar-minitar (0.5.2)
     arel (2.0.9)
-    bettertabs (0.0.1)
+    bettertabs (1.1)
     builder (2.1.2)
     columnize (0.3.2)
     diff-lcs (1.1.2)
     erubis (2.6.6)
       abstract (>= 1.0.0)
-    haml (3.0.25)
+    haml (3.1.1)
     i18n (0.5.0)
     linecache19 (0.5.12)
       ruby_core_source (>= 0.1.4)
-    mail (2.2.15)
+    mail (2.2.19)
       activesupport (>= 2.3.6)
       i18n (>= 0.4.0)
       mime-types (~> 1.16)
@@ -92,7 +92,7 @@ GEM
     thor (0.14.6)
     treetop (1.4.9)
       polyglot (>= 0.3.1)
-    tzinfo (0.3.26)
+    tzinfo (0.3.27)
 
 PLATFORMS
   ruby

data/test/ruby_1_9/rails_3_0/app/views/bettertabs/_ajax.html.haml

@@ -1,6 +1,6 @@
 = bettertabs :ajax do |tab|
   = tab.ajax :ajax_tab_1 do
-    Content for the link tab
+    Content for the ajax_tab_1
   = tab.ajax :ajax_tab_2 do
-    Content for the static tab
+    Content for the ajax_tab_2
   = tab.ajax :ajax_tab_3, partial: 'tab_content'

data/test/ruby_1_9/rails_3_0/app/views/bettertabs/_link.html.haml

@@ -1,4 +1,4 @@
-= bettertabs :link, class: 'link_class', selected_tab: selected_tab do |tab|
+= bettertabs :link, class: 'bettertabs link_tabs', selected_tab: selected_tab do |tab|
   = tab.link :tab1, 'Tab One', url: { action: 'link_tab_1' } do
     Hello World!
   = tab.link :tab2, 'Tab Two', partial: 'tab_content', url: { action: 'link_tab_2' }

data/test/ruby_1_9/rails_3_0/app/views/layouts/application.html.erb

@@ -3,7 +3,7 @@
 <head>
   <title>Rails30</title>
   <%= stylesheet_link_tag 'layout', 'bettertabs' %>
-  <%= javascript_include_tag 'jquery-1.5.2.min', 'rails', 'jquery.bettertabs.min' %>
+  <%= javascript_include_tag 'jquery-1.5.2.min', 'rails', 'jquery.bettertabs' %>
   <%= csrf_meta_tag %>
 </head>
 <body>

data/test/ruby_1_9/rails_3_0/public/javascripts/jquery.bettertabs.js

@@ -0,0 +1,83 @@
+(function() {
+  /*
+  Bettertabs jQuery plugin v1.0
+
+  jQuery(selector).bettertabs(); adds javascript to change content when click on tabs.
+
+  Markup needed, the same that is generated by the rails bettertabs helper, added by the bettertabs plugin
+      https://github.com/agoragames/bettertabs
+
+  Events: Each time a tab is selected, some events are fired, so you can easily activate
+  behavior from another jquery script (using .bind); The available events are:
+      '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 that will be activated and needs ajax loading
+      '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
+
+  */  var $, ajax_url_attr, change_url, content_id_from, show_content_id_attr, tab_type_attr, tab_type_of;
+  $ = jQuery;
+  tab_type_attr = 'data-tab-type';
+  show_content_id_attr = 'data-show-content-id';
+  ajax_url_attr = 'data-ajax-url';
+  tab_type_of = function($tab_link) {
+    return $tab_link.attr(tab_type_attr);
+  };
+  content_id_from = function($tab_link) {
+    return $tab_link.attr(show_content_id_attr);
+  };
+  change_url = function($link) {
+    var url;
+    if ((typeof history != "undefined" && history !== null) && (history.replaceState != null)) {
+      url = $link.attr('href');
+      return history.replaceState(null, document.title, url);
+    }
+  };
+  $.fn.bettertabs = function() {
+    return this.each(function() {
+      var mytabs, tabs, tabs_and_contents, tabs_contents, tabs_links;
+      mytabs = $(this);
+      tabs = mytabs.find('ul.tabs > li');
+      tabs_links = mytabs.find('ul.tabs > li > a');
+      tabs_contents = mytabs.children('.content');
+      tabs_and_contents = tabs.add(tabs_contents);
+      return tabs_links.click(function(event) {
+        var activate_tab_and_content, previous_active_tab, previous_active_tab_content, this_link, this_tab, this_tab_content;
+        this_link = $(this);
+        if (tab_type_of(this_link) !== 'link') {
+          event.preventDefault();
+          this_tab = this_link.parent();
+          if (!this_tab.is('.active') && !this_link.is('.ajax-loading')) {
+            this_tab_content = tabs_contents.filter("#" + (content_id_from(this_link)));
+            previous_active_tab = tabs.filter('.active');
+            previous_active_tab_content = tabs_contents.filter('.active');
+            activate_tab_and_content = function() {
+              tabs.removeClass('active');
+              tabs_contents.removeClass('active').addClass('hidden');
+              this_tab.addClass('active');
+              this_tab_content.removeClass('hidden').addClass('active');
+              previous_active_tab_content.trigger('bettertabs-after-deactivate');
+              this_tab_content.trigger('bettertabs-after-activate');
+              return change_url(this_link);
+            };
+            previous_active_tab_content.trigger('bettertabs-before-deactivate');
+            this_tab_content.trigger('bettertabs-before-activate');
+            if (tab_type_of(this_link) === 'ajax' && !(this_link.data('content-loaded-already') != null)) {
+              this_link.addClass('ajax-loading');
+              this_tab_content.trigger('bettertabs-before-ajax-loading');
+              return this_tab_content.load(this_link.attr(ajax_url_attr), function() {
+                this_link.removeClass('ajax-loading');
+                this_link.data('content-loaded-already', true);
+                this_tab_content.trigger('bettertabs-after-ajax-loading');
+                return activate_tab_and_content();
+              });
+            } else {
+              return activate_tab_and_content();
+            }
+          }
+        }
+      });
+    });
+  };
+}).call(this);