sorting_table_for 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 arkownz (tom)
+
+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.mdown

@@ -0,0 +1,213 @@
+# SortingTableFor
+
+## Introduction
+
+SortingTableFor is a Rails TableBuilder made to easily create table or sort a table. The syntax is simple to write and easy to read.
+
+## Infos
+
+- It's Rails 2.3 and 3 compatible
+- I18n compatible
+- Almost fully configurable
+
+## Installation
+
+Install with git
+
+    cd your_rails_app
+    cd vendor/plugins
+    git clone git://github.com/arkownz/sorting_table_for.git
+
+## Usage
+
+To create a simple table
+
+    <%- sorting_table_for @users do |table| %>
+      <%= table.headers %>
+      <%= table.columns %>
+    <%- end %>
+
+will render
+
+    <table>
+      <thead>
+        <tr>
+          <th><a href='/to_sort'>Username</a></th>
+          <th><a href='/to_sort'>Firstname</a></th>
+          <th>Edit</th>
+          <th>Delete</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td colspan='4'>Total rows : 1</td>
+        </tr>
+        <tr>
+          <td>Test</td>
+          <td>Myname</td>
+          <td><a href='/to_edit'>Edit</a></td>
+          <td><a href='/to_delete'>Delete</a></td>
+        <tr>
+      </tbody>
+    </table>
+
+You can specify columns and headers
+
+    <%- sorting_table_for @users do |table| %>
+      <%= table.headers :username, :firstname, :lastname %>
+      <%= table.columns :username, :firstname, :lastname %>
+    <%- end %>
+
+On columns you can get the object of your collection.
+Your can pass to column or header what ever your want: symbol, string, image, ...
+
+    <%- sorting_table_for @users do |table| %>
+      <%= table.headers do %>
+        <%= table.header :username %>
+        <%= table.header :firstname %>
+        <%= table.header image_tag('rails.png') %>
+      <%- end %>
+      <%= table.columns do |user| %>
+        <%= table.column :username %>
+        <%= table.column user.firstname %>
+        <%= table.column 'exemple' %>
+      <%- end %>
+    <%- end %>
+    
+For more control on headers or columns
+
+    <%- sorting_table_for @users do |table| %>
+      <%= table.headers do %>
+        <%= table.header do %>
+          <%= image_tag('rails.png') %>
+        <%- end %>
+      <%- end %>
+      <%= table.columns do |val| %>
+        <%= table.column do %>
+          <%= val.username.downcase %>
+        <%- end %>
+      <%- end %>
+    <%- end %>
+
+By default SortingTableFor will customize your table
+
+Header:
+
+- On symbol it make by default a sorting
+- On symbol it will add the translation (I18n.t)
+- On sorting it will add a class with an image to show the sort order
+
+Column:
+
+- On Symbol it will find the value in collection
+- On Object Date or DateTime it will add the localization (I18n.l)
+- On Column name (price, total_price, ...) it will the currency
+- On Boolean it will add the translation (I18n.t) true or false
+
+You can customize the table
+
+    <%- sorting_table_for @users do |table| %>
+      <%= table.headers do %>
+        <%= table.header :username %>
+        <%= table.header :price, :sort => false %>
+        <%= table.header :created_at %>
+        <%= table.header 'today' %>
+      <%- end %>
+      <%= table.columns do |user| %>
+        <%= table.column user.username %>
+        <%= table.column user.price, :as => :currency %>
+        <%= table.column user.created, :as => :date %>
+        <%= table.column DateTime.now, :as => :datetime, :format => :short %>
+      <%- end %>
+    <%- end %>
+
+You can customize the table with action
+
+    <%- sorting_table_for @users do |table| %>
+      <%= table.headers do %>
+        <%= table.header :username %>
+        <%= table.header :action => :edit %>
+      <%- end %>
+      <%= table.columns do |user| %>
+        <%= table.column user.username, :action => :show %>
+        <%= table.column :action => :edit %>
+      <%- end %>
+    <%- end %>
+
+You can customize the html and add title
+
+    <%- sorting_table_for @users, :html => { :class => 'my_table' } do |table| %>
+      <%= table.headers :html => { :class => 'my_headers', :title => 'column !' } do %>
+        <%= table.header :username :html => { :class => 'header_username' } %>
+        <%= table.header :firstname :html => { :title => 'hello price' } %>
+      <%- end %>
+      <%= table.columns :html => { :class => 'my_columns' } do |user| %>
+        <%= table.column :username :html => { :class => 'column_username' }%>
+        <%= table.column :firstname :html => { :title => "it's #{val.firstname}" } %>
+      <%- end %>
+    <%- end %>
+
+## Namespace
+
+SortingTableFor can use your namespace
+
+    <%- sorting_table_for [:admin, @users] do |table| %>
+      <%= table.headers %>
+      <%= table.columns %>
+    <%- end %>
+
+## Sorting
+
+To add sorting in your query, you just have to add sorting_table in your query
+
+    def index
+      @users = User.sorting_table(params).all
+    end
+
+to add a default sorting 
+
+    def index
+      @users = User.sorting_table(params, :username).all
+    end
+
+    -- or --
+    
+    def index
+      @users = User.sorting_table(params, :username, :desc).all
+    end
+
+## Ajax
+
+You can add ajax on sorting
+
+        <%- sorting_table_for @users, :sort_remote => true do |table| %>
+          <%= table.headers %>
+          <%= table.columns %>
+        <%- end %>
+
+You can add ajax on links
+
+        <%- sorting_table_for @users, :link_remote => true do |table| %>
+            <%= table.headers %>
+            <%= table.columns %>
+        <%- end %>
+
+## Stylesheet
+
+there are a default stylesheet in _stylesheet_
+
+- A class 'odd' or 'even' on rows
+- A class 'cur-sort-not', 'cur-sort-asc' or 'cur-sort-desc' on headers that you want to sort
+
+[_Here an exemple of css file_][]
+
+## Configurations
+
+There are some options that you can customize in your initiatilizer
+
+[_see the initializer file exemple for more explanation_][]
+
+Copyright (c) 2010 arkownz (tom), released under the MIT license
+
+[_see the initializer file exemple for more explanation_]: http://github.com/arkownz/sorting_table_for/blob/master/assets/config/initializers/sorting_table_for.rb
+[_Here an exemple of css file_]: http://github.com/arkownz/sorting_table_for/blob/master/assets/public/stylesheets/sorting_table_for.css

data/Rakefile

@@ -0,0 +1,11 @@
+require 'rake'
+require 'spec/rake/spectask'
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc 'Run the specs'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ['--colour --format progress --loadby mtime --reverse']
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end

data/init.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+
+# Require Helper
+require 'sorting_table_for'
+
+# Require Scoping helper
+require 'model/sorting_table_model_scope'

data/lib/model/sorting_table_model_scope.rb

@@ -0,0 +1,53 @@
+# encoding: utf-8
+
+module SortingTableModelScope
+  
+  def self.included(base)
+    base.extend(SingletonMethods)
+  end
+  
+  module SingletonMethods
+
+    def sorting_table(*args)
+      raise ArgumentError, 'sorting_table: Too many arguments (max : 3)' if args.size > 3 
+      sort_table_param = get_sorting_table_params(args)
+      return scoped({})  if !sort_table_param and args.size == 1
+      sort, direction = get_sort_and_direction(sort_table_param, args)
+      return scoped({}) if !sort or !valid_column?(sort) or !valid_direction?(direction)
+      return scoped({ :order => "#{sort} #{direction}" })
+    end
+
+    private
+
+    def get_sorting_table_params(args)
+      return nil unless args.first.is_a? Hash      
+      return nil unless args.first.has_key? SortingTableFor::TableBuilder.params_sort_table.to_s
+      args.first[SortingTableFor::TableBuilder.params_sort_table.to_s]
+    end
+  
+    def get_sort_and_direction(sort_table_param, args)
+      if sort_table_param
+        key = sort_table_param.keys.first rescue nil
+        value = sort_table_param.values.first rescue nil
+        return nil if !key.is_a?(String) or !value.is_a?(String)
+        return key, value
+      end
+      return nil if args.size < 2
+      return args[1], 'asc' if args.size == 2
+      return args[1], args[2]
+    end
+    
+    def valid_column?(column)
+      column_names.include? column.to_s.downcase
+    end
+    
+    def valid_direction?(direction)
+      %[asc desc].include? direction.to_s.downcase
+    end
+    
+ end  
+end
+
+if defined? ActiveRecord
+  ActiveRecord::Base.send :include, SortingTableModelScope
+end

data/lib/sorting_table_for.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+require 'sorting_table_for/table_builder'
+require 'sorting_table_for/i18n'
+require 'sorting_table_for/tools'
+
+module SortingTableFor
+  
+  def sorting_table_for(object_or_array, *args)
+    raise ArgumentError, 'Missing block' unless block_given?
+    options = args.extract_options!
+    html_options = (options[:html]) ? options[:html].merge(:class => "#{options[:html][:class]} sorting_table_for".strip) : { :class => :sorting_table_for }
+    builder = options[:builder] || TableBuilder
+    case object_or_array
+      when Array
+        if object_or_array.last.is_a?(Array)
+          object = object_or_array.last
+          object_or_array.pop
+        else
+          object = object_or_array
+          object_or_array = []
+        end
+      else
+        object = object_or_array
+        object_or_array = []
+    end
+    content_tag(:table, html_options) do
+      yield builder.new(object, object_or_array, self, options, params)
+    end
+  end
+  
+end
+
+# Include in ActionView Helper
+if defined? ActionView
+ ActionView::Base.send(:include, SortingTableFor)
+end

data/lib/sorting_table_for/i18n.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+
+module SortingTableFor
+  module I18n    
+    class << self
+      
+      def set_options(params, model_name, namespace)
+        @params, @model_name, @namespace = params, model_name, namespace
+      end
+      
+      def translate(attribute, options = {}, action_header = false)
+        if !options.has_key? :scope
+          options[:scope] = create_scope 
+          options[:scope] << TableBuilder.i18n_add_header_action_scope if action_header
+        end
+        ::I18n.t(attribute, options)
+      end
+      alias :t :translate
+      
+      private
+
+      def create_scope
+        return TableBuilder.i18n_default_scope.collect do |scope_value|
+          case scope_value.to_sym
+            when :controller then @params[:controller] ? @params[:controller].downcase : ''
+            when :action then @params[:action] ? @params[:action].downcase : ''
+            when :model then @model_name ? @model_name.downcase.to_s : ''
+            when :namespace then @namespace ? @namespace.downcase.to_s : ''
+            else scope_value.to_s
+          end
+        end
+      end
+      
+    end
+  end
+end

data/lib/sorting_table_for/table_builder.rb

@@ -0,0 +1,366 @@
+# encoding: utf-8
+
+module SortingTableFor
+  
+  private
+  
+  class TableBuilder
+    
+    include ::ActionView::Helpers::TagHelper
+    include ::ActionView::Helpers::NumberHelper
+    
+    class_inheritable_accessor :reserved_columns, :currency_columns,
+                               :default_boolean, :show_total_entries,
+                               :params_sort_table, :i18n_default_format_date,
+                               :html_sorting_class, :default_actions,
+                               :i18n_default_scope, :i18n_add_header_action_scope
+    
+    self.reserved_columns             = [:id, :password, :salt]
+    self.currency_columns             = [:price, :total_price, :currency, :money]
+    self.default_boolean              = [::I18n.t(:bolean_true, :scope => [:sorting_table_for, :columns]), ::I18n.t(:bolean_false, :scope => [:sorting_table_for, :columns])]
+    self.show_total_entries           = true
+    self.params_sort_table            = :table_sort
+    self.i18n_default_format_date     = :default
+    self.html_sorting_class           = [:'cur-sort-not', :'cur-sort-asc', :'cur-sort-desc']
+    self.default_actions              = [:edit, :delete]
+    self.i18n_default_scope           = [:namespace, :controller, :action]
+    self.i18n_add_header_action_scope = :header
+    
+    def initialize(collection, object_or_array, template, options, params)
+      @collection, @@object_or_array, @@template, @@options, @@params = collection, object_or_array, template, options, params
+      I18n.set_options(params, model_name(@collection.first), object_or_array.first)
+      set_default_global_options
+      @lines = []
+    end
+    
+    ##  Headers
+    
+    def headers(*args, &block)
+      column_options, html_options = get_column_and_html_options( args.extract_options! )
+      if block_given?
+        @header_line = FormatLine.new(args, column_options, html_options, nil, :thead)
+        @@template.capture(&block)
+      else
+        @header_line = FormatLine.new(args, column_options, html_options, @collection.first, :thead)
+      end
+      render_thead
+    end
+    
+    def header(*args, &block)
+      if block_given?
+        block = @@template.capture(&block)
+        @header_line.add_cell(@collection.first, args, nil, block)
+      else
+        @header_line.add_cell(@collection.first, args)
+      end
+      nil
+    end
+    
+    ##  Columns
+    
+    def columns(*args, &block)
+      column_options, html_options = get_column_and_html_options( args.extract_options! )
+      @collection.each do |object|
+        @current_object = object
+        if block_given?
+          @lines << FormatLine.new(args, column_options, html_options)
+          yield(object)
+        else
+          @lines << FormatLine.new(args, column_options, html_options, object)
+        end
+      end
+      render_tbody
+    end
+    
+    def column(*args, &block)
+      if block_given?
+        block = @@template.capture(&block)
+        @lines.last.add_cell(@current_object, args, nil, block)
+      else
+        @lines.last.add_cell(@current_object, args)
+      end
+      nil
+    end
+    
+    protected
+    
+    # This function is a copy from Formtastic: http://github.com/justinfrench/formtastic
+    def model_name(object)
+      object.present? ? object.class.name : object.to_s.classify
+    end
+    
+    private
+
+    def render_thead
+      if @header_line
+        return Tools::html_safe(content_tag(:thead, @header_line.render_line))
+      end
+      ''
+    end
+
+    def render_tbody
+      if @lines and @lines.size > 0
+        return Tools::html_safe(content_tag(:tbody, render_total_entries + Tools::html_safe(@lines.collect { |line| line.render_line }.join)))
+      end
+      ''
+    end
+    
+    def set_default_global_options
+      @@options[:sort] = true unless @@options.has_key? :sort
+    end
+    
+    def render_total_entries
+      if self.show_total_entries
+        total_entries = @collection.total_entries rescue @collection.size
+        return Tools::html_safe(content_tag(:tr, content_tag(:td, I18n.t(:total_entries, :scope => :sorting_table_for, :value => total_entries), {:colspan => @lines.first.total_cells}), { :class => 'total-entries' }))
+      end
+      ''
+    end
+    
+    def get_column_and_html_options(options)
+      return options, options.delete(:html) || {}
+    end
+    
+  end
+  
+  ##
+  ##  Format Lines
+  ##
+  ##
+  ##
+  
+  class FormatLine < TableBuilder
+    
+    def initialize(args, column_options = {}, html_options = {}, object = nil, type = nil)
+      @args, @column_options, @html_options, @object, @type = args, column_options, html_options, object, type
+      @cells = []
+      if object
+        @attributes = (args.empty?) ? (get_columns - TableBuilder.reserved_columns) : @args
+        create_cells
+      end
+    end
+    
+    def add_cell(object, args, type =nil, block = nil)
+      @cells << FormatCell.new(object, args, type, block)
+    end
+    
+    def render_line
+      if @type == :thead
+        header = content_tag(:tr, Tools::html_safe(@cells.collect { |cell| cell.render_cell_thead }.join), @html_options)
+      else
+        content_tag(:tr, Tools::html_safe(@cells.collect { |cell| cell.render_cell_tbody }.join), @html_options.merge(:class => "#{@html_options[:class]} #{@@template.cycle(:odd, :even)}".strip))
+      end
+    end
+    
+    def total_cells
+      @cells.size.to_s
+    end
+    
+    protected
+    
+    # This function is a copy from Formtastic: http://github.com/justinfrench/formtastic
+    def content_columns
+      model_name(@object).constantize.content_columns.collect { |c| c.name.to_sym }.compact rescue []
+    end
+    
+    def model_have_column?(column)
+      model_name(@object).constantize.content_columns.each do |model_column|
+        return true if model_column.name == column.to_s
+      end
+      false
+    end
+    
+    def can_sort_column?(column)
+      model_have_column?(column)
+    end
+    
+    private
+    
+    def create_cells
+      @attributes.each { |ask| add_cell(@object, ask) }
+      if @args.empty?
+        TableBuilder.default_actions.each { |action| add_cell(@object, action, :action) }
+      else
+        get_column_actions.each { |action| add_cell(@object, action, :action) }
+      end
+    end
+    
+    def get_column_actions
+      if @column_options.has_key? :actions
+        if @column_options[:actions].is_a?(Array)
+          return @column_options[:actions]
+        else
+          return [ @column_options[:actions] ]
+        end
+      end
+      []
+    end
+    
+    def get_columns
+      if @column_options.has_key? :only
+        return @column_options[:only] if @column_options[:only].is_a?(Array)
+        [ @column_options[:only] ]
+      elsif @column_options.has_key? :except
+        return content_columns - @column_options[:except] if @column_options[:except].is_a?(Array)
+        content_columns - [ @column_options[:except] ] 
+      else
+        content_columns
+      end
+    end
+
+  end
+
+  ##
+  ## Format Cells
+  ##
+  ##
+  ##
+
+  class FormatCell < FormatLine
+    
+    def initialize(object, args, type = nil, block = nil)
+      @object, @type, @block = object, type, block
+      if args.is_a? Array
+        @options, @html_options = get_cell_and_html_options( args.extract_options! )
+        @ask = args.first
+        if @ask.nil? and @options.has_key?(:action)
+          @type = :action 
+          @ask = @options[:action]
+        end
+      else
+        @ask = args
+      end
+      set_default_options
+      @can_sort = true if @options and @options[:sort] and can_sort_column?(@ask)
+    end
+    
+    def render_cell_tbody
+      if @type == :action
+        cell_value = action_link_to(@ask)
+      elsif @ask
+        cell_value = (@ask.is_a?(Symbol)) ? format_cell_value(@object[@ask], @ask) : format_cell_value(@ask)
+      else
+        cell_value = @block
+      end
+      cell_value = action_link_to(@options[:action], cell_value) if @type != :action and @options.has_key?(:action)
+      content_tag(:td, cell_value, @html_options)
+    end
+    
+    def render_cell_thead
+      if @ask
+        cell_value = (@ask.is_a?(Symbol)) ? I18n.t(@ask, {}, true) : @ask
+      else
+        cell_value = @block
+      end
+      if @can_sort and @options[:sort]
+        @html_options.merge!(:class => "#{@html_options[:class]} #{sorting_html_class}".strip)
+        content_tag(:th, sort_link_to(cell_value), @html_options)
+      else
+        content_tag(:th, cell_value, @html_options)
+      end
+    end
+    
+    private
+    
+    def get_cell_and_html_options(options)
+      return options, options.delete(:html) || {}
+    end
+    
+    def set_default_options
+      @html_options = {} unless defined? @html_options
+      @options = {} unless defined? @options
+      @options[:sort] = @@options[:sort] or true if !@options.has_key? :sort
+    end
+    
+    def action_link_to(action, block = nil)
+      object_or_array = @@object_or_array.clone
+      object_or_array.push @object
+      return case action.to_sym
+        when :delete
+          create_link_to(block || I18n.t(:delete), object_or_array, @@options[:link_remote], :delete, I18n.t(:confirm_delete))
+        when :show
+          create_link_to(block || I18n.t(:show), object_or_array, @@options[:link_remote])
+        else
+          object_or_array.insert(0, action)
+          create_link_to(block || I18n.t(@ask), object_or_array, @@options[:link_remote])
+      end
+    end
+    
+    def sort_link_to(name)
+      create_link_to(name, sort_url, @@options[:sort_remote])
+    end
+    
+    def create_link_to(block, url, remote, method = nil, confirm = nil)
+      if remote and Tools::rails3?
+        return @@template.link_to(block, url, :method => method, :confirm => confirm, :remote => true)
+      elsif remote
+        method = :get if method.nil?
+        return @@template.link_to_remote(block, { :url => url, :method => method, :confirm => confirm })
+      end
+      @@template.link_to(block, url, :method => method, :confirm => confirm)
+    end
+    
+    def sorting_html_class
+      return TableBuilder.html_sorting_class.first if current_sorting.nil?
+      return TableBuilder.html_sorting_class.second if current_sorting == :asc
+      TableBuilder.html_sorting_class.third
+    end
+    
+    def sort_url
+      url_params = @@params.clone
+      if url_params.has_key? TableBuilder.params_sort_table
+        if url_params[TableBuilder.params_sort_table].has_key? @ask
+          url_params[TableBuilder.params_sort_table][@ask] = inverse_sorting
+          return @@template.url_for(url_params)
+        end
+        url_params[TableBuilder.params_sort_table].delete @ask
+      end
+      url_params[TableBuilder.params_sort_table] = { @ask => :asc }
+      @@template.url_for(url_params)
+    end
+    
+    def current_sorting
+      if @@params.has_key? TableBuilder.params_sort_table and @@params[TableBuilder.params_sort_table].has_key? @ask
+        return @@params[TableBuilder.params_sort_table][@ask].to_sym
+      end
+      nil
+    end
+    
+    def inverse_sorting
+      return :asc if current_sorting.nil?
+      return :desc if current_sorting == :asc
+      :asc
+    end
+    
+    def format_cell_value(value, attribute = nil)
+      unless (ret_value = format_cell_value_as_ask(value)).nil?
+        return ret_value
+      end
+      format_cell_value_as_type(value, attribute)
+    end
+    
+    def format_cell_value_as_ask(value)
+      return nil if !@options or @options.empty? or !@options.has_key?(:as)
+      return case @options[:as]
+        when :date then ::I18n.l(value.to_date, :format => @options[:format] || TableBuilder.i18n_default_format_date)
+        when :time then ::I18n.l(value.to_datetime, :format => @options[:format] || TableBuilder.i18n_default_format_date)
+        when :currency then number_to_currency(value)
+        else nil
+      end
+    end
+    
+    def format_cell_value_as_type(value, attribute)
+      if value.is_a?(Time) or value.is_a?(Date)
+        return ::I18n.l(value, :format => @options[:format] || TableBuilder.i18n_default_format_date)
+      elsif TableBuilder.currency_columns.include?(attribute)
+        return number_to_currency(value)
+      elsif value.is_a?(TrueClass)
+        return TableBuilder.default_boolean.first
+      elsif value.is_a?(FalseClass)
+        return TableBuilder.default_boolean.second
+      end
+      value
+    end
+    
+  end
+end