table_helper 0.0.3

data/lib/table_helper/cell.rb

@@ -0,0 +1,51 @@
+module PluginAWeek #:nodoc:
+  module TableHelper
+    # Represents a single cell within a table.  This can either be a regular
+    # data cell (td) or a header cell (th).  By default, all cells will have
+    # their column name appended to the cell's class attribute.
+    # 
+    # == Creating data cells
+    # 
+    #   Cell.new(:author, 'John Doe').build
+    # 
+    # ...would generate the following tag:
+    # 
+    #   <td class="author">John Doe</td>
+    # 
+    # == Creating header cells
+    # 
+    #   c = Cell.new(:author, 'Author Name')
+    #   c.content_type = :header
+    #   c.build
+    # 
+    # ...would generate the following tag:
+    # 
+    #   <th class="author">Author Name</th>
+    class Cell < HtmlElement
+      def initialize(class_name, content = class_name.to_s.titleize, html_options = {}) #:nodoc
+        super(html_options)
+        
+        @content = content
+        @html_options[:class] = ("#{class_name} " + @html_options[:class].to_s).strip if class_name
+        
+        self.content_type = :data
+      end
+      
+      # Indicates what type of content will be stored in this cell.  This can
+      # either be set to either :data or :header.
+      def content_type=(value)
+        raise ArgumentError, "content_type must be set to :data or :header, was: #{value.inspect}" if ![:data, :header].include?(value)
+        @content_type = value
+      end
+      
+      private
+        def tag_name
+          @content_type == :data ? 'td' : 'th'
+        end
+        
+        def content
+          @content
+        end
+    end
+  end
+end

data/lib/table_helper/collection_table.rb

@@ -0,0 +1,60 @@
+require 'table_helper/html_element'
+require 'table_helper/header'
+require 'table_helper/body'
+require 'table_helper/footer'
+
+module PluginAWeek #:nodoc:
+  module TableHelper
+    # Represents a table that is displaying data for multiple objects within
+    # a collection.
+    class CollectionTable < HtmlElement
+      def initialize(collection, options = {}, html_options = {}) #:nodoc:
+        super(html_options)
+        
+        options.assert_valid_keys(
+          :class,
+          :footer,
+          :header
+        )
+        @options = options.reverse_merge(
+          :header => true,
+          :footer => false
+        )
+        
+        @html_options.reverse_merge!(
+          :cellspacing => '0',
+          :cellpadding => '0'
+        )
+        
+        @header = Header.new(collection, options[:class])
+        @body = Body.new(collection, @header)
+        @footer = Footer.new(collection)
+      end
+      
+      # Builds the table by rendering a header, body, and footer.
+      def build(&block)
+        @body.build # Build with the defaults
+        
+        elements = []
+        elements << @header if @options[:header]
+        elements << @body
+        elements << @footer if @options[:footer]
+        
+        yield *elements if block_given?
+        
+        @content = ''
+        elements.each {|element| @content << element.html}
+        @content
+      end
+      
+      private
+        def tag_name
+          'table'
+        end
+        
+        def content
+          @content
+        end
+    end
+  end
+end

data/lib/table_helper/footer.rb

@@ -0,0 +1,47 @@
+require 'table_helper/row'
+
+module PluginAWeek #:nodoc:
+  module TableHelper
+    # Represents the header of the table.  In HTML, you can think of this as
+    # the tfoot tag of the table.
+    class Footer < HtmlElement
+      # The actual footer row
+      attr_reader :row
+      
+      delegate  :cell,
+                  :to => :row
+      
+      # Whether or not the footer should be hidden when the collection is
+      # empty.  Default is true.
+      attr_accessor :hide_when_empty
+      
+      def initialize(collection) #:nodoc:
+        super()
+        
+        @collection = collection
+        @row = Row.new
+        @hide_when_empty = true
+      end
+      
+      def html #:nodoc:
+        html_options = @html_options.dup
+        html_options[:style] = 'display: none;' if @collection.empty? && hide_when_empty
+        
+        content_tag(tag_name, content, html_options)
+      end
+      
+      private
+        def tag_name
+          'tfoot'
+        end
+        
+        # Generates the html for the footer.  The footer generally consists of a
+        # summary of the data in the body.  This row will be wrapped inside of
+        # a tfoot tag.  If the collection is empty and hide_when_empty was set
+        # to true, then the footer will be hidden.
+        def content
+          @row.html
+        end
+    end
+  end
+end

data/lib/table_helper/header.rb

@@ -0,0 +1,125 @@
+require 'table_helper/row'
+
+module PluginAWeek #:nodoc:
+  module TableHelper
+    # Represents the header of the table.  In HTML, you can think of this as
+    # the <thead> tag of the table.
+    class Header < HtmlElement
+      # The actual header row
+      attr_reader   :row
+      
+      # Whether or not the header should be hidden when the collection is
+      # empty.  Default is true.
+      attr_accessor :hide_when_empty
+      
+      # Creates a new header for a collection that contains objects of the
+      # given class.
+      # 
+      # If the class is known, then the header will be pre-filled with
+      # the columns defined in that class (assuming it's an ActiveRecord
+      # class).
+      def initialize(collection, klass = nil)
+        super()
+        
+        @collection = collection
+        @row = Row.new
+        
+        @hide_when_empty = true
+        @customized = true
+        
+        # If we know what class the objects in the collection are and we can
+        # figure out what columns are defined in that class, then we can
+        # pre-fill the header with those columns so that the user doesn't
+        # have to
+        klass ||= class_for_collection(collection)
+        if klass && klass.respond_to?(:column_names)
+          klass.column_names.each {|name| column(name)}
+          @customized = false
+        end
+      end
+      
+      # Gets the names of all of the columns being displayed in the table
+      def column_names
+        row.cell_names
+      end
+      
+      # Creates a new column with the specified caption.  Columns must be
+      # defined in the order in which they will be rendered.
+      # 
+      # The caption determines what will be displayed in each cell of the
+      # header (if the header is rendered).  For example,
+      # 
+      #   header.column :title, 'The Title'
+      # 
+      # ...will create a column the displays "The Title" in the cell.
+      # 
+      # = Setting html options
+      # 
+      # In addition to customizing the content of the column, you can also
+      # specify html options like so:
+      # 
+      #   header.column :title, 'The Title', :class => 'pretty'
+      def column(name, *args)
+        # Clear the header row if this is being customized by the user
+        if !@customized
+          @customized = true
+          
+          # Remove all of the shortcut methods
+          column_names.each do |column|
+            klass = class << self; self; end
+            klass.class_eval do
+              remove_method(column)
+            end
+          end
+          
+          @row.clear
+        end
+        
+        column = @row.cell(name, *args)
+        column.content_type = :header
+        column[:scope] ||= 'col'
+        
+        # Define a shortcut method to the cell
+        name = name.to_s.gsub('-', '_')
+        unless respond_to?(name)
+          instance_eval <<-end_eval
+            def #{name}(*args)
+              if args.empty?
+                @row.#{name}
+              else
+                @row.#{name}(*args)
+              end
+            end
+          end_eval
+        end
+        
+        column
+      end
+      
+      # Creates and returns the generated html for the header
+      def html
+        html_options = @html_options.dup
+        html_options[:style] = 'display: none;' if @collection.empty? && hide_when_empty
+        
+        content_tag(tag_name, content, html_options)
+      end
+      
+      private
+        def tag_name
+          'thead'
+        end
+        
+        def content
+          @row.html
+        end
+        
+        def class_for_collection(collection)
+          if collection.respond_to?(:proxy_reflection)
+            collection.proxy_reflection.klass
+          elsif !collection.empty?
+            collection.first.class
+          end
+        end
+    end
+  end
+end

data/lib/table_helper/html_element.rb

@@ -0,0 +1,46 @@
+module PluginAWeek #:nodoc:
+  module TableHelper
+    # Represents an HTML element
+    # 
+    # == Modifying HTML options
+    # 
+    # HTML options can normally be specified when creating the element.
+    # However, if they need to be modified after the element has been created,
+    # you can access the properties like so:
+    # 
+    #   r = Row.new
+    #   r[:style] = 'display: none;'
+    # 
+    # or for a cell:
+    # 
+    #   c = Cell.new
+    #   c[:style] = 'display: none;'
+    class HtmlElement
+      include ActionView::Helpers::TagHelper
+      
+      delegate  :[],
+                :[]=,
+                  :to => '@html_options'
+      
+      def initialize(html_options = {}) #:nodoc:
+        @html_options = html_options.symbolize_keys
+      end
+      
+      # Generates the html representing this element
+      def html
+        content_tag(tag_name, content, @html_options)
+      end
+      
+      private
+        # The name of the element tag to use (e.g. td, th, tr, etc.)
+        def tag_name
+          ''
+        end
+        
+        # The content that will be displayed inside of the tag
+        def content
+          ''
+        end
+    end
+  end
+end

data/lib/table_helper/row.rb

@@ -0,0 +1,72 @@
+require 'table_helper/cell'
+
+module PluginAWeek #:nodoc:
+  module TableHelper
+    # Represents a single row within a table.  A row can consist of either
+    # data cells or header cells.
+    class Row < HtmlElement
+      def initialize #:nodoc:
+        super
+        
+        @cells = ActiveSupport::OrderedHash.new
+      end
+      
+      # Creates a new cell with the given name and generates shortcut
+      # accessors for the method.
+      def cell(name, *args)
+        name = name.to_s if name
+        
+        cell = Cell.new(name, *args)
+        @cells[name] = cell
+        
+        define_cell_accessor(name) if name && !respond_to?(name)
+        
+        cell
+      end
+      
+      # The names of all cells in this row
+      def cell_names
+        @cells.keys
+      end
+      
+      # Clears all of the current cells from the row
+      def clear
+        cell_names.each do |name|
+          klass = class << self; self; end
+          klass.class_eval do
+            remove_method(name)
+          end
+        end
+        
+        @cells.clear
+      end
+      
+      private
+        # Defines the accessor method for the given cell name.  For example, if
+        # a cell with the name :title was defined, then the cell would be able
+        # to be read and written like so:
+        # 
+        #   row.title               #=> Accesses the title
+        #   row.title "Page Title"  #=> Creates a new cell with "Page Title" as the content
+        def define_cell_accessor(name)
+          instance_eval <<-end_eval
+            def #{name.gsub('-', '_')}(*args)
+              if args.empty?
+                @cells[#{name.inspect}]
+              else
+                cell(#{name.inspect}, *args)
+              end
+            end
+          end_eval
+        end
+        
+        def tag_name
+          'tr'
+        end
+        
+        def content
+          @cells.values.map(&:html).join
+        end
+    end
+  end
+end

data/lib/table_helper.rb

@@ -0,0 +1,182 @@
+require 'table_helper/collection_table'
+
+module PluginAWeek #:nodoc:
+  # Provides a set of methods for turning a collection into a table.
+  # 
+  # == Basic Example
+  # 
+  # This example shows the most basic usage of +collection_table+ which takes
+  # information about a collection, the objects in them, the columns defined
+  # for the class, and generates a table based on that.
+  # 
+  # Support you have a table generated by a migration like so:
+  # 
+  #   class CreatePeople < ActiveRecord::Base
+  #     def self.up
+  #       create_table do |t|
+  #         t.string :first_name
+  #         t.string :last_name
+  #         t.integer :company_id
+  #         t.string :role
+  #       end
+  #     end
+  #   end
+  # 
+  # ...then invoking the helper:
+  # 
+  #   <%= collection_table Person.find(:all) %>
+  # 
+  # ...is compiled to (formatted here for the sake of sanity):
+  # 
+  #   <table cellpadding="0" cellspacing="0">
+  #   <thead>
+  #     <tr>
+  #       <th class="first_name" scope="col">First Name</th>
+  #       <th class="last_name" scope="col">Last Name</th>
+  #       <th class="company_id" scope="col">Company</th>
+  #       <th class="role" scope="col">Role</th>
+  #     </tr>
+  #   </thead>
+  #   <tbody>
+  #     <tr class="row">
+  #       <td class="first_name">John</td>
+  #       <td class="last_name">Doe</td>
+  #       <td class="company_id">1</td>
+  #       <td class="role">President</td>
+  #     </tr>
+  #     <tr class="row">
+  #       <td class="first_name">Jane</td>
+  #       <td class="last_name">Doe</td>
+  #       <td class="company_id">1</td>
+  #       <td class="role">Vice-President</td>
+  #     </tr>
+  #   </tbody>
+  #   <table>
+  # 
+  # == Advanced Example
+  # 
+  # This example below shows how +collection_table+ can be customized to show
+  # specific headers, content, and footers.
+  # 
+  #   <%=
+  #     collection_table(@posts, {}, :id => 'posts', :class => 'summary') do |header, body|
+  #       header.column :title
+  #       header.column :category
+  #       header.column :author
+  #       header.column :publish_date, 'Date<br \>Published'
+  #       header.column :num_comments, '# Comments'
+  #       header.column :num_trackbacks, '# Trackbacks'
+  #       
+  #       body.alternate = true
+  #       body.build do |row, post, index|
+  #         row.category       post.category.name
+  #         row.author         post.author.name
+  #         row.publish_date   time_ago_in_words(post.published_on)
+  #         row.num_comments   post.comments.empty? ? '-' : post.comments.size
+  #         row.num_trackbacks post.trackbacks.empty? ? '-' : post.trackbacks.size
+  #       end
+  #     end
+  #   %>
+  # 
+  # ...is compiled to (formatted here for the sake of sanity):
+  # 
+  #   <table cellpadding="0" cellspacing="0" class="summary" id="posts">
+  #   <thead>
+  #     <tr>
+  #       <th class="title" scope="col">Title</th>
+  #       <th class="category" scope="col">Category</th>
+  #       <th class="author" scope="col">Author</th>
+  #       <th class="publish_date" scope="col">Date<br \>Published</th>
+  #       <th class="num_comments" scope="col"># Comments</th>
+  #       <th class="num_trackbacks" scope="col"># Trackbacks</th>
+  #     </tr>
+  #   </thead>
+  #   <tbody class="alternate">
+  #     <tr class="row">
+  #       <td class="title">Open-source projects: The good, the bad, and the ugly</td>
+  #       <td class="category">General</td>
+  #       <td class="author">John Doe</td>
+  #       <td class="publish_date">23 days</td>
+  #       <td class="num_comments">-</td>
+  #       <td class="num_trackbacks">-</td>
+  #     </tr>
+  #     <tr class="row alternate">
+  #       <td class="title">5 reasons you should care about Rails</td>
+  #       <td class="category">Rails</td><td class="author">John Q. Public</td>
+  #       <td class="publish_date">21 days</td>
+  #       <td class="num_comments">-</td>
+  #       <td class="num_trackbacks">-</td>
+  #     </tr>
+  #     <tr class="row">
+  #       <td class="title">Deprecation: Stop digging yourself a hole</td>
+  #       <td class="category">Rails</td>
+  #       <td class="author">Jane Doe</td>
+  #       <td class="publish_date">17 days</td>
+  #       <td class="num_comments">-</td>
+  #       <td class="num_trackbacks">-</td>
+  #     </tr>
+  #     <tr class="row alternate">
+  #       <td class="title">Jumpstart your Rails career at RailsConf 2007</td>
+  #       <td class="category">Conferences</td>
+  #       <td class="author">Jane Doe</td>
+  #       <td class="publish_date">4 days</td>
+  #       <td class="num_comments">-</td>
+  #       <td class="num_trackbacks">-</td>
+  #     </tr>
+  #     <tr class="row">
+  #       <td class="title">Getting some REST</td>
+  #       <td class="category">Rails</td>
+  #       <td class="author">John Doe</td>
+  #       <td class="publish_date">about 18 hours</td>
+  #       <td class="num_comments">-</td>
+  #       <td class="num_trackbacks">-</td>
+  #     </tr>
+  #   </tbody>
+  #   </table>
+  # 
+  # == Creating footers
+  # 
+  # Footers allow you to show some sort of summary information based on the
+  # data displayed in the body of the table.  Below is an example:
+  # 
+  #   <%
+  #     collection_table(@posts, :footer => true) do |header, body, footer|
+  #       header.column :title
+  #       header.column :category
+  #       header.column :author
+  #       header.column :publish_date, 'Date<br \>Published'
+  #       header.column :num_comments, '# Comments'
+  #       header.column :num_trackbacks, '# Trackbacks'
+  #       
+  #       body.alternate = true
+  #       body.build do |row, post, index|
+  #         row.category       post.category.name
+  #         row.author         post.author.name
+  #         row.publish_date   time_ago_in_words(post.published_on)
+  #         row.num_comments   post.comments.empty? ? '-' : post.comments.size
+  #         row.num_trackbacks post.trackbacks.empty? ? '-' : post.trackbacks.size
+  #       end
+  #       
+  #       footer.cell :num_comments, @posts.inject(0) {|sum, post| sum += post.comments.size}
+  #       footer.cell :num_trackbacks, @posts.inject(0) {|sum, post| sum += post.trackbacks.size}
+  #     end
+  #   %>
+  module TableHelper
+    # Creates a new table based on the given collection
+    # 
+    # Configuration options:
+    # 
+    # * +class+ - Specify the type of objects expected in the collection if it can't be guessed from its contents.
+    # * +header+ - Specify if a header (thead) should be built into the table.  Default is true.
+    # * +footer+ - Specify if a footer (tfoot) should be built into the table.  Default is false.
+    def collection_table(collection, options = {}, html_options = {}, &block)
+      table = CollectionTable.new(collection, options, html_options)
+      table.build(&block)
+      table.html
+    end
+  end
+end
+
+ActionController::Base.class_eval do
+  helper PluginAWeek::TableHelper
+end