sortablecolumns 0.1.0

data/History.txt

@@ -0,0 +1,3 @@
+=== 0.1.0 / 2008-04-29
+
+* Initial Release

data/Manifest.txt

@@ -0,0 +1,12 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/sortable_columns
+lib/sortablecolumns.rb
+lib/sortablecolumns/helpers.rb
+lib/sortablecolumns/sortable_columns.rb
+test/col_def_test_yaml_files/person/dude/dude_report.yml
+test/col_def_test_yaml_files/person/mysorter.yml
+test/col_def_test_yaml_files/person/tacosorter.yml
+test/sortablecolumns_test.rb

data/README.txt

@@ -0,0 +1,202 @@
+= SortableColumns
+
+* http://rubyforge.org/projects/sortablecolumns/
+
+== DESCRIPTION:
+
+SortableColumns is a Rails plugin that allows easy creation of sortable HTML tables as plain HTML or as a YUI DataTable (requires YUI4Rails plugin - http://rubyforge.org/projects/yui4rails/).  Table column characteristics (e.g., default sort direction, data type, CSS attributes, and methods to wrap the output in) are defined in YAML files (more options to be added later, such auto-detecting the column types, using a hash, etc.). Multiple table column definitions can be created for a single model.
+
+An example live application can be found here: http://sortablecolumns.heroku.com/
+Download the example app here: http://www.bryandonovan.com/sortable_columns_example.tar.gz
+
+Also see: ActiveRecord::Acts::SortableColumns::ClassMethods#sortable_columns
+
+== INSTALL:
+
+* sudo gem install sortablecolumns
+* IMPORTANT: create a directory named col_defs in your app/models directory if you want to use the default YAML directory (otherwise you can specify a path using :path_prefix).
+
+== FEATURES/PROBLEMS:
+
+=== Features
+* Simple to define column characteristics in YAML
+* Can be used with regular HTML or with YUI DataTable (http://developer.yahoo.com/yui/datatable/)
+* Allows definitions of arbitrary columns, so you aren't limited to the columns in your model.  E.g., 
+  you can use custom SQL queries that return a mix of columns from different models or "virtual" columns
+  created in the SQL query.
+* Test coverage for all current features.
+
+=== Problems
+* Doesn't yet support date formats (should be easy to implement though and will hopefully happen soon)
+
+== SYNOPSIS:
+* First, create a directory to store your column definitions YAML files.  The default location SortableColumns will look is app/models/col_defs. 
+* Create a YAML file for the configuration of your table columns.
+* Call sortable_tables in your model
+* Run query (get an ActiveRecord result set)
+* Render table in your view
+
+=== Example Usage
+Say we have a Person model (or a custom SQL query result) with the following columns/attributes:
+* firstname - string, should be a link to the people/show action, TD CSS class of "left".
+* lastname - string, should be wrapped in sanitize.
+* age - integer, default sort direction: descending. TD CSS class: "center".
+* description - string/text - should have a TD CSS class of "left", should be wrapped in auto_link, sanitize, and simple_format.
+* balance - decimal/currency - precision of 2, comma for a separator, space for delimiter, British pound for unit. Default sort: descending.
+* edit and detroy links, called "Edit" and "Delete" (which, of course, are not fields in the query result, but will be in the displayed table).
+
+We're going to call this sorter "mysorter".  This will be the name of the YAML file and the name passed into the sortable_columns method in the model.
+
+In model:
+
+  class Person < ActiveRecord::Base
+    sortable_columns :mysorter
+
+    # method to run query with sort options
+    def self.find_for_mysorter(options = {})
+      order_by = options[:order_by]
+      dir = options[:dir]
+      query = "select * from people"
+      query << " order by #{order_by}" if order_by
+      query << " #{dir}" if dir
+      Person.find_by_sql(query)
+    end
+  end
+
+YAML file:
+-
+  firstname:
+    heading: First
+    datatype: string
+    link_options:
+      controller: people
+      action: show
+      id: obj_id
+    td_class: left
+
+-
+  lastname:
+    heading: Last
+    datatype: string
+    print_options:
+      wrappers: sanitize
+-
+  age:
+    datatype: number
+    sort_options:
+      default_dir: desc
+    td_class: center
+-
+  description:
+    datatype: string
+    sortable: false
+    print_options:
+      wrappers:
+        - auto_link
+        - sanitize
+        - simple_format
+    td_class: left
+-
+  balance:
+    datatype: currency
+    precision: 2
+    separator: ","
+    delimiter: " "
+    unit: £
+    td_class: right
+-
+  edit:
+    in_resultset: false
+    heading: false
+    th_class: invisible
+    print_text: Edit
+    link_options:
+      controller: people
+      action: edit
+      id: obj_id
+-
+  delete:
+    in_resultset: false
+    heading: false
+    th_class: invisible
+    print_text: Delete
+    link_options:
+      controller: people
+      action: destroy
+      id: obj_id
+      extras:
+        method: delete
+        confirm: Are you sure?
+
+In the link_options, use obj_id to specify that the current object's id field should be used.
+
+In the controller:
+
+  def index #plain HTML table
+    @people = Person.find_for_mysorter(options=params.dup)
+    respond_to do |format|
+      format.html
+    end
+  end
+
+  def yui #YUI DataTable
+    @people = Person.find_for_mysorter(options=params.dup)
+    @col_defs = Person.mysorter_col_defs_for_yui
+    @data_keys = Person.mysorter_fields_for_yui
+
+    @data_table = Yui4Rails::Widgets::DataTable.new(:table_div_id => "markup",
+      :col_defs => @col_defs,
+      :data_keys => @data_keys,
+      :table_id => 'yui_table')
+
+    @data_table.paginate(5)
+
+    respond_to do |format|
+      format.html # index.html.erb
+    end
+  end
+
+In the view:
+
+ <%= print_table(@people, :mysorter %>
+Or if you want alternating styles for table rows:
+ <%= print_table(@people, :mysorter, :tr => {:classes => ['even','odd']}) %>
+And you can specify a table CSS class & id:
+ <%= print_table(@people, :mysorter, :table => {:class => 'yui-skin-sam', :id => 'yui_table'}) %>
+
+For YUI DataTable, add the followoing after the print_table call:
+ <%= @data_table.render(:source => :html)%>
+Also make sure the table is inside a div with the same id as specified in the controller when using the YUI DataTable.
+
+== REQUIREMENTS:
+
+* YUI4Rails gem if you want to use YUI datatables
+
+== Disclaimer 
+
+This is beta-quality software. It works well according to my tests, but the API may change and other features may be added.
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Bryan Donovan
+
+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/Rakefile

@@ -0,0 +1,22 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/sortablecolumns.rb'
+
+Hoe.new('sortablecolumns', Sortablecolumns::VERSION) do |p|
+  p.name = "sortablecolumns"
+  p.author = "Bryan Donovan - http://www.bryandonovan.com"
+  p.email = "b.dondo+rubyforge@gmail.com"
+  p.description = "Sortable HTML tables for Rails"
+  p.summary = "Sortable HTML tables for Rails"
+  p.url = "http://rubyforge.org/projects/sortablecolumns/"
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.remote_rdoc_dir = '' # Release to root
+end
+
+rule '' do |t|
+  system "cd test && ruby sortablecolumns_test.rb"
+end
+
+# vim: syntax=Ruby

data/lib/sortablecolumns.rb

@@ -0,0 +1,6 @@
+module Sortablecolumns #:nodoc:
+  VERSION = '0.1.0'
+end
+Dir[File.join(File.dirname(__FILE__), "sortablecolumns/**/*.rb")].sort.each { |lib| require lib }
+ActiveRecord::Base.send(:include, ActiveRecord::Acts::Sortablecolumns)
+ActionView::Base.send(:include, Sortablecolumns::Helpers)

data/lib/sortablecolumns/helpers.rb

@@ -0,0 +1,167 @@
+module Sortablecolumns
+  module Helpers
+
+    #Prints entire HTML table with content
+    def print_table(collection, sorter, options={})
+      klass = collection.first.class
+      txt = print_table_thead(klass, sorter)
+      txt << print_table_body(collection, sorter, options)
+      return content_tag('table', txt, options[:table])
+    end
+
+    #Prints a single table column (TD element) with content
+    def print_col(obj, sorter, col)
+      col = col.to_s
+      klass = obj.class
+      txt = klass.send("#{sorter}_col_text",obj,col) 
+      wrappers = []
+
+      datatype = klass.send("#{sorter}_datatype",col) || 'string'
+
+      if datatype == 'number'
+        precision = klass.send("#{sorter}_precision",col) 
+        txt = number_with_precision(txt, precision) if precision
+      end
+
+      if datatype == 'currency'
+        precision = klass.send("#{sorter}_precision",col) 
+        unit      = klass.send("#{sorter}_unit",col) 
+        separator = klass.send("#{sorter}_separator",col) 
+        delimiter = klass.send("#{sorter}_delimiter",col) 
+        txt = number_to_currency(txt, :precision => precision, 
+        :unit => unit, :separator => separator, :delimiter => delimiter)
+      end
+
+      do_link = klass.send("#{sorter}_link?",col)
+
+      if do_link
+        link_ops = klass.send("#{sorter}_link_options",col).dup
+        raise "link_options must be defined for #{klass}:#{col}" unless link_ops
+        if link_ops[:object_url]
+          txt = link_to(txt, send("#{klass.to_s.downcase}_url", obj))
+        elsif link_ops[:controller] && link_ops[:action]
+          if link_ops[:id] && link_ops[:id] == 'obj_id'
+            link_ops[:id] = obj.id
+          end
+          if link_ops[:extras]
+            extras = link_ops.delete(:extras)
+            txt = link_to(txt, link_ops, extras)
+          else
+            txt = link_to(txt, link_ops)
+          end
+        elsif link_ops[:url]
+          url = link_ops[:url].gsub(/:id/, obj.id.to_s)
+          unless url.match(/http/)
+            url = 'http://' + default_url_options[:host] + url
+          end
+          txt = link_to(txt, url)
+        end
+      end
+
+      print_options = klass.send("#{sorter}_print_options",col)
+      wrappers << print_options['wrappers'] if print_options && print_options['wrappers']
+
+      wrappers.flatten.each do |wrapper|
+        if wrapper.is_a? Hash
+          key = wrapper.keys.first
+          extra_args = wrapper[key]
+          txt = send(key, txt, extra_args)
+        else
+          txt = send(wrapper, txt)
+        end
+      end
+
+      td_class = klass.send("#{sorter}_td_class",col)
+
+      return content_tag("td", txt, :class => td_class)
+    end
+
+    #Prints single table row with content
+    def print_table_row(obj, sorter, options={})
+      txt = ''
+      klass = obj.class
+      cols = klass.send("#{sorter}_col_keys_in_order")
+      cols.each do |col|
+        txt << print_col(obj, sorter, col)
+      end
+      content_tag("tr", txt, options)
+    end
+
+    #Prints table body with content
+    def print_table_body(collection, sorter, options={})
+      txt = ""
+      if options[:tr] && options[:tr][:classes]
+        alternate = true
+        tr_classes = options[:tr][:classes]
+      end
+      tr_class = nil
+      i = 0
+      collection.each do |obj|
+        if alternate 
+          tr_class = tr_classes[i % 2]
+        end
+        txt << print_table_row(obj, sorter, :class => tr_class) 
+        i += 1
+      end
+      content_tag("tbody", txt)
+    end
+
+    #Prints single TH tag with content
+    def print_col_heading(klass, sorter, col, options={})
+      col      = col.to_s
+      th_txt   = klass.send("#{sorter}_heading", col)
+      th_class = klass.send("#{sorter}_th_class", col)
+      return content_tag("th", '', :class => th_class) unless th_txt
+      sortable = klass.send("#{sorter}_sortable?", col)
+      return content_tag("th", th_txt, :class => th_class) unless sortable
+      url = get_col_heading_url(klass, sorter, col)
+      link = link_to(th_txt, url)
+      return content_tag("th", link, :class => th_class)
+    end
+
+    #Get URL for sortable table column header (TH element)
+    def get_col_heading_url(klass, sorter, col)
+      order_by    = col
+      default_dir = 'asc'
+      sort_ops = klass.send("#{sorter}_sort_options", col)
+      if sort_ops
+        order_by    = sort_ops['order_by']    if sort_ops['order_by']
+        default_dir = sort_ops['default_dir'] if sort_ops['default_dir']
+      end
+
+      reg = Regexp.new(order_by.to_s)
+      if params[:order_by] =~ reg
+        dir = (params[:dir] == "asc") ? "desc" : "asc"
+      else
+        dir = default_dir
+      end
+
+      get_url(order_by, dir)
+    end
+
+    #get url for given set of params, order_by, and dir
+    def get_url(order_by, dir)
+      _params = params.dup
+      _params[:order_by] = order_by
+      _params[:dir] = dir 
+      url_for(_params)
+    end
+
+    #Prints a row of TH tags with content
+    def print_table_heading_row(klass, sorter, options={})
+      cols = klass.send("#{sorter}_col_keys_in_order")
+      txt = ''
+      cols.each do |col|
+        txt << print_col_heading(klass, sorter, col)
+      end
+      txt
+      content_tag("tr", txt, options)
+    end
+
+    #Prints THEAD tags with content
+    def print_table_thead(klass, sorter)
+      content_tag('thead', print_table_heading_row(klass, sorter))
+    end
+
+  end 
+end

data/lib/sortablecolumns/sortable_columns.rb

@@ -0,0 +1,254 @@
+# Sortablecolumns Rails Plugin
+# Lets you define column definitions for a sortable HTML table.
+# Author: Bryan Donovan 
+# March 2008
+
+require 'active_record'
+require 'active_support'
+require 'action_controller'
+
+module ActiveRecord #:nodoc:
+  module Acts #:nodoc:
+    module Sortablecolumns
+      def self.included(base) # :nodoc:
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        include ActiveSupport::CoreExtensions::Hash::Keys
+
+        # == Configuration options
+        #
+        # * <tt>sorter_name</tt> (required) - specify the name of the sorter, same name used for YAML file, method prefixes
+        # * <tt>subclass_name</tt> (optional) - specify the subclass name if your model inherits from another model.  You must create your YAML file in a subdirectory of the same name (lowercase).  E.g., app/models/person/manager_sorter.yml for a Manager model that inherits from the Person model.
+        # * <tt>path_prefix</tt> (optional) - path to your column definitions directory where your YAML files are stored (relative to RAILS_ROOT). If this isn't specified, Sortablecolumns looks for column definitions in /app/models/col_defs, but you must create that directory manually.  
+        # == Examples
+        # class Person < ActiveRecord::Base
+        #   sortable_columns :mysorter
+        #   sortable_columns :othersorter, :path_prefix => '/my_column_defs'
+        # end
+
+        # class Manager < Person
+        #   sortable_columns :manager_sorter, :subclass_name => 'Manager' 
+        # end
+        def sortable_columns(sorter_name, options = {})
+          options = {:subclass_name => nil, :path_prefix => nil}.merge(options)
+          write_inheritable_attribute(:sorter_options, options)
+          class_inheritable_reader :sorter_options
+
+          self.class_eval <<-END
+            def self.#{sorter_name}_cols=(val)
+              @@#{sorter_name}_cols = val
+            end
+
+            def self.#{sorter_name}_cols
+              @@#{sorter_name}_cols
+            end
+            cattr_accessor :#{sorter_name}_cols
+
+            def self.#{sorter_name}_col_defs
+              @@#{sorter_name}_cols ||= #{sorter_name}_initialize_col_defs
+            end
+
+            def self.#{sorter_name}_col_text(obj, col)
+               return obj.send(col) if self.#{sorter_name}_in_resultset?(col)
+               return self.#{sorter_name}_print_text(col)
+            end
+
+            def self.#{sorter_name}_yaml_path
+              raise "RAILS_ROOT is not defined" unless defined?(RAILS_ROOT)
+              #klass_name = self.class_name.downcase
+              klass_name = Inflector.underscore(self.class_name)
+              file_name = "#{sorter_name}.yml"
+              if sorter_options[:subclass_name]
+                sub_path = File.join(klass_name, Inflector.underscore(sorter_options[:subclass_name]), file_name)
+              else
+                sub_path = File.join(klass_name, file_name)
+              end
+              if sorter_options[:path_prefix]
+                return File.join(RAILS_ROOT, sorter_options[:path_prefix], sub_path)
+              else
+                #defaults to col_defs subdirectory in app/models
+                return File.join(RAILS_ROOT, "app/models/col_defs", sub_path)
+              end
+            end
+
+            def self.#{sorter_name}_initialize_col_defs
+              YAML.load_file(#{sorter_name}_yaml_path)
+            end
+
+            def self.#{sorter_name}_col_def_hash
+              @@#{sorter_name}_col_def_hash ||= #{sorter_name}_initialize_col_def_hash
+            end
+
+            def self.#{sorter_name}_initialize_col_def_hash
+              col_def_hash = {}
+              #{sorter_name}_col_defs.each do |c|
+                c.keys.each do |key|
+                  col_def_hash[key] = c[key]
+                end
+              end
+              col_def_hash
+            end
+
+            def self.#{sorter_name}_col_keys_in_order
+              @@#{sorter_name}_col_keys_in_order ||= #{sorter_name}_initialize_col_keys_in_order
+            end
+
+            def self.#{sorter_name}_initialize_col_keys_in_order
+              cols = []
+              #{sorter_name}_col_defs.each do |hsh|
+                hsh.each do |key, sub_hash|
+                  cols << key
+                end
+              end
+              cols
+            end
+
+            def self.#{sorter_name}_heading(col)
+              return false if #{sorter_name}_col_def_hash[col]['heading'] == false
+              #{sorter_name}_col_def_hash[col]['heading'] || col.humanize
+            end
+
+            def self.#{sorter_name}_headings_in_order
+              @@#{sorter_name}_headings_in_order ||= #{sorter_name}_initialize_headings_in_order
+            end
+
+            def self.#{sorter_name}_initialize_headings_in_order
+              headings = []
+              #{sorter_name}_col_keys_in_order.each do |key|
+                headings << #{sorter_name}_heading(key) if #{sorter_name}_heading(key)
+              end
+              headings
+            end
+
+            def self.#{sorter_name}_col_def(col)
+              #{sorter_name}_col_def_hash[col]
+            end
+
+            def self.#{sorter_name}_datatype(col)
+              #{sorter_name}_col_def_hash[col]['datatype']
+            end
+
+            def self.#{sorter_name}_sort_options(col)
+              #{sorter_name}_col_def_hash[col]['sort_options']
+            end
+
+            def self.#{sorter_name}_default_sort_dir(col)
+              if sort_ops = #{sorter_name}_col_def_hash[col]['sort_options']
+                sort_ops['default_dir'] ? sort_ops['default_dir'] : 'asc'
+              else 
+                'asc'
+              end
+            end
+            
+            def self.#{sorter_name}_print_options(col)
+              if #{sorter_name}_col_def_hash[col]
+                #{sorter_name}_col_def_hash[col]['print_options']
+              end
+            end
+            
+            def self.#{sorter_name}_td_class(col)
+              #{sorter_name}_col_def_hash[col]['td_class']
+            end
+
+            def self.#{sorter_name}_th_class(col)
+              #{sorter_name}_col_def_hash[col]['th_class']
+            end
+
+            def self.#{sorter_name}_precision(col)
+              #{sorter_name}_col_def_hash[col]['precision']
+            end
+
+            def self.#{sorter_name}_delimiter(col)
+              #{sorter_name}_col_def_hash[col]['delimiter'] || ","
+            end
+
+            def self.#{sorter_name}_separator(col)
+              #{sorter_name}_col_def_hash[col]['separator'] || "."
+            end
+
+            def self.#{sorter_name}_unit(col)
+              #{sorter_name}_col_def_hash[col]['unit'] || "$"
+            end
+
+            def self.#{sorter_name}_print_text(col)
+              #{sorter_name}_col_def_hash[col]['print_text'] || '' 
+            end
+
+            def self.#{sorter_name}_sortable?(col)
+              hsh = #{sorter_name}_col_def_hash[col]
+              return false if hsh.has_key?('sortable') && hsh['sortable'] == false
+              return false if hsh.has_key?('heading') && hsh['heading'] == false
+              return true
+            end
+
+            def self.#{sorter_name}_link_options(col)
+              link_ops = #{sorter_name}_col_def_hash[col]['link_options']
+              return link_ops.symbolize_keys! if link_ops 
+            end
+
+            def self.#{sorter_name}_link?(col)
+              return true if #{sorter_name}_link_options(col)
+              return false
+            end
+
+            def self.#{sorter_name}_in_resultset?(col)
+              hsh = #{sorter_name}_col_def_hash[col]
+              return false if hsh.has_key?('in_resultset') && hsh['in_resultset'] == false
+              return true
+            end
+
+            def self.#{sorter_name}_col_def_for_yui(col)
+              label = #{sorter_name}_heading(col) ? #{sorter_name}_heading(col) : ''
+              sortable = #{sorter_name}_sortable?(col)
+              datatype = #{sorter_name}_datatype(col)
+              if datatype == 'number' or datatype == 'currency'
+                formatter = datatype
+              end
+              sort_dir = #{sorter_name}_default_sort_dir(col)
+              if sort_dir == 'desc'
+                sort_ops =  {:defaultDir => "YAHOO.widget.DataTable.CLASS_DESC"}
+              end
+              yui = {:key => col, :label => label, :sortable => sortable}
+              yui[:sortOptions] = sort_ops  if sort_ops
+              yui[:formatter]   = formatter if formatter
+              yui
+            end
+
+            def self.#{sorter_name}_col_defs_for_yui
+              yui_col_defs = [] 
+              #{sorter_name}_col_keys_in_order.each do |col|
+                yui_col_defs << #{sorter_name}_col_def_for_yui(col)
+              end
+              yui_col_defs
+            end
+
+            def self.#{sorter_name}_field_def_for_yui(col)
+              datatype = #{sorter_name}_datatype(col)
+              yui_field_def = {:key => col}
+              if datatype == 'number'
+                yui_field_def[:parser] = "YAHOO.util.DataSource.parseNumber"
+              end
+              if  datatype == 'currency'
+                yui_field_def[:parser] = "this.parseNumberFromCurrency"
+              end
+              yui_field_def
+            end
+
+            def self.#{sorter_name}_fields_for_yui
+              yui_fields = []
+              #{sorter_name}_col_keys_in_order.each do |col|
+                yui_fields << #{sorter_name}_field_def_for_yui(col)
+              end
+              yui_fields
+            end
+
+
+            END
+
+        end #sortable_columns
+      end #ClassMethods
+    end #Sortablecolumns
+  end #Acts
+end #ActiveRecord