table_helper 0.0.3

data/CHANGELOG

@@ -0,0 +1,19 @@
+*SVN*
+
+*0.0.3* (June 1st, 2008)
+
+* Remove dependency on set_or_append
+
+*0.0.2* (May 5th, 2008)
+
+* Updated documentation
+
+*0.0.1* (August 18th, 2007)
+
+* Add README documentation
+
+* Add gem dependency on set_or_append
+
+* Refactor test method names
+
+* Convert dos newlines to unix newlines

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2008 Aaron Pfeifer
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,161 @@
+= table_helper
+
++table_helper+ adds a helper method for generating HTML tables from collections.
+
+== Resources
+
+Wiki
+
+* http://wiki.pluginaweek.org/Table_helper
+
+API
+
+* http://api.pluginaweek.org/table_helper
+
+Development
+
+* http://dev.pluginaweek.org/browser/trunk/table_helper
+
+Source
+
+* http://svn.pluginaweek.org/trunk/table_helper
+
+== Description
+
+Tables of summary data for ActiveRecord models are often formatted in the same
+way by creating a header indicating the attribute and a body containing the
+data from each record in separate rows.  table_helper makes it easier to create
+these types of tables by DRYing much of the html being generated.
+
+== Usage
+
+=== Basic Example
+
+  <%= 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
+
+  <%=
+    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>
+
+=== Caveat Emptor
+
+See the API for more information on syntax and options.  You should only use
+table_helper if it fits the needs of your application.  Remember one of the key
+principles of Rails, KISS (Keep It Simple Stupid).  table_helper works really
+well when you need to quickly output several of these types of summary tables.
+If this is not the case, you may want to stick to using actual html.
+
+== Testing
+
+Before you can run any tests, the following gem must be installed:
+* plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper]
+
+To run against a specific version of Rails:
+
+  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails
+
+== Dependencies
+
+* Rails 2.0 or later
+* set_or_append[http://wiki.pluginaweek.org/Set_or_append]

data/Rakefile

@@ -0,0 +1,80 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+PKG_NAME           = 'table_helper'
+PKG_VERSION        = '0.0.3'
+PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
+RUBY_FORGE_PROJECT = 'pluginaweek'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the table_helper plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the table_helper plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'TableHelper'
+  rdoc.template = '../rdoc_template.rb'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s|
+  s.name            = PKG_NAME
+  s.version         = PKG_VERSION
+  s.platform        = Gem::Platform::RUBY
+  s.summary         = 'Adds a helper method for generating HTML tables from collections'
+  
+  s.files           = FileList['{lib,test}/**/*'].to_a + %w(CHANGELOG init.rb MIT-LICENSE Rakefile README)
+  s.require_path    = 'lib'
+  s.autorequire     = 'table_helper'
+  s.has_rdoc        = true
+  s.test_files      = Dir['test/**/*_test.rb']
+  
+  s.author          = 'Aaron Pfeifer'
+  s.email           = 'aaron@pluginaweek.org'
+  s.homepage        = 'http://www.pluginaweek.org'
+end
+  
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+desc 'Publish the beta gem'
+task :pgem => [:package] do
+  Rake::SshFilePublisher.new('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{PKG_FILE_NAME}.gem").upload
+end
+
+desc 'Publish the API documentation'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{PKG_NAME}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+task :publish => [:pgem, :pdoc, :release]
+
+desc 'Publish the release files to RubyForge.'
+task :release => [:gem, :package] do
+  require 'rubyforge'
+  
+  ruby_forge = RubyForge.new.configure
+  ruby_forge.login
+  
+  %w( gem tgz zip ).each do |ext|
+    file = "pkg/#{PKG_FILE_NAME}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(RUBY_FORGE_PROJECT, PKG_NAME, PKG_VERSION, file)
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'table_helper'

data/lib/table_helper/body.rb

@@ -0,0 +1,119 @@
+require 'table_helper/body_row'
+
+module PluginAWeek #:nodoc:
+  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
+      # If set to :odd or :even, every odd or even-numbered row will have the
+      # class 'alternate' appended to its html attributes, respectively.
+      # Default is nil.
+      attr_accessor :alternate_rows
+      
+      # The caption to display in the collection is empty
+      attr_accessor :empty_caption
+      
+      def initialize(collection, header) #:nodoc:
+        super()
+        
+        @collection, @header = collection, header
+        @empty_caption = 'No matches found.'
+      end
+      
+      def alternate_rows=(value) #:nodoc:
+        raise ArgumentError, 'alternate_rows must be set to :odd or :even' if value && ![:odd, :even].include?(value)
+        @alternate_rows = value
+      end
+      
+      # Builds the body of the table.  This includes the actual data that is
+      # generated for each object in the collection.
+      # 
+      # build expects a block that defines the data in each cell.  Each
+      # iteration of the block will provide the object being rendered, the row
+      # within the table that will be built and the index of the object.  For
+      # example,
+      # 
+      #   body.build 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:
+      # 
+      #   body.build do |row, post index|
+      #     row.category post.category.name
+      #   end
+      # 
+      # +row.title+ 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:
+      # 
+      #   body.build do |row, post, index|
+      #     row.title     link_to(post.title, post_url(post))
+      #     row.category  post.category.name
+      #   end
+      def build(&block)
+        @content = ''
+        
+        # Display nothing if there are no objects to display
+        if @collection.empty? && @empty_caption
+          row = Row.new
+          row[:class] = 'no_content'
+          
+          html_options = {}
+          html_options[:colspan] = @header.column_names.size if @header.column_names.size > 1
+          row.cell nil, @empty_caption, html_options
+          
+          @content << row.html
+        else
+          @collection.each_with_index do |object, i|
+            @content << build_row(object, i, &block)
+          end
+        end
+        
+        @content
+      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 = @collection.index(object), &block)
+        row = BodyRow.new(object, @header)
+        row.alternate = alternate_rows ? index.send("#{@alternate_rows}?") : false
+        
+        yield row, object, index if block_given?
+        
+        row.html
+      end
+      
+      def html #:nodoc:
+        html_options = @html_options.dup
+        html_options[:class] = (html_options[:class].to_s + ' alternate').strip if alternate_rows 
+        
+        content_tag(tag_name, content, html_options)
+      end
+      
+      private
+        def tag_name
+          'tbody'
+        end
+        
+        def content
+          @content
+        end
+    end
+  end
+end

data/lib/table_helper/body_row.rb

@@ -0,0 +1,86 @@
+require 'table_helper/row'
+
+module PluginAWeek #:nodoc:
+  module TableHelper
+    # Represents a single row within the body of a table.  The row can consist
+    # of either data cells or header cells. 
+    # 
+    # == Borders
+    # 
+    # Each row has an optional special border row that can be generated either
+    # immediately before or immediately after this row.  A separate border row
+    # is usually used when you cannot express borders in the css of the row
+    # containing the data (e.g. dotted borders in Internet Explorer).
+    # 
+    # To modify the properties of the border, you can access +row.border+ like
+    # so:
+    # 
+    #   r = BodyRow.new
+    #   r.border_type = :before
+    #   r.border[:style] = 'color: #ff0000;'
+    # 
+    # == Alternating rows
+    # 
+    # Alternating rows can be automated by setting the +alternate+ property.
+    # For example,
+    # 
+    #   r = BodyRow.new
+    #   r.alternate = true
+    class BodyRow < Row
+      # True if this is an alternating row, otherwise false.  Default is false.
+      attr_accessor :alternate
+      
+      def initialize(object, header) #:nodoc:
+        super()
+        
+        @header = header
+        @alternate = false
+        @html_options[:class] = ('row ' + @html_options[:class].to_s).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
+        @header.column_names.each do |column|
+          if object.respond_to?(column)
+            cell(column, object.send(column))
+          else
+            define_cell_accessor(column)
+          end
+        end
+      end
+      
+      # Generates the html for this row in additional to the border row
+      # (if specified)
+      def html
+        original_options = @html_options.dup
+        @html_options[:class] = (@html_options[:class].to_s + ' alternate').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 = ''
+          @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, '', :class => 'empty')
+            end
+            
+            html << cell.html
+          end
+          
+          html
+        end
+    end
+  end
+end