paginated_table 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+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.md

@@ -0,0 +1,132 @@
+# PaginatedTable
+
+[![Build Status](https://secure.travis-ci.org/dball/paginated_table.png)](http://travis-ci.org/dball/paginated\_table)
+
+PaginatedTable is a Rails plugin that makes rendering paginated, sorted
+HTML tables dead simple.
+
+## Requirements
+
+* rails 3.2 (3.1 may work)
+* will_paginate 3.0
+* jquery-rails
+
+## Installation
+
+Add `paginated\_table` to your `Gemfile` and `bundle install`.
+
+Add the `paginated\_table` javascript to your application's javascript
+requires after `jquery` and `jquery\_ujs`:
+
+    //= require jquery
+    //= require jquery_ujs
+    //= require paginated_table
+
+## Usage
+
+PaginatedTable mixes helper methods into ActionController::Base and
+ActionView::Base, conveniently named `paginated_table`.
+
+### Controller
+
+The `paginated_table` helper is an instance method you can call in an
+action that paginates a table:
+
+    class ProductsController < ApplicationController
+      def index
+        paginated_table :products => Product.all
+      end
+    end
+
+This will sort the collection using Arel's order method, paginate
+the given collection using will_paginate, store the
+page in an instance variable with the name of the hash key, e.g.
+`@products`, and if the request is AJAX, renders a partial response.
+
+### View
+
+The `paginated_table` helper is an instance method you can call in a
+view that renders a paginated table. To work with the AJAX pagination,
+the call must appear in a partial with the same name as the table's
+instance variable, e.g. `products.html.erb`. Thus, we might have:
+
+In `index.html.erb`:
+
+    <h1>Products</h1>
+
+    <%= render :partial => 'products' %>
+
+and in `products.html.erb`:
+
+    <%= paginated_table(@products) do |table|
+          table.column :name, :sortable => false
+          table.column :price do |price|
+            format_currency(price)
+          end
+          table.column :qty, :title => 'Quantity'
+        end %>
+
+The `div.paginated_table` element on the page will be updated for successful
+AJAX responses.
+
+The table DSL provides a column method by which you describe the table.
+The column calls correspond to columns in the rendered table. Columns
+with no block send their name to the records to get their cell values, while
+columns with blocks yield to them the records to get their cell values.
+Columns are sortable by default, but may be rendered unsortable with the
+:sortable option set to false.
+
+The table gets a header row with titleized column names, and a
+wrapping header and footer with pagination info and links. The
+pagination links are decorated to be AJAX requests by jquery-rails, the
+results of which overwrite the paginated_table div. The column names
+corresponding to sortable columns are linked to sort the table
+ascending, then descending, restarting at the first page of the
+collection.
+
+### Output
+
+    <div class="paginated_table">
+      <div class="header">
+        <div class="info">
+          ... will_paginate info ...
+        </div>
+        <div class="links">
+          <div class="pagination">
+            ... will_paginate links ...
+          </div>
+        </div>
+      </div>
+      <table class="paginated">
+        <thead>
+          <tr>
+            <th class="sortable sorted_asc">...</th>
+            <th class="sortable">...</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td>...</td>
+            <td>...</td>
+          </tr>
+        </tbody>
+      </table>
+      <div class="footer">
+        <div class="info">
+          ... will_paginate info ...
+        </div>
+        <div class="links">
+          <div class="pagination">
+            ... will_paginate links ...
+          </div>
+        </div>
+      </div>
+    </div>
+
+## TODO
+
+* AJAX links should be optional
+
+* AJAX busy indicator
+
+* AJAX error indicator

data/Rakefile

@@ -0,0 +1,38 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'PaginatedTable'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/lib/paginated_table.rb

@@ -0,0 +1,7 @@
+module PaginatedTable
+end
+
+require 'will_paginate/railtie'
+require 'paginated_table/railtie'
+require 'paginated_table/engine'
+require 'paginated_table/page'

data/lib/paginated_table/controller_helpers.rb

@@ -0,0 +1,14 @@
+module PaginatedTable
+  module ControllerHelpers
+    def paginated_table(tables)
+      raise ArgumentError if tables.length > 1
+      name, collection = tables.first
+      page = PageParams.create_page_from_params(params)
+      data_page = DataPage.new(collection, page)
+      instance_variable_set(:"@#{name}", data_page)
+      render :partial => name.to_s, :layout => false if request.xhr?
+    end
+  end
+end
+
+ActionController::Base.send :include, PaginatedTable::ControllerHelpers

data/lib/paginated_table/engine.rb

@@ -0,0 +1,7 @@
+module PaginatedTable
+  class Engine < ::Rails::Engine
+    initializer 'static_assets.load_static_assets' do |app|
+      app.middleware.use ::ActionDispatch::Static, "#{root}/vendor"
+    end
+  end
+end

data/lib/paginated_table/page.rb

@@ -0,0 +1,87 @@
+module PaginatedTable
+  class Page
+
+    SORT_DIRECTIONS = %w(asc desc)
+    DEFAULT_PER_PAGE = 10
+
+    attr_reader :number, :rows, :sort_column, :sort_direction
+
+    def self.opposite_sort_direction(sort_direction)
+      index = SORT_DIRECTIONS.index(sort_direction)
+      SORT_DIRECTIONS[index - 1]
+    end
+
+    def initialize(attributes)
+      @number = Integer(attributes[:number] || 1)
+      raise ArgumentError unless @number > 0
+      @rows = Integer(attributes[:rows] || DEFAULT_PER_PAGE)
+      raise ArgumentError unless @rows > 0
+      @sort_column = attributes[:sort_column] || 'id'
+      @sort_direction = attributes[:sort_direction] || 'asc'
+      raise ArgumentError unless SORT_DIRECTIONS.include?(@sort_direction)
+    end
+
+    def page_for_number(number)
+      Page.new(
+        :number => number,
+        :rows => rows,
+        :sort_column => sort_column,
+        :sort_direction => sort_direction
+      )
+    end
+
+    def page_for_sort_column(new_sort_column)
+      if sort_column == new_sort_column
+        new_sort_direction = self.class.opposite_sort_direction(sort_direction)
+      else
+        new_sort_direction = nil
+      end
+      Page.new(
+        :number => 1,
+        :rows => rows,
+        :sort_column => new_sort_column,
+        :sort_direction => new_sort_direction
+      )
+    end
+
+  end
+
+  class PageParams
+    def self.create_page_from_params(params)
+      Page.new(
+        :number => params[:page],
+        :rows => params[:per_page],
+        :sort_column => params[:sort_column],
+        :sort_direction => params[:sort_direction]
+      )
+    end
+
+    def self.to_params(page)
+      {
+        :page => page.number.to_s,
+        :per_page => page.rows.to_s,
+        :sort_column => page.sort_column,
+        :sort_direction => page.sort_direction
+      }
+    end
+  end
+
+  class DataPage
+    attr_reader :page, :data
+
+    def initialize(collection, page)
+      @page = page
+      @data = collection.order(order_clause).paginate(pagination_params)
+    end
+
+    private
+
+    def order_clause
+      "#{@page.sort_column} #{@page.sort_direction}"
+    end
+
+    def pagination_params
+      { :page => @page.number, :per_page => @page.rows }
+    end
+  end
+end

data/lib/paginated_table/railtie.rb

@@ -0,0 +1,12 @@
+module PaginatedTable
+  class Railtie < Rails::Railtie
+    initializer "paginated_table" do |app|
+      ActiveSupport.on_load(:action_view) do
+        require 'paginated_table/view_helpers'
+      end
+      ActiveSupport.on_load :action_controller do
+        require 'paginated_table/controller_helpers'
+      end
+    end
+  end
+end

data/lib/paginated_table/version.rb

@@ -0,0 +1,3 @@
+module PaginatedTable
+  VERSION = "0.0.1"
+end

data/lib/paginated_table/view_helpers.rb

@@ -0,0 +1,168 @@
+module PaginatedTable
+  module ViewHelpers
+    def paginated_table(data_page, &block)
+      table_description = TableDescription.new(block)
+      page = PageParams.create_page_from_params(params)
+      link_renderer = LinkRenderer.new(page)
+      table_renderer = RendersTable.new(self, table_description, data_page, link_renderer)
+      table_renderer.render
+    end
+  end
+
+  class TableDescription
+    attr_reader :columns
+
+    def initialize(description_proc = nil)
+      @columns = []
+      description_proc.call(self) if description_proc
+    end
+
+    def column(*args, &block)
+      @columns << Column.new(*args, &block)
+    end
+
+    class Column
+      attr_reader :name
+
+      def initialize(name, options = {}, &block)
+        @name = name
+        @block = block
+        @options = options
+      end
+
+      def render_header
+        @options.fetch(:title, @name.to_s.titleize)
+      end
+
+      def render_cell(datum)
+        if @block
+          @block.call(datum)
+        else
+          datum.send(@name)
+        end
+      end
+
+      def sortable?
+        @options.fetch(:sortable, true)
+      end
+    end
+  end
+
+  class RendersTable
+    def initialize(view, description, data_page, link_renderer)
+      @view = view
+      @description = description
+      @data_page = data_page
+      @link_renderer = link_renderer
+    end
+
+    def render
+      pagination_area = render_pagination_area
+      content = pagination_area + render_table + pagination_area
+      @view.content_tag('div', content, :class => 'paginated_table')
+    end
+
+    def render_pagination_area
+      content = render_pagination_info + render_pagination_links
+      @view.content_tag('div', content, :class => 'header')
+    end
+
+    def render_pagination_info
+      content = @view.page_entries_info(@data_page.data)
+      @view.content_tag('div', content, :class => 'info')
+    end
+
+    def render_pagination_links
+      content = @view.will_paginate(@data_page.data, :renderer => @link_renderer)
+      @view.content_tag('div', content, :class => 'links')
+    end
+
+    def render_table
+      content = render_table_header + render_table_body
+      @view.content_tag('table', content, :class => 'paginated')
+    end
+
+    def render_table_header
+      @view.content_tag('thead', render_table_header_row)
+    end
+
+    def render_table_header_row
+      content = @description.columns.map { |column|
+        render_table_header_column(column)
+      }.reduce(&:+)
+      @view.content_tag('tr', content)
+    end
+
+    def render_table_header_column(column)
+      css = []
+      if column.sortable?
+        css << 'sortable'
+      end
+      if @data_page.page.sort_column == column.name.to_s
+        css << "sorted_#{@data_page.page.sort_direction}"
+      end
+      attributes = {}
+      attributes[:class] = css.join(' ') unless css.empty?
+      @view.content_tag('th', render_table_header_column_content(column), attributes)
+    end
+
+    def render_table_header_column_content(column)
+      text = column.render_header
+      if column.sortable?
+        @link_renderer.sort_link(text, column.name.to_s)
+      else
+        text
+      end
+    end
+
+    def render_table_body
+      content = @data_page.data.map { |datum|
+        render_table_body_row(datum)
+      }.reduce(&:+)
+      @view.content_tag('tbody', content)
+    end
+
+    def render_table_body_row(datum)
+      content = @description.columns.map { |column|
+        render_table_body_cell(datum, column)
+      }.reduce(&:+)
+      @view.content_tag('tr', content)
+    end
+
+    def render_table_body_cell(datum, column)
+      @view.content_tag('td', column.render_cell(datum))
+    end
+  end
+
+  class LinkRenderer < WillPaginate::ActionView::LinkRenderer
+    def initialize(page)
+      super()
+      @paginated_table_page = page
+    end
+
+    def sort_link(text, sort_on)
+      @template.link_to(text, sort_url(sort_on), :remote => true)
+    end
+
+    def tag(name, value, attributes = {})
+      if name == :a
+        @template.link_to(value, attributes.delete(:href), attributes.merge(:remote => true))
+      else
+        super
+      end
+    end
+
+    private
+
+    def sort_url(sort_on)
+      new_page = @paginated_table_page.page_for_sort_column(sort_on)
+      @template.url_for(PageParams.to_params(new_page))
+    end
+
+    def default_url_params
+      PageParams.to_params(@paginated_table_page)
+    end
+  end
+end
+
+ActionView::Base.send :include, PaginatedTable::ViewHelpers