tangofoxtrot-table_helper 0.2.2

data/lib/table_helper/body.rb

@@ -0,0 +1,113 @@
+require 'table_helper/body_row'
+
+module TableHelper
+  # Represents the body of the table.  In HTML, you can think of this as
+  # the <tbody> tag of the table.
+  class Body < HtmlElement
+    # The css class to apply for all rows in the body
+    cattr_accessor :empty_caption_class
+    @@empty_caption_class = 'ui-collection-empty'
+    
+    # The table this body is a part of
+    attr_reader :table
+    
+    # If set to :odd or :even, every odd or even-numbered row will have the
+    # alternate class appended to its html attributes. Default is nil.
+    attr_accessor :alternate
+    
+    # The caption to display in the collection is empty
+    attr_accessor :empty_caption
+    
+    def initialize(table) #:nodoc:
+      super()
+      
+      @table = table
+      @empty_caption = 'No matches found.'
+    end
+    
+    def alternate=(value) #:nodoc:
+      raise ArgumentError, 'alternate must be set to :odd or :even' if value && ![:odd, :even].include?(value)
+      @alternate = value
+    end
+    
+    # Builds the body of the table.  This includes the actual data that is
+    # generated for each object in the collection.
+    # 
+    # +each+ expects a block that defines the data in each cell.  Each
+    # iteration of the block will provide the row within the table, the object
+    # being rendered, and the index of the object.  For example,
+    # 
+    #   t.rows.each do |row, post, index|
+    #     row.title     "<div class=\"wrapped\">#{post.title}</div>"
+    #     row.category  post.category.name
+    #   end
+    # 
+    # In addition, to specifying the data, you can also modify the html
+    # options of the row.  For more information on doing this, see the
+    # BodyRow class.
+    # 
+    # If the collection is empty and +empty_caption+ is set on the body,
+    # then the actual body will be replaced by a single row containing the
+    # html that was stored in +empty_caption+.
+    # 
+    # == Default Values
+    # 
+    # Whenever possible, the default value of a cell will be set to the
+    # object's attribute with the same name as the cell.  For example,
+    # if a Post consists of the attribute +title+, then the cell for the
+    # title will be prepopulated with that attribute's value:
+    # 
+    #   t.rows.each do |row, post index|
+    #     row.title post.title
+    #   end
+    # 
+    # <tt>row.title</tt> is already set to post.category so there's no need to
+    # manually set the value of that cell.  However, it is always possible
+    # to override the default value like so:
+    # 
+    #   t.rows.each do |row, post, index|
+    #     row.title     link_to(post.title, post_url(post))
+    #     row.category  post.category.name
+    #   end
+    def each(&block)
+      @builder = block
+    end
+    
+    # Builds a row for an object in the table.
+    # 
+    # The provided block should set the values for each cell in the row.
+    def build_row(object, index = table.collection.index(object))
+      row = BodyRow.new(object, self)
+      row.alternate = alternate ? index.send("#{alternate}?") : false
+      @builder.call(row.builder, object, index) if @builder
+      row.html
+    end
+    
+    private
+      def tag_name
+        'tbody'
+      end
+      
+      def content
+        content = ''
+        
+        if table.empty? && @empty_caption
+          # No objects to display
+          row = Row.new(self)
+          row[:class] = empty_caption_class
+          
+          html_options = {}
+          html_options[:colspan] = table.header.columns.size if table.header.columns.size > 1
+          row.cell nil, @empty_caption, html_options
+          
+          content << row.html
+        else
+          table.collection.each_with_index do |object, i|
+            content << build_row(object, i)
+          end
+        end
+        
+        content
+      end
+  end
+end

data/lib/table_helper/body_row.rb

@@ -0,0 +1,74 @@
+require 'table_helper/row'
+
+module TableHelper
+  # Represents a single row within the body of a table.  The row can consist
+  # of either data cells or header cells. 
+  # 
+  # == Alternating rows
+  # 
+  # Alternating rows can be automated by setting the +alternate+ property.
+  # For example,
+  # 
+  #   r = BodyRow.new(object, parent)
+  #   r.alternate = true
+  class BodyRow < Row
+    # The css class to apply for all rows in the body
+    cattr_accessor :result_class
+    @@result_class = 'ui-collection-result'
+    
+    # The css class to apply for rows that are marked as "alternate"
+    cattr_accessor :alternate_class
+    @@alternate_class = 'ui-state-alternate'
+    
+    # True if this is an alternating row, otherwise false.  Default is false.
+    attr_accessor :alternate
+    
+    def initialize(object, parent) #:nodoc:
+      super(parent)
+      
+      @alternate = false
+      self[:class] = "#{self[:class]} #{table.object_name} #{result_class}".strip
+      
+      # For each column defined in the table, see if we can prepopulate the
+      # cell based on the data in the object.  If not, we can at least
+      # provide shortcut accessors to the cell
+      table.header.column_names.each do |column|
+        value = object.respond_to?(column) ? object.send(column) : nil
+        cell(column, value)
+      end
+    end
+    
+    # Generates the html for this row in additional to the border row
+    # (if specified)
+    def html
+      original_options = @html_options.dup
+      self[:class] = "#{self[:class]} #{alternate_class}".strip if alternate
+      html = super
+      @html_options = original_options
+      html
+    end
+    
+    private
+      # Builds the row's cells based on the order of the columns in the
+      # header.  If a cell cannot be found for a specific column, then a blank
+      # cell is rendered.
+      def content
+        number_to_skip = 0 # Keeps track of the # of columns to skip
+        
+        html = ''
+        table.header.column_names.each do |column|
+          number_to_skip -= 1 and next if number_to_skip > 0
+          
+          if cell = @cells[column]
+            number_to_skip = (cell[:colspan] || 1) - 1
+          else
+            cell = Cell.new(column, nil)
+          end
+          
+          html << cell.html
+        end
+        
+        html
+      end
+  end
+end

data/lib/table_helper/cell.rb

@@ -0,0 +1,60 @@
+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 name appended to the cell's class attribute.
+  # 
+  # == Examples
+  # 
+  #   # Data cell
+  #   c = Cell.new(:author, 'John Doe')
+  #   c.html    # => <td class="author">John Doe</td>
+  #   
+  #   # Header cell
+  #   c = Cell.new(:author, 'Author Name')
+  #   c.content_type = :header
+  #   c.html
+  #   
+  #   # With namespace
+  #   c = Cell.new(:author, :namespace => 'post')
+  #   c.content_type = :header
+  #   c.html    # => <td class="post-author">Author</td>
+  class Cell < HtmlElement
+    # The css class to apply to empty cells
+    cattr_accessor :empty_class
+    @@empty_class = 'ui-state-empty'
+    
+    # The content to display within the cell
+    attr_reader :content
+    
+    # The type of content this cell represents (:data or :header)
+    attr_reader :content_type
+    
+    def initialize(name, content = name.to_s.titleize, html_options = {}) #:nodoc
+      html_options, content = content, name.to_s.titleize if content.is_a?(Hash)
+      namespace = html_options.delete(:namespace)
+      super(html_options)
+      
+      @content = content.to_s
+      
+      if name
+        name = "#{namespace}-#{name}" unless namespace.blank?
+        self[:class] = "#{self[:class]} #{name}".strip
+      end
+      self[:class] = "#{self[:class]} #{empty_class}".strip if content.blank?
+      
+      self.content_type = :data
+    end
+    
+    # Indicates what type of content will be stored in this cell.  This can
+    # 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}" unless [:data, :header].include?(value)
+      @content_type = value
+    end
+    
+    private
+      def tag_name
+        @content_type == :data ? 'td' : 'th'
+      end
+  end
+end

data/lib/table_helper/collection_table.rb

@@ -0,0 +1,138 @@
+require 'table_helper/html_element'
+require 'table_helper/header'
+require 'table_helper/body'
+require 'table_helper/footer'
+
+module TableHelper
+  # Represents a table that displays data for multiple objects within a
+  # collection.
+  class CollectionTable < HtmlElement
+    # The css class to apply for all menu bars
+    cattr_accessor :collection_class
+    @@collection_class = 'ui-collection'
+    
+    # The class of objects that will be rendered in the table
+    attr_reader :klass
+    
+    # The name of the objects in the collection.  By default, this is the
+    # underscored name of the class of objects being rendered.  This value is
+    # used for generates parts of the css classes in the table, such as rows
+    # and cells.
+    # 
+    # For example, if the class is Post, then the object name will be "post".
+    attr_accessor :object_name
+    
+    # The actual collection of objects being rendered in the table's body.
+    # This collection will also be used to help automatically determine what
+    # the class is.
+    attr_reader :collection
+    
+    # The body of rows that will be generated for each object in the
+    # collection.  The actual content for each row and the html options can
+    # be configured as well.
+    # 
+    # See TableHelper::Body for more information.
+    # 
+    # == Examples
+    # 
+    #   # Defining rows
+    #   t.rows.each do |row, post, index|
+    #     row.category post.category.name
+    #     row.author   post.author.name
+    #     ...
+    #     row[:style] = 'margin-top: 5px;'
+    #   end
+    #   
+    #   # Customizing html options
+    #   t.rows[:class] = 'pretty'
+    attr_reader :rows
+    
+    # Creates a new table based on the objects within the given collection
+    def initialize(collection, klass = nil, html_options = {}) #:nodoc:
+      html_options, klass = klass, nil if klass.is_a?(Hash)
+      super(html_options)
+      
+      @collection = collection
+      @klass = klass || default_class
+      @object_name = @klass ? @klass.name.split('::').last.underscore : nil
+      @html_options.reverse_merge!(:cellspacing => '0', :cellpadding => '0')
+      
+      self[:class] = "#{self[:class]} #{@object_name.pluralize}".strip if @object_name
+      self[:class] = "#{self[:class]} #{collection_class}".strip
+      
+      # Build actual content
+      @header = Header.new(self)
+      @rows = Body.new(self)
+      @footer = Footer.new(self)
+      
+      yield self if block_given?
+    end
+    
+    # Will any rows be generated in the table's body?
+    def empty?
+      collection.empty?
+    end
+    
+    # Creates a new header cell with the given name.  Headers must be defined
+    # in the order in which they will be rendered.
+    # 
+    # The actual caption and html options for the header can be configured
+    # as well.  The caption determines what will be displayed in each cell.
+    # 
+    # == Examples
+    # 
+    #   # Adding headers
+    #   t.header :title                                   # => <th class="post-title">Title</th>
+    #   t.header :title, 'The Title'                      # => <th class="post-title">The Title</th>
+    #   t.header :title, :class => 'pretty'               # => <th class="post-title pretty">Title</th>
+    #   t.header :title, 'The Title', :class => 'pretty'  # => <th class="post-title pretty">The Title</th>
+    #   
+    #   # Customizing html options
+    #   t.header[:class] = 'pretty'
+    def header(*args)
+      args.empty? ? @header : @header.column(*args)
+    end
+    
+    # Creates a new footer cell with the given name.  Footers must be defined
+    # in the order in which they will be rendered.
+    # 
+    # The actual caption and html options for the footer can be configured
+    # as well.  The caption determines what will be displayed in each cell.
+    # 
+    # == Examples
+    # 
+    #   # Adding footers
+    #   t.footer :total                         # => <td class="post-total"></th>
+    #   t.footer :total, 5                      # => <td class="post-total">5</th>
+    #   t.footer :total, :class => 'pretty'     # => <td class="post-total pretty"></th>
+    #   t.footer :total, 5, :class => 'pretty'  # => <td class="post-total pretty">5</th>
+    #   
+    #   # Customizing html options
+    #   t.footer[:class] = 'pretty'
+    def footer(*args)
+      args.empty? ? @footer : @footer.cell(*args)
+    end
+    
+    private
+      # Finds the class representing the objects within the collection
+      def default_class
+        if collection.respond_to?(:proxy_reflection)
+          collection.proxy_reflection.klass
+        elsif !collection.empty?
+          collection.first.class
+        end
+      end
+      
+      def tag_name
+        'table'
+      end
+      
+      def content
+        content = ''
+        content << @header.html unless @header.empty?
+        content << @rows.html
+        content << @footer.html unless @footer.empty?
+        content
+      end
+  end
+end

data/lib/table_helper/footer.rb

@@ -0,0 +1,52 @@
+require 'table_helper/row'
+
+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 table this footer is a part of
+    attr_reader :table
+    
+    # The actual footer row
+    attr_reader :row
+    
+    # Whether or not the footer should be hidden when the collection is
+    # empty.  Default is true.
+    attr_accessor :hide_when_empty
+    
+    delegate :cell, :empty?, :to => :row
+    
+    def initialize(table) #:nodoc:
+      super()
+      
+      @table = table
+      @row = Row.new(self)
+      @hide_when_empty = true
+    end
+    
+    def html #:nodoc:
+      # Force the last cell to span the remaining columns
+      cells = row.cells.values
+      colspan = table.header.columns.length - cells[0..-2].inject(0) {|count, cell| count += (cell[:colspan] || 1).to_i}
+      cells.last[:colspan] ||= colspan if colspan > 1
+      
+      html_options = @html_options.dup
+      html_options[:style] = "display: none; #{html_options[:style]}".strip if table.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

data/lib/table_helper/header.rb

@@ -0,0 +1,109 @@
+require 'table_helper/row'
+
+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 table this header is a part of
+    attr_reader :table
+    
+    # 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
+    
+    delegate :empty?, :to => :row
+    
+    # Creates a new header for the given table.
+    # 
+    # 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(table)
+      super()
+      
+      @table = table
+      @row = Row.new(self)
+      @hide_when_empty = 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 = table.klass
+      if klass && klass.respond_to?(:column_names)
+        if !table.empty? && klass < ActiveRecord::Base
+          # Make sure only the attributes that have been loaded are used
+          column_names = table.collection.first.attributes.keys
+        else
+          # Assume all attributes are loaded
+          column_names = klass.column_names
+        end
+        
+        column(*column_names.map(&:to_sym))
+      end
+      
+      @customized = false
+    end
+    
+    # The current columns in this header, in the order in which they will be
+    # built
+    def columns
+      row.cells
+    end
+    
+    # Gets the names of all of the columns being displayed in the table
+    def column_names
+      row.cell_names
+    end
+    
+    # Clears all of the current columns from the header
+    def clear
+      row.clear
+    end
+    
+    # Creates one or more to columns in the header.  This will clear any
+    # pre-existing columns if it is being customized for the first time after
+    # it was initially created.
+    def column(*names)
+      # Clear the header row if this is being customized by the user
+      unless @customized
+        @customized = true
+        clear
+      end
+      
+      # Extract configuration
+      options = names.last.is_a?(Hash) ? names.pop : {}
+      content = names.last.is_a?(String) ? names.pop : nil
+      args = [content, options].compact
+      
+      names.collect! do |name|
+        column = row.cell(name, *args)
+        column.content_type = :header
+        column[:scope] ||= 'col'
+        column
+      end
+      
+      names.length == 1 ? names.first : names
+    end
+    
+    # Creates and returns the generated html for the header
+    def html
+      html_options = @html_options.dup
+      html_options[:style] = 'display: none;' if table.empty? && hide_when_empty
+      
+      content_tag(tag_name, content, html_options)
+    end
+    
+    private
+      def tag_name
+        'thead'
+      end
+      
+      def content
+        @row.html
+      end
+  end
+end