tabulous 1.3.2 → 2.0.0

data/REFERENCE.md

@@ -0,0 +1,403 @@
+# Tabulous Reference
+
+## Contents
+
+* [Tabsets](#tabsets)
+    * [Multiple Tabsets](#multiple-tabsets)
+    * [Tab Order](#tab-order)
+    * [Subtabs](#subtabs)
+    * [Tab Names](#tab-names)
+* [Tab Declarations](#tab-declarations)
+    * [text](#text)
+    * [link_path](#link_path)
+    * [visible_when](#visible_when)
+    * [enabled_when](#enabled_when)
+    * [active_when](#active_when)
+* [Customizing](#customizing)
+    * [renderer](#renderer)
+    * [active_tab_clickable](#active_tab_clickable)
+    * [when_action_has_no_tab](#when_action_has_no_tab)
+    * [render_subtabs_when_empty](#render_subtabs_when_empty)
+* [CSS Scaffolding](#css-scaffolding)
+* [Helpers](#helpers)
+* [Generators](#generators)
+
+## Tabsets
+
+A tabbed navigation bar, which we will call a tabset, is specified using a tabs block:
+
+    tabs do
+      unicorns_tab do
+        ...
+      end
+
+      rainbows_tab do
+        ...
+      end
+    end
+
+### Multiple Tabsets
+
+You can have more than one tabset on a page by passing in a name to the tabs block:
+
+    tabs(:fun) do
+      unicorns_tab do
+        ...
+      end
+
+      rainbows_tab do
+        ...
+      end
+    end
+
+    tabs(:colors) do
+      red_tab do
+        ...
+      end
+
+      blue_tab do
+        ...
+      end
+    end
+
+Then, in your layout, you need to tell tabulous which tabset to draw:
+
+    <%= render tabs(:fun) %>
+    <%= render subtabs(:fun) %>
+    <p>some markup</p>
+    <%= render tabs(:colors) %>
+    <%= render subtabs(:colors) %>
+
+### Tab Order
+
+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
+
+### Subtabs
+
+Any tab can have several subtabs associated with it that become visible when the parent tab is clicked.  Declare subtabs just like tabs, except make sure that their name ends in _subtab.  Subtabs should be declared immediately after their parent tab.  Parent tabs must include a_subtab_is_active in their active_when declaration:
+
+    tabs do
+      unicorns_tab do
+        ...
+      end
+
+      rainbows_tab do
+        ...
+        active_when { a_subtab_is_active }
+      end
+
+      monorainbows_subtab do
+        ...
+      end
+
+      double_rainbows_subtab do
+        ...
+      end
+
+      ponies_tab do
+        ...
+        active_when { a_subtab_is_active }
+      end
+
+      shetland_ponies_subtab do
+        ...
+      end
+    end
+
+### Tab Names
+
+It doesn't matter what you call a tab, but it must end in \_tab or \_subtab, and it can't have the same name as another tab.
+
+    tabs do
+      unicorns do  # BAD: does not end in _tab
+        ...
+      end
+
+      rainbows_tab do
+        ...
+      end
+    end
+
+## Tab Declarations
+
+Each tab has five declarations that you must specify.  The text, link_path, visible_when and enabled_when declarations do not need to be given a block.  If given a block, the block will be executed in the context of the layout where the tabs are rendered.
+
+Here is an example of a tab with the five required declarations:
+
+    unicorns_tab do
+      text          'Unicorns'
+      link_path     '/unicorns'
+      visible_when  { current_user.loves_unicorns? }
+      enabled_when  true
+      active_when   { in_action('any').of_controller('unicorns') }
+    end
+
+### text
+
+text must evaluate to a string.  This string will be what users see written on the tab.
+
+### link_path
+
+link_path must evaluate to a string which is a valid URL or path.  This is the URL that the browser will load when the tab is clicked.
+
+    narwhals_tab do
+      ...
+      link_path  { narwhals_path }
+      ...
+    end
+
+Since a block given to link_path is evaluated in the context of a view layout and not any particular view, you should not reference HTTP params:
+
+    narwhal_tab do
+      ...
+      link_path  { narwhal_path(params[:narwhal_id]) }  # WRONG
+      ...
+    end
+
+### visible_when
+
+If visible_when evaluates to false (or a falsy value like nil), the HTML for that particular tab will not be generated.
+
+### enabled_when
+
+If enabled_when evaluates to false (or a falsy value like nil), li tag for that tab will have a "disabled" class.
+
+### active_when
+
+Tabulous sets a tab as active depending on the controller action that generated the web page.  active_when should list out all of the actions for which the tab should be selected:
+
+    unicorns_tab do
+      ...
+      active_when do
+        in_action('index').of_controller('unicorns')
+        in_action('show').of_controller('unicorns')
+        in_action('new').of_controller('unicorns')
+        in_action('create').of_controller('unicorns')
+        in_action('edit').of_controller('unicorns')
+        in_action('update').of_controller('unicorns')
+        in_action('destroy').of_controller('unicorns')
+      end
+    end
+
+As a convenience, you can list more than one action at a time using in_actions:
+
+    unicorns_tab do
+      ...
+      active_when  { in_actions('index', 'show', 'new', 'create', 'edit', 'update', 'destroy').of_controller('unicorns') }
+    end
+
+Since it is common for there to be a one-to-one correspondence between a controller and a tab, you can list the 'any' action as a catch-all:
+
+    unicorns_tab do
+      ...
+      active_when  { in_action('any').of_controller('unicorns') }
+    end
+
+The actions that make the tab active do not have to be limited to one controller:
+
+    unicorns_tab do
+      ...
+      active_when do
+        in_action('any').of_controller('unicorns')
+        in_action('show').of_controller('horses')
+      end
+    end
+
+Namespaced controllers, such as Admin::UserAccountsController, can be referenced like so:
+
+    unicorns_tab do
+      ...
+      active_when  { in_action('any').of_controller('admin/user_accounts') }
+    end
+
+It is an error for active_when rules of different tabs to overlap or conflict with each other:
+
+    unicorns_tab do
+      ...
+      active_when  { in_action('any').of_controller('unicorns') }
+    end
+
+    list_unicorns_tab do
+      ...
+      active_when  { in_action('index').of_controller('unicorns') }  # WRONG, conflicts with above active_when
+    end
+
+If a tab has subtabs, it is automatically set to active if any of its subtabs is active.  To make this behavior explicit, the parent tab must specify a_subtab_is_active as one of the rules in active_when.
+
+## Customizing
+
+Tabulous tries to provide good default behavior to make it easy to quickly add tabs to your app.  Tabulous gives you control over some of its choices if you don't like the defaults.
+
+### renderer
+
+This specifies the class that the tabs and subtabs view helpers use to generate the tab markup.
+
+    customize do
+      renderer :default
+    end
+
+There are three other renderers you can use:
+
+* **:html5** -- uses nav tags instead of divs
+* **:bootstrap** -- generates markup compatible with Twitter Bootstrap; it uses the "nav-tabs" class
+* **:bootstrap_pill** -- generates markup compatible with Twitter Bootstrap; it uses the "nav-pills" class
+
+If this doesn't suit your needs, you can write your own custom renderer.  Here's an example of a custom renderer class:
+
+    class CustomRenderer < Tabulous::DefaultRenderer
+
+      def tabs_html
+        <<-HTML.strip_heredoc
+          <div class="tabs" class="from_custom_renderer">
+            <ul>
+              #{ tab_list_html }
+            </ul>
+          </div>
+        HTML
+      end
+
+      def subtabs_html
+        <<-HTML.strip_heredoc
+          <div class="subtabs" class="from_custom_renderer">
+            <ul>
+              #{ subtab_list_html }
+            </ul>
+          </div>
+        HTML
+      end
+
+    protected
+
+      def tab_html(tab)
+        return '<li>stub</li>'
+      end
+
+    end
+
+Put this class in app/tabs alongside the tabulous.rb file.  To use this, pass the underscored name of the renderer class (without renderer) to the customize block:
+
+    customize do
+      renderer :custom
+    end
+
+You do not have to call the class CustomRenderer.  For example, if you specified this renderer:
+
+    customize do
+      renderer :double_rainbow
+    end
+
+tabulous will look for a class called DoubleRainbowRenderer when generating markup for tabs.
+
+The best way to understand how to write a custom renderer is to look at [the tabulous gem code](https://github.com/techiferous/tabulous/tree/master/lib/tabulous/renderers) at how the various tabulous renderers are written.
+
+### active_tab_clickable
+
+By default, the active tab is clickable.  If you want to prevent the active tab from being clicked, set this to false:
+
+    customize do
+      active_tab_clickable false
+    end
+
+### when_action_has_no_tab
+
+When tabulous tries to set a tab active based on the current controller action and it can't find any tab that says it should be active, by default tabulous does not render the tabset at all:
+
+    customize do
+      when_action_has_no_tab :do_not_render
+    end
+
+This default makes multiple tabsets play nicely with each other.  If you want to consider not finding an active tab to be an error, you can tell tabulous to raise an error:
+
+    customize do
+      when_action_has_no_tab :raise_error
+    end
+
+Finally, if you want tabulous to draw the tabs anyway, even though none of them are active, you can:
+
+    customize do
+      when_action_has_no_tab :render
+    end
+
+### render_subtabs_when_empty
+
+By default, tabulous does not include any subtab markup at all if no subtabs are visible.  If you always want subtab HTML to appear in the page, even if there is nothing in the list of subtabs, set render_subtabs_when_empty to true:
+
+    customize do
+      render_subtabs_when_empty true
+    end
+
+## CSS Scaffolding
+
+If you are prototyping a new app and want your tabs to instantly look decent, tabulous provides you with quick and dirty CSS that you can turn on by specifying use_css_scaffolding in your Tabulous.setup block:
+
+    Tabulous.setup do
+
+      tabs do
+        ...
+      end
+
+      customize do
+        ...
+      end
+
+      use_css_scaffolding
+
+    end
+
+You can customize the colors:
+
+    use_css_scaffolding do
+      background_color '#cec'
+      text_color '#464'
+      active_tab_color '#fff'
+      hover_tab_color '#dfd'
+      inactive_tab_color '#aca'
+      inactive_text_color '#8a8'
+    end
+
+You should turn off the CSS scaffolding and use your own CSS before launching your web app, since the scaffolded CSS is placed directly inside your HTML page, which is technically invalid HTML.
+
+## Helpers
+
+Tabulous generates HTML for you to place in your layout.  It does this with the following helpers:
+
+    <%= render tabs %>
+    <%= render subtabs %>
+
+If you have multiple tabsets, you need to call these helpers for each tabset:
+
+    <%= render tabs(:fun) %>
+    <%= render subtabs(:fun) %>
+
+    <%= render tabs(:colors) %>
+    <%= render subtabs(:colors) %>
+
+Some renderers, like the Twitter Bootstrap renderers, generate markup that has subtabs interspersed within tabs instead of a separate list of tabs and subtabs.  If a renderer does this, it is an error to call the subtabs helper:
+
+    <%= render tabs %>     # always ok
+    <%= render subtabs %>  # DO NOT DO THIS if using a Bootstrap renderer
+
+## Generators
+
+Tabulous comes with one generator that will create an app/tabs/tabulous.rb file based on your controllers:
+
+    rails generate tabs

data/Rakefile

@@ -21,9 +21,6 @@ task :test do
   puts "To run integration specs:"
   puts "  $ script/for_all_test_apps rake"
   puts
-  puts "To run integration specs in a Ruby 1.8 environment:"
-  puts "  $ RUBY_COMPATIBILITY=1.8 script/for_all_test_apps rake"
-  puts
   puts "To run integration specs in a Ruby 2.0 environment:"
   puts "  $ RUBY_COMPATIBILITY=2.0 script/for_all_test_apps rake"
   puts
@@ -36,11 +33,3 @@ task :test do
 end
 
 task :default => :test
-
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Test'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end

data/lib/generators/tabs/templates/tabulous.rb

@@ -1,197 +1,68 @@
-# Tabulous gives you an easy way to set up tabs for your Rails application.
-#
-#   1. Configure this file.
-#   2. Add <%%= tabs %> and <%%= subtabs %> in your layout(s) wherever you want
-#      your tabs to appear.
-#   3. Add styles for these tabs in your stylesheets.
-#   4. Profit!
-
-<% controllers = []
-   Dir[File.join(Rails.root.to_s, 'app/controllers/*.rb')].each do |filename|
-     filename = filename.split('/').last
-     if filename =~ /(\w+)_controller.rb/
-       controller_name = $1.downcase
-       if controller_name != 'application'
-         controllers << controller_name
-       end
-     end
-   end
--%>
-Tabulous.setup do |config|
-
-  #---------------------------
-  #   HOW TO USE THE TABLES
-  #---------------------------
-  #
-  # The following tables are just an array of arrays.  As such, you can put
-  # any Ruby code into a cell.  For example, you could put "/foo/bar" in
-  # a path cell or you could put "/foo" + "/bar".  You can even wrap up code
-  # in a lambda to be executed later.  These will be executed in the context
-  # of a Rails view meaning they will have access to view helpers.
-  #
-  # However, there is something special about the format of these tables.
-  # Because it would be a pain for you to manually prettify the tables each
-  # time you edit them, there is a special rake task that does this for
-  # you: rake tabs:format.  However, for this prettifier to work properly
-  # you have to follow some special rules:
-  #
-  #   * No comments are allowed between rows.
-  #   * Comments are allowed to the right of rows, except for header rows.
-  #   * The start of a table is signified by a [ all by itself on a line.
-  #   * The end of a table is signified by a ] all by itself on a line.
-  #   * And most importantly: commas that separate cells should be surrounded
-  #     by spaces and commas that are within cells should not.  This gives the
-  #     formatter an easy way to distinguish between cells without having
-  #     to actually parse the Ruby.
-
-  #----------
-  #   TABS
-  #----------
-  #
-  # This is where you define your tabs and subtabs.  The order that the tabs
-  # appear in this list is the order they will appear in your views.  Any
-  # subtabs defined will have the previous tab as their parent.
-  #
-  # TAB NAME
-  #   must end in _tab or _subtab
-  # DISPLAY TEXT
-  #   the text the user sees on the tab
-  # PATH
-  #   the URL that gets sent to the server when the tab is clicked
-  # VISIBLE
-  #   whether to display the tab
-  # ENABLED
-  #   whether the tab is disabled (unclickable)
-
-<% index_routes = Rails.application.routes.routes.select{|r| r.requirements[:action] == 'index'}
-   tab_data = index_routes.map do |route|
-     name = route.requirements[:controller].gsub('/', '_')
-     if route.name.nil?
-       path = "url_for(:controller => '#{route.requirements[:controller]}', :action => 'index')"
-     else
-       path = route.name + '_path'
-     end
-     { :text => name.titleize,
-       :name => name,
-       :path_helper => path }
-   end
+<%
+  index_routes = Rails.application.routes.routes.select{|r| r.requirements[:action] == 'index'}
+  unique_routes = {}
+  index_routes.each do |route|
+    unique_routes[route.requirements[:controller]] = route.name
+  end
 -%>
-<%= s = []
-    s <<  '  config.tabs do'
-    s <<  '    ['
-    s <<  '      #-------------------------------------------------------------------------------------------------#'
-    s <<  '      #    TAB NAME         |    DISPLAY TEXT     |    PATH           |    VISIBLE?    |    ENABLED?    #'
-    s <<  '      #-------------------------------------------------------------------------------------------------#'
-    for tab in tab_data
-      s << "[    :#{tab[:name]}_tab  ,  '#{tab[:text]}'    ,  #{tab[:path_helper]}  ,  true  ,  true  ],"
+Tabulous.setup do
+
+  tabs do
+
+<% unique_routes.keys.each do |controller_name| -%>
+<% next if controller_name == 'rails/info' -%>
+<% next if controller_name == 'rails/welcome' -%>
+<% next if unique_routes[controller_name].nil? -%>
+<% underscored_name = controller_name.gsub('/', '_')
+   title = underscored_name.titleize
+   path = unique_routes[controller_name] + '_path' -%>
+    <%= underscored_name %>_tab do
+      text          { '<%= title %>' }
+      link_path     { <%= path %> }
+      visible_when  { true }
+      enabled_when  { true }
+      active_when   { in_action('any').of_controller('<%= controller_name %>') }
     end
-    s <<  '      #-------------------------------------------------------------------------------------------------#'
-    s <<  '      #    TAB NAME         |    DISPLAY TEXT     |    PATH           |    VISIBLE?    |    ENABLED?    #'
-    s <<  '      #-------------------------------------------------------------------------------------------------#'
-    s <<  '    ]'
-    s <<  '  end'
-    Tabulous::Formatter.format(s).join("\n") %>
 
-  #-------------
-  #   ACTIONS
-  #-------------
-  #
-  # This is where you hook up actions with tabs.  That way tabulous knows
-  # which tab and subtab to mark active when an action is rendered.
-  #
-  # CONTROLLER
-  #   the name of the controller
-  # ACTION
-  #   the name of the action, or :all_actions
-  # TAB
-  #   the name of the tab or subtab that is active when this action is rendered
+<% end -%>
+  end
 
-<%= s = []
-    s <<  '  config.actions do'
-    s <<  '    ['
-    s <<  '      #-------------------------------------------------------------#'
-    s <<  '      #    CONTROLLER    |    ACTION          |    TAB              #'
-    s <<  '      #-------------------------------------------------------------#'
-    for tab in tab_data
-      s << "[    :#{tab[:name]}  ,  :all_actions  ,  :#{tab[:name]}_tab  ],"
-    end
-    s <<  '      #-------------------------------------------------------------#'
-    s <<  '      #    CONTROLLER    |    ACTION          |    TAB              #'
-    s <<  '      #-------------------------------------------------------------#'
-    s <<  '    ]'
-    s <<  '  end'
-    Tabulous::Formatter.format(s).join("\n") %>
-
-  #---------------------
-  #   GENERAL OPTIONS
-  #---------------------
-
-  # By default, you cannot click on the active tab.
-  config.active_tab_clickable = false
-
-  # By default, the subtabs HTML element is not rendered if it is empty.
-  config.always_render_subtabs = false
-
-  # Tabulous expects every controller action to be associated with a tab.
-  # When an action does not have an associated tab (or subtab), you can
-  # instruct tabulous how to behave:
-  config.when_action_has_no_tab = :raise_error      # the default behavior
-  # config.when_action_has_no_tab = :do_not_render  # no tab navigation HTML will be generated
-  # config.when_action_has_no_tab = :render         # the tab navigation HTML will be generated,
-                                                    # but no tab or subtab will be active
-
-  #--------------------
-  #   MARKUP OPTIONS
-  #--------------------
+  customize do
 
-  # By default, div elements are used in the tab markup.  When html5 is
-  # true, nav elements are used instead.
-  config.html5 = false
+    # which class to use to generate HTML
+    # :default, :html5, :bootstrap, or :bootstrap_pill
+    # or create your own renderer class and reference it here
+    # renderer :default
 
-  # This gives you control over what class the <ul> element that wraps the tabs
-  # will have.  Good for interfacing with third-party code like Twitter
-  # Bootstrap.
-  # config.tabs_ul_class = "nav nav-pills"
+    # whether to allow the active tab to be clicked
+    # defaults to true
+    # active_tab_clickable true
 
-  # This gives you control over what class the <ul> element that wraps the subtabs
-  # will have.  Good for interfacing with third-party code.
-  # config.subtabs_ul_class = "nav"
+    # what to do when there is no active tab for the currrent controller action
+    # :render -- draw the tabset, even though no tab is active
+    # :do_not_render -- do not draw the tabset
+    # :raise_error -- raise an error
+    # defaults to :do_not_render
+    # when_action_has_no_tab :do_not_render
 
-  # Set this to true to have subtabs rendered in markup that Twitter Bootstrap
-  # understands.  If this is set to true, you don't need to call subtabs in
-  # your layout, just tabs.
-  # config.bootstrap_style_subtabs = true
-
-
-  #-------------------
-  #   STYLE OPTIONS
-  #-------------------
-  #
-  # The markup that is generated has the following properties:
-  #
-  #   Tabs and subtabs that are selected have the class "active".
-  #   Tabs and subtabs that are not selected have the class "inactive".
-  #   Tabs that are disabled have the class "disabled"; otherwise, "enabled".
-  #   Tabs that are not visible do not appear in the markup at all.
-  #
-  # These classes are provided to make it easier for you to create your
-  # own CSS (and JavaScript) for the tabs.
+    # whether to always add the HTML markup for subtabs, even if empty
+    # defaults to false
+    # render_subtabs_when_empty false
 
-  # Some styles will be generated for you to get you off to a good start.
-  # Scaffolded styles are not meant to be used in production as they
-  # generate invalid HTML markup.  They are merely meant to give you a
-  # head start or an easy way to prototype quickly.  Set this to false if
-  # you are using Twitter Bootstrap.
-  # 
-  config.css.scaffolding = true
+  end
 
-  # You can tweak the colors of the generated CSS.
+  # The following will insert some CSS straight into your HTML so that you
+  # can quickly prototype an app with halfway-decent looking tabs.
   #
-  # config.css.background_color = '#ccc'
-  # config.css.text_color = '#444'
-  # config.css.active_tab_color = 'white'
-  # config.css.hover_tab_color = '#ddd'
-  # config.css.inactive_tab_color = '#aaa'
-  # config.css.inactive_text_color = '#888'
+  # This scaffolding should be turned off and replaced by your own custom
+  # CSS before using tabulous in production.
+  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
 
 end