tableficate 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*.swp

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in tablificate.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011 SEI Meetings & Incentives
+
+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.markdown

@@ -0,0 +1,120 @@
+# Tableficate
+A DSL for easy table creation with sorting and filtering. It tries to do to tables what simple_form and formtastic have done for forms. Below you'll find basic documentation with more compelete docs forthcoming.
+
+## Installation
+
+    $ gem install tableficate
+
+If you're using Bundler, add this to your Gemfile:
+
+    gem 'tableficate'
+
+## Support
+
+### Ruby
+1.9+
+
+### Rails
+3.1+
+
+### Templating
+Any templating engine can be used. The default theme uses ERB.
+
+### Database Framework
+ActiveRecord
+
+### Pagination
+Any pagination can be used. The default theme has built-in support for Kaminari and will_paginate.
+
+## Basic Usage
+Let's say that we want to create a table that lists active accounts in the system with their time of creation and the name on the account.
+
+Our controller:
+
+    @accounts = Accounts.active.tableficate(params[:accounts]).page(params.try(:[], :accounts_page) || 1)
+
+Here we're getting active accounts, calling tableficate and then paginating with Kaminari. Tableficate works on Arel objects and passes out an Arel so you can add things like pagination. We pass in the params for the table we'll create in the view. By default the params are stored under the primary table name of the query.
+
+Our View:
+
+    <%= table_for @accounts, show_sorts: true do |t|
+      t.column :id, header: 'Account Number'
+      t.column :created_at do |account|
+        account.created_at.strftime('%m/%d/%Y')
+      end
+      t.column :first_name
+      t.column :last_name
+      t.actions do |account|
+        link_to('View', account_path(account))
+      end
+
+      t.input_filter :first_name
+      t.input_filter :last_name
+    %>
+
+This creates a sortable table with two filters, 4 data columns and an action column. Column headers are automatically generated but can be overridden as seen on the "id" column. The column output can also be overridden by passing a block to the call. This setup provides easy table creation but only covers basic functionality. Some of the more advanced functionality requires you to wrap your scope in a special table model.
+
+Having created the basic table we now want to default the sorting to show newest accounts first and we want the first and last name to be merged into one name column. First we'll need to create a table model.
+
+In "app/tables/" we'll create a new table model. This can be done using a generator.
+
+    $ rails generate tableficate:table AccountReport
+
+Our table model:
+
+    class AccountReport < Tableficate::Base
+      scope do
+        Accounts.active
+      end
+
+      default_sort(:created_at, 'DESC')
+
+      column(:full_name, sort: 'first_name ASC, last_name ASC')
+
+      filter(:full_name) do |value, scope|
+        first_name, last_name = value.split(/\s+/)
+
+        if last_name.nil?
+          scope.where(['first_name LIKE ? OR last_name LIKE ?', first_name, first_name])
+        else
+          scope.where(['first_name LIKE ? AND last_name LIKE ?', first_name, last_name])
+        end 
+      end
+    end
+
+We've defined a scope that we're wrapping. Then we provide a default sorting and explain how to sort and filter a new column called ":full_name".
+
+Our new controller:
+
+    @accounts = AccountReport.tableficate(params[:accounts]).page(params.try(:[], :accounts_page) || 1)
+
+The only change here is that "Accounts.active" has changed to "AccountReport".
+
+Our new view:
+
+    <%= table_for @accounts, show_sorts: true do |t|
+      t.column :id, header: 'Account Number'
+      t.column :created_at do |account|
+        account.created_at.strftime('%m/%d/%Y')
+      end
+      t.column :full_name
+      t.actions do |account|
+        link_to('View', account_path(account))
+      end
+
+      t.input_filter :full_name
+    %>
+
+In the view we've merged the first and last name into a new full name column. Now we have default sorting, sortable columns and a full name filter.
+
+## Themes
+
+New themes can be created using the theme generator.
+
+    $ rails generate tableficate:theme NAME
+
+The theme can then be applied to a table by passing "theme: 'NAME'" to the "table_for" call.
+
+    <%= table_for @accounts, theme: 'foo' do |t|
+      ...
+    %>

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/app/views/tableficate/_column_header.html.erb

@@ -0,0 +1,8 @@
+<th>
+  <%= column.header %>
+  <% table_params = (params[column.table.as] || {}) %>
+  <% if column.show_sort? %>
+    <%= link_to 'A', url_for(params.merge(column.table.as => table_params.merge({sort: column.name.to_s, dir: 'asc'}))) %><% if column.is_sorted?('asc') %>*<% end %>
+    <%= link_to 'D', url_for(params.merge(column.table.as => table_params.merge({sort: column.name.to_s, dir: 'desc'}))) %><% if column.is_sorted?('desc') %>*<% end %>
+  <% end %>
+</th>

data/app/views/tableficate/_data.html.erb

@@ -0,0 +1 @@
+<td><%= column.value(row) %></td>

data/app/views/tableficate/_input_filter.html.erb

@@ -0,0 +1,4 @@
+<div>
+  <%= tableficate_label_tag(filter) %>
+  <%= tableficate_text_field_tag(filter) %>
+</div>

data/app/views/tableficate/_input_range_filter.html.erb

@@ -0,0 +1,6 @@
+<div>
+  <%= tableficate_label_tag(filter.start) %>
+  <%= tableficate_text_field_tag(filter.start) %>
+  <%= tableficate_label_tag(filter.stop) %>
+  <%= tableficate_text_field_tag(filter.stop) %>
+</div>

data/app/views/tableficate/_row.html.erb

@@ -0,0 +1,5 @@
+<tr>
+  <% columns.each do |column| %>
+    <%= tableficate_data_tag row, column %>
+  <% end %>
+</tr>

data/app/views/tableficate/_select_filter.html.erb

@@ -0,0 +1,4 @@
+<div>
+  <%= tableficate_label_tag(filter) %>
+  <%= tableficate_select_tag(filter) %>
+</div>

data/app/views/tableficate/_table.html.erb

@@ -0,0 +1,36 @@
+<% if table.filters.any? %>
+  <%= form_tag '', method: :get do %>
+    <% if params[table.as] and params[table.as][:sort] %>
+      <%= hidden_field_tag("#{table.as}[sort]", params[table.as][:sort]) %>
+    <% end %>
+    <% if params[table.as] and params[table.as][:dir] %>
+      <%= hidden_field_tag("#{table.as}[dir]", params[table.as][:dir]) %>
+    <% end %>
+    <% table.filters.each do |filter| %>
+      <%= tableficate_filter_tag filter %>
+    <% end %>
+
+    <%= submit_tag('Filter') %>
+  <% end %>
+<% end %>
+
+<% if defined? ::Kaminari %>
+  <%= paginate(table.rows, param_name: "#{table.as}_page") %>
+<% elsif defined? ::WillPaginate %>
+  <%= will_paginate(table.rows, param_name: "#{table.as}_page") %>
+<% end %>
+
+<%= content_tag(:table, table.options[:html]) do %>
+  <thead>
+    <tr>
+      <% table.columns.each do |column| %>
+        <%= tableficate_header_tag column %>
+      <% end %>
+    </tr>
+  </thead>
+  <tbody>
+    <% table.rows.each do |row| %>
+      <%= tableficate_row_tag row, table.columns %>
+    <% end %>
+  </tbody>
+<% end %>

data/changelog.markdown

@@ -0,0 +1,2 @@
+## 0.1.0
+ * initial release

data/lib/generators/tableficate/table/table_generator.rb

@@ -0,0 +1,17 @@
+module Tableficate
+  class TableGenerator < Rails::Generators::NamedBase
+    desc('Create a Tableficate table model.')
+
+    source_root File.expand_path('../templates', __FILE__)
+
+    TABLES_PATH = 'app/tables'
+
+    argument :scope, required: false
+
+    def create_table
+      empty_directory(TABLES_PATH)
+
+      template('table.rb', "#{TABLES_PATH}/#{file_name.underscore}.rb")
+    end
+  end
+end

data/lib/generators/tableficate/table/templates/table.rb

@@ -0,0 +1,5 @@
+class <%= class_name %> < Tableficate::Base
+<% if scope -%>
+  scope :<%= scope.tableize %>
+<% end -%>
+end

data/lib/generators/tableficate/theme/theme_generator.rb

@@ -0,0 +1,15 @@
+module Tableficate
+  class ThemeGenerator < Rails::Generators::NamedBase
+    desc('Create a Tableficate theme.')
+
+    VIEW_PATH = 'app/views/tableficate'
+
+    source_root File.expand_path("../../../../../#{VIEW_PATH}", __FILE__)
+
+    def create_theme
+      empty_directory(VIEW_PATH)
+
+      directory('', "#{VIEW_PATH}/#{file_name}")
+    end
+  end
+end

data/lib/tableficate/action_column.rb

@@ -0,0 +1,15 @@
+module Tableficate
+  class ActionColumn < Column
+    def initialize(table, options = {}, block)
+      super(table, '', options, &block)
+    end
+
+    def show_sort?
+      false
+    end
+
+    def is_sorted?(dir = nil)
+      false
+    end
+  end
+end

data/lib/tableficate/active_record_extension.rb

@@ -0,0 +1,20 @@
+module Tableficate
+  module ActiveRecordExtension
+    extend ActiveSupport::Concern
+
+    included do
+      extend Tableficate::Finder
+
+      self.scope :tableficate_ext, ->{} do
+        def tableficate_add_data(key, value)
+          @tableficate_data ||= {}
+          @tableficate_data[key] = value
+        end
+
+        def tableficate_get_data
+          @tableficate_data || {}
+        end
+      end
+    end
+  end
+end

data/lib/tableficate/base.rb

@@ -0,0 +1,37 @@
+module Tableficate
+  class Base
+    extend Tableficate::Finder
+
+    def self.scope(model = nil, &block)
+      if block_given?
+        @scope = block.call
+      else
+        @scope = model.to_s.camelize.constantize
+      end
+    end
+
+    def self.default_sort(name, dir = 'asc')
+      @default_sort = [name, dir]
+    end
+
+    def self.column(name, options = {})
+      @sort ||= {}
+
+      @sort[name] = options[:sort] if options[:sort].present?
+    end
+
+    def self.filter(name, options = {}, &block)
+      @filter ||= {}
+
+      if block_given?
+        @filter[name] = block
+      else
+        options.reverse_merge!(
+          field: name
+        )
+
+        @filter[name] = options
+      end
+    end
+  end
+end

data/lib/tableficate/column.rb

@@ -0,0 +1,33 @@
+module Tableficate
+  class Column
+    attr_reader :name, :header, :table
+
+    def initialize(table, name, options = {}, &block)
+      @table   = table
+      @name    = name
+      @options = options
+      @block   = block
+
+      @header = @options.delete(:header) || name.to_s.titleize
+    end
+
+    def value(row)
+      if @block
+        @block.call(row).html_safe
+      else
+        row.send(@name)
+      end
+    end
+
+    def show_sort?
+      !!@options[:show_sort]
+    end
+
+    def is_sorted?(dir = nil)
+      is_sorted = @table.current_sort[:column] == self.name
+      is_sorted = @table.current_sort[:dir] == dir if is_sorted and dir
+
+      is_sorted
+    end
+  end
+end

data/lib/tableficate/engine.rb

@@ -0,0 +1,4 @@
+module Tableficate
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/tableficate/exceptions.rb

@@ -0,0 +1,3 @@
+module Tableficate
+  class MissingScope < StandardError; end
+end

data/lib/tableficate/filters/filter.rb

@@ -0,0 +1,19 @@
+module Tableficate
+  class Filter
+    attr_reader :name, :label, :options, :template, :table, :field_name
+
+    def initialize(table, name, options = {})
+      @table   = table
+      @name    = name
+      @options = options
+
+      @template   = self.class.name.demodulize.underscore
+      @label      = @options[:label] || table.columns.detect{|column| column.name == @name}.try(:header) || name.to_s.titleize
+      @field_name = "#{table.as}[filter][#{@name}]"
+    end
+
+    def field_value(params)
+      params[:filter][@name] rescue ''
+    end
+  end
+end

data/lib/tableficate/filters/input_filters.rb

@@ -0,0 +1,64 @@
+module Tableficate
+  class InputFilter < Filter
+    def initialize(table, name, options = {})
+      super(table, name, options)
+
+      type = @options[:field_options][:type] rescue 'text'
+
+      if not Dir.glob('app/views/' + Tableficate::Utils::template_path("_#{type}_#{@template}.html.*", table.options[:theme])).empty?
+        @template = "#{type}_#{@template}"
+      end
+    end
+  end
+
+  class InputStartFilter < InputFilter
+    def initialize(table, name, options = {})
+      super(table, name, options)
+
+      @field_name += '[start]'
+    end
+
+    def name
+      "#{@name}_start".to_sym
+    end
+
+    def field_value(params)
+      params[:filter][@name][:start] rescue ''
+    end
+  end
+
+  class InputStopFilter < InputFilter
+    def initialize(table, name, options = {})
+      super(table, name, options)
+
+      @field_name += '[stop]'
+    end
+
+    def name
+      "#{@name}_stop".to_sym
+    end
+
+    def field_value(params)
+      params[:filter][@name][:stop] rescue ''
+    end
+  end
+
+  class InputRangeFilter < Filter
+    attr_reader :start, :stop
+
+    def initialize(table, name, options = {})
+      start_options = options.delete(:start) || {}
+      stop_options  = options.delete(:stop)  || {}
+
+      super(table, name, options)
+
+      start_options.reverse_merge!(@options)
+      start_options.reverse_merge!(label: self.label)
+      stop_options.reverse_merge!(@options)
+      stop_options.reverse_merge!(label: self.label)
+
+      @start = InputStartFilter.new(table, name, start_options)
+      @stop  = InputStopFilter.new(table, name, stop_options)
+    end
+  end
+end

data/lib/tableficate/filters/select_filter.rb

@@ -0,0 +1,11 @@
+module Tableficate
+  class SelectFilter < Filter
+    attr_reader :choices
+
+    def initialize(table, name, choices, options = {})
+      super(table, name, options)
+
+      @choices = choices
+    end
+  end
+end

data/lib/tableficate/finder.rb

@@ -0,0 +1,79 @@
+module Tableficate
+  module Finder
+    def tableficate(params)
+      scope = @scope || self
+      raise Tableficate::MissingScope unless scope.new.kind_of?(ActiveRecord::Base)
+
+      # filtering
+      if params
+        if params[:filter]
+          params[:filter].each do |name, value|
+            next if value.blank? or (value.is_a?(Hash) and value.all?{|key, value| value.blank?})
+
+            name = name.to_sym
+            value.strip! if value.is_a?(String)
+
+            if @filter and @filter[name]
+              if @filter[name].is_a?(Proc)
+                scope = @filter[name].call(value, scope)
+              elsif value.is_a?(String)
+                value = "%#{value}%" if @filter[name][:match] == 'contains'
+
+                scope = scope.where(["#{get_full_column_name(@filter[name][:field])} LIKE ?", value])
+              elsif value.is_a?(Array)
+                full_column_name = get_full_column_name(@filter[name][:field])
+
+                if @filter[name][:match] == 'contains'
+                  scope = scope.where([
+                    Array.new(value.size, "#{full_column_name} LIKE ?").join(' OR '),
+                    *value.map{|v| "%#{v}%"}
+                  ])
+                else
+                  scope = scope.where(["#{full_column_name} IN(?)", value])
+                end
+              elsif value.is_a?(Hash)
+                scope = scope.where(["#{get_full_column_name(@filter[name][:field])} BETWEEN :start AND :stop", value])
+              end
+            elsif value.is_a?(Array)
+              scope = scope.where(["#{get_full_column_name(name.to_s.gsub(/\W/, ''))} IN(?)", value])
+            elsif value.is_a?(Hash)
+              scope = scope.where(["#{get_full_column_name(name.to_s.gsub(/\W/, ''))} BETWEEN :start AND :stop", value])
+            else
+              scope = scope.where(["#{get_full_column_name(name.to_s.gsub(/\W/, ''))} LIKE ?", value])
+            end
+          end
+        end
+      end
+
+      # sorting
+      column = params.try(:[], :sort).try(:gsub, /\W/, '') || @default_sort.try(:[], 0)
+      dir = (params.try(:[], :dir) || @default_sort.try(:[], 1) || 'asc').downcase
+      if column.present?
+        scope = scope.order(@sort.try(:[], column.to_sym) || "#{get_full_column_name(column.to_s)} ASC")
+        scope = scope.reverse_order if dir == 'desc'
+      end
+
+      # return an arel object with our data attached
+      scope = scope.tableficate_ext
+      sorting = {column: nil, dir: nil}
+      if column.present?
+        sorting[:column] = column.to_sym
+        sorting[:dir]    = ['asc', 'desc'].include?(dir) ? dir : 'asc'
+      end
+      scope.tableficate_add_data(:current_sort, sorting)
+      scope
+    end
+
+    def get_full_column_name(name)
+      name = name.to_s
+      scope = @scope || self
+
+      if scope.column_names.include?(name)
+        "#{scope.table_name}.#{name}"
+      else
+        name
+      end
+    end
+    private :get_full_column_name
+  end
+end

data/lib/tableficate/helper.rb

@@ -0,0 +1,37 @@
+module Tableficate
+  module Helper
+    def table_for(rows, options = {})
+      t = Tableficate::Table.new(self, rows, options, rows.tableficate_get_data)
+      yield(t)
+      t.render
+    end
+
+    def tableficate_header_tag(column)
+      render partial: Tableficate::Utils::template_path('column_header', column.table.options[:theme]), locals: {column: column}
+    end
+
+    def tableficate_data_tag(row, column)
+      render partial: Tableficate::Utils::template_path('data', column.table.options[:theme]), locals: {row: row, column: column}
+    end
+
+    def tableficate_row_tag(row, columns)
+      render partial: Tableficate::Utils::template_path('row', columns.first.table.options[:theme]), locals: {row: row, columns: columns}
+    end
+
+    def tableficate_filter_tag(filter)
+      render partial: Tableficate::Utils::template_path(filter.template, filter.table.options[:theme]), locals: {filter: filter}
+    end
+
+    def tableficate_label_tag(filter)
+      label_tag(filter.field_name, filter.label, filter.options[:label_options] || {})
+    end
+
+    def tableficate_text_field_tag(filter)
+      text_field_tag(filter.field_name, filter.field_value(params[filter.table.as]), filter.options[:field_options] || {})
+    end
+
+    def tableficate_select_tag(filter)
+      select_tag(filter.field_name, filter.choices, filter.options)
+    end
+  end
+end

data/lib/tableficate/table.rb

@@ -0,0 +1,57 @@
+module Tableficate
+  class Table
+    attr_reader :columns, :rows, :current_sort, :filters, :options, :as
+
+    def initialize(template, rows, options, data)
+      @template = template
+      @rows     = rows
+      @columns  = []
+      @filters  = []
+      @as       = options[:as] || rows.table_name
+
+      @options = {
+        show_sorts: false,
+        theme:      ''
+      }.merge(options)
+
+      @current_sort = data[:current_sort]
+    end
+
+    def column(name, options = {}, &block)
+      options.reverse_merge!(
+        show_sort: @options[:show_sorts]
+      )
+
+      @columns.push(Column.new(self, name, options, &block))
+    end
+
+    def actions(options = {}, &block)
+      @columns.push(ActionColumn.new(self, options, block))
+    end
+
+    def show_sort?
+      self.columns.any?{|column| column.show_sort?}
+    end
+
+    def input_filter(name, options = {})
+      @filters.push(InputFilter.new(self, name, options))
+    end
+
+    def input_range_filter(name, options = {})
+      @filters.push(InputRangeFilter.new(self, name, options))
+    end
+
+    def select_filter(name, choices, options = {})
+      @filters.push(SelectFilter.new(self, name, choices, options))
+    end
+
+    def render(options = {})
+      options.reverse_merge!(
+        partial: Tableficate::Utils::template_path('table', @options[:theme]),
+        locals:  {table: self}
+      )
+
+      @template.render options
+    end
+  end
+end