handles_sortable_columns 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Alex Fortuna
+
+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,118 @@
+
+Sortable Table Columns
+======================
+
+
+Introduction
+------------
+
+A simple yet flexible Rails gem/plugin to quickly add sortable table columns to your controller and views.
+
+
+Setup
+-----
+
+    $ gem sources --add http://rubygems.org
+    $ gem install handles_sortable_columns
+
+In your app's `config/environment.rb` do a:
+
+    config.gem "handles_sortable_columns"
+
+
+Basic Usage
+-----------
+
+Activate the feature in your controller class:
+
+    class MyController < ApplicationController
+      handles_sortable_columns
+    ...
+
+In a view, mark up sortable columns by using the <tt>sortable_column</tt> helper:
+
+    <%= sortable_column "Product" %>
+    <%= sortable_column "Price" %>
+
+In controller action, fetch and use the order clause according to current state of sortable columns:
+
+    def index
+      order = sortable_column_order
+      @records = Article.all(:order => order)
+    end
+
+That's it for basic usage. Production usage may require passing additional parameters to listed methods.
+
+
+Production Usage
+----------------
+
+Please take time to read the gem's full [RDoc documentation](http://rdoc.info/projects/dadooda/handles_sortable_columns). This README has a limited coverage.
+
+
+### Configuration ###
+
+Change names of GET parameters used for sorting and pagination:
+
+    class MyController < ApplicationController
+      handles_sortable_columns do |conf|
+        conf.sort_param = "s"
+        conf.page_param = "p"
+      end
+    ...
+
+Change CSS class of all sortable column `<a>` tags:
+
+    handles_sortable_columns do |conf|
+      conf.class = "SortableLink"
+      conf.indicator_class = {:asc => "AscSortableLink", :desc => "DescSortableLink"}
+    end
+
+Change how text-based sort indicator looks like:
+
+    handles_sortable_columns do |conf|
+      conf.indicator_text = {:asc => "[asc]", :desc => "[desc]"}
+    end
+
+Disable text-based sort indicator completely:
+
+    handles_sortable_columns do |conf|
+      conf.indicator_text = {}
+    end
+
+
+### Helper Options ###
+
+Explicitly specify column name:
+
+    <%= sortable_column "Highest Price", :column => "max_price" %>
+
+Specify CSS class for this particular link:
+
+    <%= sortable_column "Name", :class => "SortableLink" %>
+
+Specify sort direction on first click:
+
+    <%= sortable_column "Created At", :direction => :asc %>
+
+
+### Fetching Sort Order ###
+
+To fetch sort order **securely**, with **column name validation**, **default values** and **multiple sort criteria**, use the block form of `sortable_column_order`:
+
+    order = sortable_column_order do |column, direction|
+      case column
+      when "name"
+        "#{column} #{direction}"
+      when "created_at", "updated_at"
+        "#{column} #{direction}, name ASC"
+      else
+        "name ASC"
+      end
+    end
+
+
+Feedback
+--------
+
+Send bug reports, suggestions and criticisms through [project's page on GitHub](http://github.com/dadooda/handles_sortable_columns).

data/Rakefile

@@ -0,0 +1,51 @@
+require "rake/rdoctask"
+
+GEM_NAME = "handles_sortable_columns"
+
+begin
+  require "jeweler"
+  Jeweler::Tasks.new do |gem|
+    gem.name = GEM_NAME
+    gem.summary = "Sortable Table Columns"
+    gem.description = gem.summary
+    gem.email = "alex.r@askit.org"
+    gem.homepage = "http://github.com/dadooda/handles_sortable_titles"
+    gem.authors = ["Alex Fortuna"]
+    gem.files = FileList[
+      "[A-Z]*",
+      "*.gemspec",
+      "lib/**/*.rb",
+      "init.rb",
+    ] - ["README.html"]
+    gem.extra_rdoc_files = ["README.md"]
+  end
+rescue LoadError
+  STDERR.puts "This gem requires Jeweler to be built"
+end
+
+desc "Rebuild gemspec and package"
+task :rebuild => [:gemspec, :build]
+
+desc "Push (publish) gem to RubyGems (aka Gemcutter)"
+task :push => :rebuild do
+  # Yet found no way to ask Jeweler forge a complete version string for us.
+  vh = YAML.load(File.read("VERSION.yml"))
+  version = [vh[:major], vh[:minor], vh[:patch]].join(".")
+  pkgfile = File.join("pkg", [GEM_NAME, "-", version, ".gem"].to_s)
+  system("gem", "push", pkgfile)
+end
+
+desc "Compile README preview"
+task :readme do
+  require "kramdown"
+
+  doc = Kramdown::Document.new(File.read "README.md")
+
+  fn = "README.html"
+  puts "Writing '#{fn}'..."
+  File.open(fn, "w") do |f|
+    f.write(File.read "dev/head.html")
+    f.write(doc.to_html)
+  end
+  puts ": ok"
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 0

data/handles_sortable_columns.gemspec

@@ -0,0 +1,47 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{handles_sortable_columns}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Alex Fortuna"]
+  s.date = %q{2010-08-26}
+  s.description = %q{Sortable Table Columns}
+  s.email = %q{alex.r@askit.org}
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.files = [
+    "MIT-LICENSE",
+     "README.md",
+     "Rakefile",
+     "VERSION.yml",
+     "handles_sortable_columns.gemspec",
+     "init.rb",
+     "lib/action_controller/base/handles_sortable_columns.rb",
+     "lib/handles/sortable_columns.rb",
+     "lib/handles_sortable_columns.rb"
+  ]
+  s.homepage = %q{http://github.com/dadooda/handles_sortable_titles}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Sortable Table Columns}
+  s.test_files = [
+    "spec/handles_sortable_columns_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
+    else
+    end
+  else
+  end
+end

data/init.rb

@@ -0,0 +1,2 @@
+# Rails plugin init.
+require File.join(File.dirname(__FILE__), "lib/handles_sortable_columns")

data/lib/action_controller/base/handles_sortable_columns.rb

@@ -0,0 +1,3 @@
+class ActionController::Base    #:nodoc:
+  include Handles::SortableColumns
+end

data/lib/handles/sortable_columns.rb

@@ -0,0 +1,261 @@
+module Handles  #:nodoc:
+  # == Overview
+  #
+  # A sortable columns feature for your controller and views.
+  #
+  # == Basic Usage
+  #
+  # Activate the feature in your controller class:
+  #
+  #   class MyController < ApplicationController
+  #     handles_sortable_columns
+  #   ...
+  # 
+  # In a view, mark up sortable columns by using the <tt>sortable_column</tt> helper:
+  #
+  #   <%= sortable_column "Product" %>
+  #   <%= sortable_column "Price" % >
+  #
+  # In controller action, fetch and use the order clause according to current state of sortable columns:
+  #
+  #   def index
+  #     order = sortable_column_order
+  #     @records = Article.all(:order => order)
+  #   end
+  #
+  # That's it for basic usage. Production usage may require passing additional parameters to listed methods.
+  #
+  # See also:
+  # * <tt>MetaClassMethods#handles_sortable_columns</tt>
+  # * <tt>HelperMethods#sortable_column</tt>
+  # * <tt>InstanceMethods#sortable_column_order</tt>
+  module SortableColumns
+    def self.included(owner)
+      owner.extend MetaClassMethods
+    end
+
+    # Sortable columns configuration object. Passed to block when you do a:
+    #
+    #   handles_sortable_column do |conf|
+    #     ...
+    #   end
+    class Config
+      # CSS class for link (regardless of sorted state). Default:
+      #
+      #   nil
+      attr_accessor :class
+
+      # GET parameter name for page number. Default:
+      #
+      #   page
+      attr_accessor :page_param
+
+      # GET parameter name for sort column and direction. Default:
+      #
+      #   sort
+      attr_accessor :sort_param
+
+      # Sort indicator text. If any of values are empty, indicator is not displayed. Default:
+      #
+      #  {:asc => "&nbsp;&darr;&nbsp;", :desc => "&nbsp;&uarr;&nbsp;"}
+      attr_accessor :indicator_text
+
+      # Sort indicator class. Default:
+      #
+      #  {:asc => "SortedAsc", :desc => "SortedDesc"}
+      attr_accessor :indicator_class
+
+      def initialize(attrs = {})
+        defaults = {
+          :page_param         => "page",
+          :sort_param         => "sort",
+          :indicator_text     => {:asc => "&nbsp;&darr;&nbsp;", :desc => "&nbsp;&uarr;&nbsp;"},
+          :indicator_class    => {:asc => "SortedAsc", :desc => "SortedDesc"},
+        }
+
+        defaults.merge(attrs).each {|k, v| send("#{k}=", v)}
+      end
+
+      def [](key)
+        send(key)
+      end
+
+      def []=(key, value)
+        send("#{key}=", value)
+      end
+    end # Config
+
+    module MetaClassMethods
+      # Activate and optionally configure the sortable columns.
+      #
+      #   class MyController < ApplicationController
+      #     handles_sortable_columns
+      #   end
+      #
+      # With configuration:
+      #
+      #   class MyController < ApplicationController
+      #     handles_sortable_columns do |conf|
+      #       conf.sort_param = "s"
+      #       conf.page_param = "p"
+      #       conf.indicator_text = {}
+      #       ...
+      #     end
+      #   end
+      #
+      # <tt>conf</tt> is a <tt>Config</tt> object.
+      def handles_sortable_columns(&block)
+        # Multiple activation protection.
+        if not self < InstanceMethods
+          extend ClassMethods
+          include InstanceMethods
+          helper HelperMethods
+        end
+
+        # Configuration is processed at every activation.
+        yield(sortable_columns_config) if block
+      end
+    end # MetaClassMethods
+
+    module ClassMethods
+      # Internal/advanced use only. Access/initialize the sortable columns config.
+      def sortable_columns_config
+        # NOTE: This is controller's class instance variable.
+        @sortable_columns_config ||= ::Handles::SortableColumns::Config.new
+      end
+
+      # Internal/advanced use only. Convert title to sortable column name.
+      #
+      #   sortable_column_name_from_title("ProductName")  # => "product_name"
+      def sortable_column_name_from_title(title)
+        title.gsub(/(\s)(\S)/) {$2.upcase}.underscore
+      end
+
+      # Internal/advanced use only. Parse sortable column sort param into a Hash with predefined keys.
+      #
+      #   parse_sortable_column_sort_param("name")    # => {:column => "name", :direction => :asc}
+      #   parse_sortable_column_sort_param("-name")   # => {:column => "name", :direction => :desc}
+      #   parse_sortable_column_sort_param("")        # => {:column => nil, :direction => nil}
+      def parse_sortable_column_sort_param(sort)
+        out = {:column => nil, :direction => nil}
+        if sort.to_s.strip.match /\A((?:-|))([^-]+)\z/
+          out[:direction] = $1.empty?? :asc : :desc
+          out[:column] = $2.strip
+        end
+        out
+      end
+    end # ClassMethods
+
+    module InstanceMethods
+      protected
+
+      # Compile SQL order clause according to current state of sortable columns.
+      #
+      # Basic (kickstart) usage:
+      #
+      #   order = sortable_column_order
+      #
+      # <b>WARNING!</b> Basic usage is <b>not recommended</b> for production since it is potentially
+      # vulnerable to SQL injection!
+      #
+      # Production usage with multiple sort criteria, column name validation and defaults:
+      #
+      #   order = sortable_column_order do |column, direction|
+      #     case column
+      #     when "name"
+      #       "#{column} #{direction}"
+      #     when "created_at", "updated_at"
+      #       "#{column} #{direction}, name ASC"
+      #     else
+      #       "name ASC"
+      #     end
+      #   end
+      #
+      # Apply order:
+      #
+      #   @records = Article.all(:order => order)   # Rails 2.x.
+      #   @records = Article.order(order)           # Rails 3.
+      def sortable_column_order(&block)
+        conf = {}
+        conf[k = :sort_param] = self.class.sortable_columns_config[k]
+
+        # Parse sort param.
+        pp = self.class.parse_sortable_column_sort_param(params[conf[:sort_param]])
+
+        order = if block
+          yield(pp[:column], pp[:direction])
+        else
+          # No block -- do a straight mapping.
+          if pp[:column]
+            [pp[:column], pp[:direction]].join(" ")
+          end
+        end
+
+        # Can be nil.
+        order
+      end
+    end # InstanceMethods
+
+    module HelperMethods
+      # Render a sortable column link.
+      #
+      # Options:
+      # * <tt>:column</tt> -- Column name. E.g. <tt>"created_at"</tt>.
+      # * <tt>:direction</tt> -- Sort direction on first click. <tt>:asc</tt> or <tt>:desc</tt>. Default is <tt>:asc</tt>.
+      # * <tt>:class</tt> -- CSS class for link (regardless of sorted state).
+      #
+      # Examples:
+      #
+      #   <%= sortable_column "Product" %>
+      #   <%= sortable_column "Highest Price", :column_name => "max_price" %>
+      #   <%= sortable_column "Name", :class => "SortableLink" %>
+      #   <%= sortable_column "Created At", :direction => :asc %>
+      def sortable_column(title, options = {})
+        options = options.dup
+        o = {}
+        conf = {}
+        conf[k = :sort_param] = controller.class.sortable_columns_config[k]
+        conf[k = :page_param] = controller.class.sortable_columns_config[k]
+        conf[k = :indicator_text] = controller.class.sortable_columns_config[k]
+        conf[k = :indicator_class] = controller.class.sortable_columns_config[k]
+
+        #HELP sortable_column
+        o[k = :column] = options.delete(k) || controller.class.sortable_column_name_from_title(title)
+        o[k = :direction] = options.delete(k).to_s.downcase =~ /\Adesc\z/ ? :desc : :asc
+        o[k = :class] = options.delete(k) || controller.class.sortable_columns_config[k]
+        #HELP /sortable_column
+
+        raise "Unknown option(s): #{options.inspect}" if not options.empty?
+
+        # Parse sort param.
+        pp = controller.class.parse_sortable_column_sort_param(params[conf[:sort_param]])
+
+        css_class = []
+        if (s = o[:class]).present?
+          css_class << s
+        end
+
+        # Build link itself.
+        pcs = []
+
+        # Already sorted?
+        if pp[:column] == o[:column].to_s
+          if (s = conf[:indicator_class][pp[:direction]]).present?
+            css_class << s
+          end
+
+          pcs << link_to(title, params.merge({conf[:sort_param] => [("-" if pp[:direction] == :asc), o[:column]].join, conf[:page_param] => 1}), {:class => css_class.present?? css_class.join(" ") : nil})       # Opposite sort order when clicked.
+
+          if (s = conf[:indicator_text][pp[:direction]]).present?
+            pcs << s
+          end
+        else
+          # Not sorted.
+          pcs << link_to(title, params.merge({conf[:sort_param] => [("-" if o[:direction] != :asc), o[:column]].join, conf[:page_param] => 1}), {:class => css_class.present?? css_class.join(" ") : nil})
+        end
+
+        pcs.join
+      end
+    end # HelperMethods
+  end # SortableColumns
+end # Handles

data/lib/handles_sortable_columns.rb

@@ -0,0 +1,4 @@
+# Rails gem init.
+Dir[File.join(File.dirname(__FILE__), "**/*.rb")].each do |fn|
+  require fn
+end

data/spec/handles_sortable_columns_spec.rb

@@ -0,0 +1,42 @@
+describe "ClassMethods" do
+  module WrapSortableColumnsClassMethods
+    class MyController < ActionController::Base
+      handles_sortable_columns
+    end
+  end
+
+  describe "#sortable_column_name_from_title" do
+    it "generally works" do
+      tests = [
+        ["Product", "product"],
+        ["product", "product"],
+        ["created_at", "created_at"],
+        ["created at", "created_at"],
+        ["CreatedAt", "created_at"],
+        ["Created At", "created_at"],
+      ]
+
+      tests.each do |input, expected|
+        WrapSortableColumnsClassMethods::MyController.sortable_column_name_from_title(input).should == expected
+      end
+    end
+  end # #sortable_column_name_from_title
+
+  describe "#parse_sortable_column_sort_param" do
+    it "generally works" do
+      tests = [
+        ["name", {:column => "name", :direction => :asc}],
+        ["-name", {:column => "name", :direction => :desc}],
+        [" -name ", {:column => "name", :direction => :desc}],
+        ["", {:column => nil, :direction => nil}],
+        ["-", {:column => nil, :direction => nil}],
+        ["- name", {:column => "name", :direction => :desc}],
+        ["--kaka", {:column => nil, :direction => nil}],
+      ]
+
+      tests.each do |input, expected|
+        WrapSortableColumnsClassMethods::MyController.parse_sortable_column_sort_param(input).should == expected
+      end
+    end
+  end # #parse_sortable_column_sort_param
+end # ClassMethods

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: handles_sortable_columns
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Alex Fortuna
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-26 00:00:00 +04:00
+default_executable: 
+dependencies: []
+
+description: Sortable Table Columns
+email: alex.r@askit.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- MIT-LICENSE
+- README.md
+- Rakefile
+- VERSION.yml
+- handles_sortable_columns.gemspec
+- init.rb
+- lib/action_controller/base/handles_sortable_columns.rb
+- lib/handles/sortable_columns.rb
+- lib/handles_sortable_columns.rb
+has_rdoc: true
+homepage: http://github.com/dadooda/handles_sortable_titles
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Sortable Table Columns
+test_files: 
+- spec/handles_sortable_columns_spec.rb