tabletastic 0.0.1 → 0.1.0

data/README.rdoc

@@ -4,46 +4,189 @@ Inspired by the projects table_builder and formtastic,
 I realized how often I created tables for my active record collections.
 This is my attempt to simply this (the default scaffold):
 
-    <table>
+  <table>
+    <tr>
+      <th>Title</th>
+      <th>Body</th>
+      <th>Author Id</th>
+    </tr>
+    <% for post in @posts %>
       <tr>
-        <th>Title</th>
-        <th>Body</th>
-        <th>Author Id</th>
-      </tr>
-      <% for post in @posts %>
-        <tr>
-          <td><%=h post.title %></td>
-          <td><%=h post.body %></td>
-          <td><%=h post.author_id %></td>
-          <td><%=h author.name %></td>
-          <td><%= link_to "Show", post %></td>
-          <td><%= link_to "Edit", edit_post_path(post) %></td>
-          <td><%= link_to "Destroy", post, :confirm => 'Are you sure?', :method => :delete %></td>
-          </tr>
-      <% end %>
-    </table>
+        <td><%=h post.title %></td>
+        <td><%=h post.body %></td>
+        <td><%=h post.author_id %></td>
+        <td><%= link_to "Show", post %></td>
+        <td><%= link_to "Edit", edit_post_path(post) %></td>
+        <td><%= link_to "Destroy", post, :confirm => 'Are you sure?', :method => :delete %></td>
+        </tr>
+    <% end %>
+  </table>
 
 into this:
 
-    <% table_for(@posts) do |t| %>
-       <%= t.data :title, :body, :author %>
-    <% end %>
+  <% table_for(@posts) do |t| %>
+    <%= t.data :title, :body, :author %>
+  <% end %>
+
+and still output the same effective results, but with all the semantic
+goodness that tabular data should have, i.e. a +<thead>+ and +<tbody>+ element.
 
 
 == Warning
-THIS PROJECT IS UNDER HEAVY DEVELOPMENT.
-IT IS NOT RECOMMENDED FOR USE IN PRODUCTION APPLICATIONS
 
+This project is still being actively developed. As such, future updates might not be backwards-compatible.
+
+== Installation
+
+In your Rails project, as a gem:
+  config.gem "tabletastic", :source => "http://gemcutter.org"
+
+Or, for if you're behind the times, as a plugin:
+  script/plugin install git://github.com/jgdavey/tabletastic.git
+
+
+== Usage
+
+By default, you can just use the table_for method to build up your table.
+Assuming you have a Post model with title and body, that belongs to an Author model with a name,
+you can just use the helper. It will try to detect all content fields and belongs to associations.
+
+In your view, simply calling:
+
+  <% table_for(@posts) do |t| %>
+    <%= t.data %>
+  <% end %>
+
+will produce html like this:
+
+  <table id="posts">
+    <thead>
+      <tr>
+        <th>Title</th>
+        <th>Body</th>
+        <th>Author</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr class="post odd" id="post_1">
+        <td>Something</td>
+        <td>Lorem ipsum dolor sit amet consequat. Duis aute irure dolor.</td>
+        <td>Jim Beam</td>
+      </tr>
+      <tr class="post even" id="post_2">
+        <td>Second Post</td>
+        <td>This is the second post</td>
+        <td>Jack Daniels</td>
+      </tr>
+      <tr class="post odd" id="post_3">
+        <td>Something else</td>
+        <td>Blah!</td>
+        <td></td>
+      </tr>
+    </tbody>
+  </table>
+
+
+To limit the fields, change the order, or to include fields that are excluded by default (such as created_at),
+You can list methods to call on each resource:
+
+  <% table_for(@posts) do |t| %>
+    <%= t.data :author, :title, :created_at %>
+  <% end %>
+
+will produce html like:
+
+  <table id="posts">
+    <thead>
+      <tr>
+        <th>Author</th>
+        <th>Title</th>
+        <th>Created at</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr id="post_1" class="post odd">
+        <td>Jim Beam</td>
+        <td>Something</td>
+        <td>2009-11-15 02:42:48 UTC</td>
+      </tr>
+      <tr id="post_2" class="post even">
+        <td>Jack Daniels</td>
+        <td>Second Post</td>
+        <td>2009-11-16 00:11:00 UTC</td>
+      </tr>
+      <tr id="post_3" class="post odd">
+        <td></td>
+        <td>Something else</td>
+        <td>2009-11-16 00:11:30 UTC</td>
+      </tr>
+    </tbody>
+  </table>
+
+For even greater flexibility, you can pass +data+ a block:
+
+  <% table_for(@posts) do |t| %>
+    <% t.data do %>
+      <%= t.cell(:title, :cell_html => {:class => "titlestring"}) %>
+      <%= t.cell(:body, :heading => "Content") {|p| truncate(p.body, 30)} %>
+      <%= t.cell(:author) {|p| p.author && link_to(p.author.name, p.author) } %>
+      <%= t.cell(:edit, :heading => '') {|p| link_to "Edit", edit_post_path(p) } %>
+    <% end -%>
+  <% end %>
+
+will product html like:
+
+  <table id="posts">
+    <thead>
+      <tr>
+        <th>Title</th>
+        <th>Content</th>
+        <th>Author</th>
+        <th></th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr class="post odd" id="post_1">
+        <td class="titlestring">Something</td>
+        <td>Lorem ipsum dolor sit amet,...</td>
+        <td>
+          <a href="/authors/1">Jim Bean</a>
+        </td>
+        <td>
+          <a href="/posts/1/edit">Edit</a>
+        </td>
+      </tr>
+      <tr class="post even" id="post_2">
+        <td class="titlestring">Second Post</td>
+        <td>This is the second post</td>
+        <td>
+          <a href="/authors/2">Jack Daniels</a>
+        </td>
+        <td>
+          <a href="/posts/2/edit">Edit</a>
+        </td>
+      </tr>
+      <tr class="post odd" id="post_3">
+        <td class="titlestring">Something else</td>
+        <td>Blah!</td>
+        <td></td>
+        <td>
+          <a href="/posts/3/edit">Edit</a>
+        </td>
+      </tr>
+    </tbody>
+  </table>
+
+
+If it _still_ isn't flexible enough for your needs, it might be time to return to static html/erb.
 
 == Note on Patches/Pull Requests
 
 * Fork the project.
 * Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
 * Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but
-   bump version in a commit by itself I can ignore when I pull)
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
 == Copyright

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.1.0

data/lib/tabletastic.rb

@@ -1,5 +1,6 @@
 module Tabletastic
 
+  # returns and outputs a table for the given active record collection
   def table_for(collection, *args)
     options = args.extract_options!
     options[:html] ||= {}
@@ -14,35 +15,64 @@ module Tabletastic
   end
 
   class TableBuilder
-    @@association_methods = %w[to_label display_name full_name name title username login value to_s]
+    @@association_methods = %w[display_name full_name name title username login value to_s]
+    attr_accessor :field_labels
 
     def initialize(collection, template)
       @collection, @template = collection, template
     end
 
+    # builds up the fields that the table will include,
+    # returns table head and body with all data
     def data(*args, &block)
       if block_given?
         yield self
-        @template.concat(headers)
+        @template.concat(head)
         @template.concat(body)
       else
         @fields = args unless args.empty?
-        headers + body
+        @field_labels = fields.map { |f| f.to_s.humanize }
+        [head, body].join("")
       end
     end
 
-    def headers
+    def cell(*args, &block)
+      options = args.extract_options!
+      @field_labels ||= []
+      @fields ||= []
+
+      method_or_attribute = args.first.to_sym
+
+      if cell_html = options.delete(:cell_html)
+        @fields << [method_or_attribute, cell_html]
+      elsif block_given?
+        @fields << block.to_proc
+      else
+        @fields << method_or_attribute
+      end
+
+      if heading = options.delete(:heading)
+        @field_labels << heading
+      else
+        @field_labels << method_or_attribute.to_s.humanize
+      end
+
+      return "" # Since this will likely be called with <%= erb %>, this suppresses strange output
+    end
+
+    def head
+      @field_labels ||= fields
       content_tag(:thead) do
         header_row
       end
     end
 
     def header_row
-      output = "<tr>"
-      fields.each do |field|
-        output += content_tag(:th, field.to_s.humanize)
+      content_tag(:tr) do
+        @field_labels.inject("") do |result,field|
+          result += content_tag(:th, field)
+        end
       end
-      output += "</tr>"
     end
 
     def body
@@ -61,49 +91,66 @@ module Tabletastic
     end
 
     def tds_for_row(record)
-      fields.inject("") do |cells, field|
-        cells += content_tag(:td, cell_for(record, field))
+      fields.inject("") do |cells, field_or_array|
+        field = field_or_array
+        if field_or_array.is_a?(Array)
+          field = field_or_array.first
+          html_options = field_or_array.last
+        end
+        cells += content_tag(:td, cell_data(record, field), html_options)
       end
     end
 
-    def cell_for(record, method_or_attribute)
-      result = record.send(method_or_attribute)
+    def cell_data(record, method_or_attribute_or_proc)
+      # Get the attribute or association in question
+      result = send_or_call(record, method_or_attribute_or_proc)
+      # If we already have a string, just return it
       return result if result.is_a?(String)
+
+      # If we don't have a string, its likely an association
+      # Try to detect which method to use for stringifying the attribute
       to_string = detect_string_method(result)
       result.send(to_string) if to_string
     end
 
+    def fields
+      return @fields if defined?(@fields)
+      @fields = @collection.empty? ? [] : active_record_fields_for_object(@collection.first)
+    end
+
+    protected
+
     def detect_string_method(association)
       @@association_methods.detect { |method| association.respond_to?(method) }
     end
 
-    def cell(method_or_attribute)
-      @fields ||= []
-      @fields << method_or_attribute.to_sym
-      return ""
+
+    def active_record_fields_for_object(obj)
+      # normal content columns
+      fields = obj.class.content_columns.map(&:name)
+
+      # active record associations
+      associations = obj.class.reflect_on_all_associations(:belongs_to) if obj.class.respond_to?(:reflect_on_all_associations)
+      if associations
+        associations = associations.map(&:name)
+        fields += associations
+      end
+
+      # remove utility columns by default
+      fields -= %w[created_at updated_at created_on updated_on lock_version version]
+      fields = fields.map(&:to_sym)
     end
 
-    def fields
-      return @fields if defined?(@fields)
-      if @collection.empty?
-        @fields = []
+    def send_or_call(object, duck)
+      if duck.is_a?(Proc)
+        duck.call(object)
       else
-        object = @collection.first
-        associations = object.class.reflect_on_all_associations(:belongs_to) if object.class.respond_to?(:reflect_on_all_associations)
-        @fields = object.class.content_columns.map(&:name)
-        if associations
-          associations = associations.map(&:name)
-          @fields += associations
-        end
-        @fields -= %w[created_at updated_at created_on updated_on lock_version version]
-        @fields.map!(&:to_sym)
+        object.send(duck)
       end
     end
 
-    private
-
-      def content_tag(name, content = nil, options = nil, escape = true, &block)
-        @template.content_tag(name, content, options, escape, &block)
-      end
+    def content_tag(name, content = nil, options = nil, escape = true, &block)
+      @template.content_tag(name, content, options, escape, &block)
+    end
   end
 end

data/spec/tabletastic_spec.rb

@@ -20,15 +20,15 @@ describe "Tabletastic#table_for" do
       output_buffer.should have_tag("table")
     end
 
-    context "headers and table body" do
+    context "head and table body" do
       before do
         table_for([]) do |t|
-          concat(t.headers)
+          concat(t.head)
           concat(t.body)
         end
       end
 
-      it "should build a basic table and headers" do
+      it "should build a basic table and head" do
         output_buffer.should have_table_with_tag("thead")
       end
 
@@ -69,7 +69,7 @@ describe "Tabletastic#table_for" do
           output_buffer.should have_tag("table#posts")
         end
 
-        it "should output headers" do
+        it "should output head" do
           output_buffer.should have_table_with_tag("thead")
         end
 
@@ -162,6 +162,49 @@ describe "Tabletastic#table_for" do
         end
       end
 
+      context "with custom cell options" do
+        before do
+          table_for(@posts) do |t|
+            t.data do
+              concat(t.cell(:title, :heading => "FooBar"))
+              concat(t.cell(:body, :cell_html => {:class => "batquux"}))
+            end
+          end
+        end
+
+        it "should change the heading label for :heading option" do
+          output_buffer.should have_table_with_tag("th", "FooBar")
+          output_buffer.should have_table_with_tag("th", "Body")
+        end
+
+        it "should pass :cell_html to the cell" do
+          output_buffer.should have_table_with_tag("td.batquux")
+        end
+      end
+
+      context "with custom cell options" do
+        before do
+          table_for(@posts) do |t|
+            t.data do
+              concat(t.cell(:title) {|p| link_to p.title, "/" })
+              concat(t.cell(:body, :heading => "Content") {|p| p.body })
+            end
+          end
+        end
+
+        it "accepts a block as a lazy attribute" do
+          output_buffer.should have_table_with_tag("th:nth-child(1)", "Title")
+          output_buffer.should have_table_with_tag("td:nth-child(1)") do |td|
+            td.should have_tag("a", "The title of the post")
+          end
+        end
+
+        it "accepts a block as a lazy attribute (2)" do
+          output_buffer.should have_table_with_tag("th:nth-child(2)", "Content")
+          output_buffer.should have_table_with_tag("td:nth-child(2)", "Lorem ipsum")
+        end
+      end
+
       context "and normal/association columns" do
         before do
           ::Post.stub!(:reflect_on_all_associations).with(:belongs_to).and_return([@mock_reflection_belongs_to_author])

data/tabletastic.gemspec

@@ -0,0 +1,56 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{tabletastic}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Joshua Davey"]
+  s.date = %q{2009-11-17}
+  s.description = %q{A table builder for active record collections   that produces semantically rich and accessible markup}
+  s.email = %q{josh@joshuadavey.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/tabletastic.rb",
+     "rails/init.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb",
+     "spec/tabletastic_spec.rb",
+     "tabletastic.gemspec"
+  ]
+  s.homepage = %q{http://github.com/jgdavey/tabletastic}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{A smarter table builder for Rails collections}
+  s.test_files = [
+    "spec/spec_helper.rb",
+     "spec/tabletastic_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+  end
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: tabletastic
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors: 
 - Joshua Davey
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-15 00:00:00 -06:00
+date: 2009-11-17 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -43,6 +43,7 @@ files:
 - spec/spec.opts
 - spec/spec_helper.rb
 - spec/tabletastic_spec.rb
+- tabletastic.gemspec
 has_rdoc: true
 homepage: http://github.com/jgdavey/tabletastic
 licenses: []