ar_orderable 0.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+Gemfile.lock
+.bundle
+pkg

data/.rvmrc

@@ -0,0 +1 @@
+rvm 1.8.7@ar_orderable

data/Gemfile

@@ -0,0 +1,15 @@
+source "http://rubygems.org"
+
+gem "activerecord", "2.3.5"
+gem "jeweler"
+gem "gemcutter"
+
+group :test do
+  gem "activesupport", "2.3.5"
+  gem "factory_girl"
+  gem "rspec", "~> 1.3.0"
+  gem "rspec-rails", "~> 1.3.0"
+  gem "sqlite3-ruby"
+  gem "pg"
+  gem "mysql"
+end

data/README.textile

@@ -0,0 +1,57 @@
+h2. Introduction
+
+ar_orderable is a small ActiveRecord addition that makes ordering of results easier and cleaner.
+
+Supported features are:
+
+* Ordering by an attribute in associated model (@belongs_to@ or @has_one@)
+* Ordering by multiple attributes
+* Defaults to case-insensitive ordering (@a < B@), optionally case-sensitive
+* Direction can be specified, defaults to ascending
+* Protects from SQL injection by checking the attribute to order by is in a predefined set of orderable attributes
+
+Tested with ActiveRecord 2.3.5. Should work without hassle using any 2.3.x version of ActiveRecord. Support for ActiveRecord 3.0.x is upcoming.
+
+Supported & tested database adapters include PostgreSQL, MySQL and SQLite3. Might work with others.
+
+h2. Installation
+
+Using Bundler with Rails 2.3.x add this to your Gemfile:<pre><code>
+  gem "ar_orderable", :require => "orderable"
+</code></pre>
+
+As plugin:<pre><code>
+  ./script/plugin install git://github.com/mnylen/ar_orderable.git
+</code></pre>
+
+h2. Usage
+
+In model:<pre><code>
+class Game < ActiveRecord::Base
+  belongs_to :developer
+  orderable :by => [:name, :"developer.name"], :default => :name
+end
+</code></pre>
+
+In controller:<pre><code>
+Game.order(:name) # or Game.order("name")  
+</code></pre>
+
+To order by association's attribute:<pre><code>
+Game.order(:"developer.name") # or Game.order("developer.name")
+</code></pre>
+
+To order in descending order:<pre><code>
+Game.order(:"name!desc") # or Game.order("name!desc")
+</code></pre>
+
+To order in case-sensitive manner:<pre><code>
+Game.order(:name, :case_sensitive => true)
+</code></pre>
+
+To order by multiple attributes:<pre><code>
+Game.order([:"developer.name", :name]) # orders results first by developer name, then by game name
+</code></pre>
+
+If trying to order by an attribute that is not orderable by, it will order by the default attribute:<pre><code>
+Game.order(:updated_at) # will order by name

data/Rakefile

@@ -0,0 +1,17 @@
+begin
+  require 'jeweler'
+  
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "ar_orderable"
+    gemspec.summary = "A small ActiveRecord addition that makes ordering of results easier and cleaner"
+    gemspec.description = "ar_orderable adds a consistent way to order results at database level using ActiveRecord. Supports ordering by multiple attributes and by associated model's attributes."
+    gemspec.email = "mikko.nylen@gmail.com"
+    gemspec.homepage = "http://github.com/mnylen/ar_orderable"
+    gemspec.authors = ["Mikko Nylén"]
+    gemspec.add_dependency("activerecord", "~> 2.3.5")
+  end
+  
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/ar_orderable.gemspec

@@ -0,0 +1,73 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{ar_orderable}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Mikko Nyl\303\251n"]
+  s.date = %q{2010-09-19}
+  s.description = %q{ar_orderable adds a consistent way to order results at database level using ActiveRecord. Supports ordering by multiple attributes and by associated model's attributes.}
+  s.email = %q{mikko.nylen@gmail.com}
+  s.extra_rdoc_files = [
+    "README.textile"
+  ]
+  s.files = [
+    ".gitignore",
+     ".rvmrc",
+     "Gemfile",
+     "README.textile",
+     "Rakefile",
+     "VERSION",
+     "ar_orderable.gemspec",
+     "init.rb",
+     "lib/orderable.rb",
+     "spec/order_belongs_to_association_spec.rb",
+     "spec/order_case_sensitivity_spec.rb",
+     "spec/order_multiple_attributes_spec.rb",
+     "spec/order_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/support/database.yml",
+     "spec/support/factories.rb",
+     "spec/support/lib/activerecord_test_connector.rb",
+     "spec/support/matchers/be_in_order.rb",
+     "spec/support/models/developer.rb",
+     "spec/support/models/game.rb",
+     "spec/support/schema.rb"
+  ]
+  s.homepage = %q{http://github.com/mnylen/ar_orderable}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{A small ActiveRecord addition that makes ordering of results easier and cleaner}
+  s.test_files = [
+    "spec/order_belongs_to_association_spec.rb",
+     "spec/order_case_sensitivity_spec.rb",
+     "spec/order_multiple_attributes_spec.rb",
+     "spec/order_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/support/factories.rb",
+     "spec/support/lib/activerecord_test_connector.rb",
+     "spec/support/matchers/be_in_order.rb",
+     "spec/support/models/developer.rb",
+     "spec/support/models/game.rb",
+     "spec/support/schema.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activerecord>, ["~> 2.3.5"])
+    else
+      s.add_dependency(%q<activerecord>, ["~> 2.3.5"])
+    end
+  else
+    s.add_dependency(%q<activerecord>, ["~> 2.3.5"])
+  end
+end
+

data/init.rb

@@ -0,0 +1 @@
+require 'orderable'

data/lib/orderable.rb

@@ -0,0 +1,101 @@
+module Orderable
+  def self.included(base)
+    base.extend ActiveRecordAdditions
+  end
+  
+  module ActiveRecordAdditions
+    def orderable(options = {})
+      allowed_attrs = options[:by] || {}
+      default_attr  = options[:default] || allowed_attrs.first
+      
+      named_scope :order, lambda {
+        |*attrs| do_order_by(attrs.shift, attrs.shift || {}, allowed_attrs, default_attr)
+      }
+    end
+    
+    
+    private
+    
+      def do_order_by(attr_names, options, allowed_attrs, default_attr)
+        attr_names = [attr_names] unless attr_names.kind_of?(Array)
+        find_options = {}
+                
+        attr_names.each do |attr_name|
+          attr_name, direction = attr_name.to_s.split('!')
+          direction ||= "asc"
+          
+          unless allowed_attrs.include?(attr_name.to_sym)
+            attr_name = default_attr.to_s
+          end
+          
+          find_options = merge_find_options(find_options, order_by_single_attribute(attr_name, direction, options))
+        end
+        
+        find_options
+      end
+      
+      
+      def merge_find_options(old_find_options, other_find_options)
+        joins = old_find_options[:joins].to_s + " " + other_find_options[:joins].to_s
+        order = unless old_find_options[:order]
+          other_find_options[:order]
+        else
+          old_find_options[:order] + ", " + other_find_options[:order]
+        end
+        
+        {:order => order, :joins => joins}
+      end
+      
+      
+      def order_by_single_attribute(attr_name, direction, options)
+        attr_name, association_name = attr_name.split('.').reverse
+        unless association_name.nil?
+          association_order(association_name, attr_name, direction, options)
+        else
+          {:order => sql_order_attribute(nil, nil, attr_name, direction, options)}
+        end
+      end
+      
+      
+      def association_order(association_name, attr_name, direction, options)
+        reflection = self.reflect_on_association(association_name.to_sym)
+        join_table = reflection.quoted_table_name
+        join_alias = reflection.table_name + "_join_for_order_by"
+
+        if reflection.macro == :has_one
+          fk_column = join_alias + "." + self.name.foreign_key
+          pk_column = self.quoted_table_name + "." + get_primary_key(self.name)
+        elsif reflection.macro == :belongs_to
+          fk_column = self.quoted_table_name + "." + reflection.association_foreign_key
+          pk_column = join_alias + "." + get_primary_key(reflection.klass.name)
+        end
+        
+        joins = "LEFT JOIN #{join_table} #{join_alias} ON #{fk_column} = #{pk_column}"
+        order = sql_order_attribute(join_alias, reflection, attr_name, direction, options)
+        
+        {:joins => joins, :order => order}
+      end
+      
+      
+      def sql_order_attribute(join_alias, reflection, attr_name, direction, options)
+        order_attribute = join_alias ? "#{join_alias}.#{attr_name}" : "#{self.quoted_table_name}.#{attr_name}"
+        
+        unless options[:case_sensitive]
+          # Certain database adapters fail if we try to use LOWER() on non-string values
+          cols_hash = reflection ? reflection.klass.columns_hash : self.columns_hash
+          if cols_hash[attr_name].type == :string
+            order_attribute = "LOWER(#{order_attribute})"
+          end
+        else
+          if self.connection.adapter_name == "MySQL"
+            order_attribute = "BINARY #{order_attribute}"
+          end
+        end
+        
+        order_attribute += " #{direction}"
+        order_attribute
+      end
+  end
+end
+
+ActiveRecord::Base.send(:include, Orderable)

data/spec/order_belongs_to_association_spec.rb

@@ -0,0 +1,26 @@
+require "spec_helper"
+
+describe "order by attribute in belongs_to association" do
+  before(:each) do
+    @ea_redwood_shores = Factory.create(:developer, :name => "EA Redwood Shores")
+    @dead_space = Factory.create(:game, :name => "Dead Space", :developer => @ea_redwood_shores, :created_at => 10.minutes.ago)
+    
+    @rocksteady_studios = Factory.create(:developer, :name => "Rocksteady Studios")
+    @batman = Factory.create(:game, :name => "Batman: Arkham Asylum", :developer => @rocksteady_studios, :created_at => 1.minute.ago)
+    
+    @valve = Factory.create(:developer, :name => "Valve")
+    @half_life = Factory.create(:game, :name => "Half-Life", :developer => @valve, :created_at => Time.now)
+  end
+  
+  it "should order by developer name given :'developer.name'" do
+    Game.order(:'developer.name').should be_in_order(:'developer.name')
+  end
+  
+  it "should behave like order(:'developer.name') given ':'developer.name!asc'" do
+    Game.order(:'developer.name!asc').should be_in_order(:'developer.name')
+  end
+  
+  it "should order by developer name in descending order given ':'developer.name!desc'" do
+    Game.order(:"developer.name!desc").reverse.should be_in_order(:'developer.name')
+  end
+end

data/spec/order_case_sensitivity_spec.rb

@@ -0,0 +1,56 @@
+require "spec_helper"
+
+describe "case-sensitivity of ordering" do
+  before(:each) do
+  
+  end
+  
+  it "should order in case-insensitive manner by default" do
+    games = [
+      Factory.create(:game, :name => "A"),
+      Factory.create(:game, :name => "a"),
+      Factory.create(:game, :name => "B")
+    ]
+    
+    Game.order(:name).should == games
+  end
+  
+  
+  it "should order in case-sensitive manner when :case_sensitive => true" do
+    games = [
+      Factory.create(:game, :name => "A"),
+      Factory.create(:game, :name => "B"),
+      Factory.create(:game, :name => "a")
+    ]
+    
+    Game.order(:name, :case_sensitive => true).should == games
+  end
+  
+  it "should order associated model's attributes in case-insensitive-manner by default" do
+    a1 = Factory.create(:developer, :name => "A")
+    a2 = Factory.create(:developer, :name => "a")
+    b = Factory.create(:developer, :name => "B")
+    
+    games = [
+      Factory.create(:game, :name => "game1", :developer => a1),
+      Factory.create(:game, :name => "game2", :developer => a2),
+      Factory.create(:game, :name => "game3", :developer => b)
+    ]
+    
+    Game.order(:"developer.name").should == games
+  end
+  
+  it "should order associated model's attributes in case-sensitive manner when :case_sensitive => true" do
+    a1 = Factory.create(:developer, :name => "A")
+    a2 = Factory.create(:developer, :name => "a")
+    b = Factory.create(:developer, :name => "B")
+    
+    games = [
+      Factory.create(:game, :name => "game1", :developer => a1),
+      Factory.create(:game, :name => "game3", :developer => b),
+      Factory.create(:game, :name => "game2", :developer => a2),
+    ]
+    
+    Game.order(:"developer.name", :case_sensitive => true).should == games
+  end
+end

data/spec/order_multiple_attributes_spec.rb

@@ -0,0 +1,19 @@
+require "spec_helper"
+
+describe "ordering by multiple attributes" do
+  before(:each) do
+    valve = Factory.create(:developer, :name => "Valve")
+    portal = Factory.create(:game, :name => "Portal", :developer => valve)
+    half_life = Factory.create(:game, :name => "Half-Life", :developer => valve)
+    
+    ea_redwood_shores = Factory.create(:developer, :name => "EA Redwood Shores")
+    the_godfather = Factory.create(:game, :name => "The Godfather", :developer => ea_redwood_shores)
+    dead_space = Factory.create(:game, :name => "Dead Space", :developer => ea_redwood_shores)
+    
+    @games_in_order = [dead_space, the_godfather, half_life, portal]
+  end
+  
+  it "should order by all attributes in given list" do
+    Game.order([:"developer.name", :name]).should == @games_in_order
+  end
+end

data/spec/order_spec.rb

@@ -0,0 +1,29 @@
+require "spec_helper"
+
+describe "order" do
+  before(:each) do
+    @dead_space = Factory.create(:game, :name => "Dead Space", :created_at => 10.minutes.ago)
+    @batman = Factory.create(:game, :name => "Batman: Arkham Asylum", :created_at => 1.minute.ago)
+    @half_life = Factory.create(:game, :name => "Half-Life", :created_at => Time.now)
+  end
+  
+  it "should order by name given ':name' symbol" do
+    Game.order(:name).should be_in_order(:name)
+  end
+  
+  it "should order by name given 'name' string" do
+    Game.order("name").should be_in_order(:name)
+  end
+  
+  it "should behave like order(:name) given ':name!asc'" do
+    Game.order(:"name!asc").should be_in_order(:name)
+  end
+  
+  it "should order by name in descending order given ':name!desc'" do
+    Game.order(:"name!desc").reverse.should be_in_order(:name)
+  end
+  
+  it "should use default ordering if the model is not orderable by the given attribute" do
+    Game.order(:updated_at).should be_in_order(:created_at)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+require 'rubygems'
+require 'bundler/setup'
+Bundler.setup(:default, :test)
+
+require 'active_record'
+require File.join(File.dirname(__FILE__), '..', 'init')
+require File.join(File.dirname(__FILE__), 'support', 'lib', 'activerecord_test_connector')
+ActiveRecordTestConnector.setup
+
+require 'spec'
+require 'active_support'
+require 'factory_girl'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir[File.expand_path(File.join(File.dirname(__FILE__),'support','**','*.rb'))].each {|f| require f}
+
+Spec::Runner.configure do |config|
+  config.before(:each) do
+    Game.delete_all
+    Developer.delete_all
+  end
+end

data/spec/support/database.yml

@@ -0,0 +1,11 @@
+sqlite3:
+  adapter: sqlite3
+  database: ":memory:"
+  
+postgresql:
+  adapter: postgresql
+  database: ar_orderable_test
+  
+mysql:
+  adapter: mysql
+  database: ar_orderable_test

data/spec/support/factories.rb

@@ -0,0 +1,7 @@
+Factory.define :game do |game|
+  game.developer
+end
+
+Factory.define :developer do |developer|
+  developer.name
+end

data/spec/support/lib/activerecord_test_connector.rb

@@ -0,0 +1,60 @@
+require 'active_record'
+require 'active_record/version'
+require 'active_record/fixtures'
+
+# Taken from will_paginate (http://github.com/mislav/will_paginate/)
+# with small modifications 
+class ActiveRecordTestConnector
+  cattr_accessor :able_to_connect
+  cattr_accessor :connected
+
+  MODELS_PATH = File.join(File.dirname(__FILE__), '..', 'models')
+
+  # Set our defaults
+  self.connected = false
+  self.able_to_connect = true
+
+  def self.setup
+    unless self.connected || !self.able_to_connect
+      setup_connection
+      load_schema
+      add_load_path MODELS_PATH
+      self.connected = true
+    end
+  end
+
+  private
+  
+  def self.add_load_path(path)
+    dep = defined?(ActiveSupport::Dependencies) ? ActiveSupport::Dependencies : ::Dependencies
+    autoload_paths = dep.respond_to?(:autoload_paths) ? dep.autoload_paths : dep.load_paths
+    autoload_paths.unshift path
+  end
+
+  def self.setup_connection
+    db = ENV['DB'].blank?? 'sqlite3' : ENV['DB']
+    
+    configurations = YAML.load_file(File.join(File.dirname(__FILE__), '..', 'database.yml'))
+    raise "no configuration for '#{db}'" unless configurations.key? db
+    configuration = configurations[db]
+    
+    ActiveRecord::Base.logger = Logger.new(STDOUT) if $0 == 'irb'
+    puts "using #{configuration['adapter']} adapter" unless ENV['DB'].blank?
+    
+    gem 'sqlite3-ruby' if 'sqlite3' == db
+    
+    ActiveRecord::Base.establish_connection(configuration)
+    ActiveRecord::Base.configurations = { db => configuration }
+    
+    unless Object.const_defined?(:QUOTED_TYPE)
+      Object.send :const_set, :QUOTED_TYPE, ActiveRecord::Base.connection.quote_column_name('type')
+    end
+  end
+
+  def self.load_schema
+    ActiveRecord::Base.silence do
+      ActiveRecord::Migration.verbose = false
+      load File.join(File.dirname(__FILE__), '..', 'schema.rb')
+    end
+  end
+end

data/spec/support/matchers/be_in_order.rb

@@ -0,0 +1,28 @@
+Spec::Matchers.define :be_in_order do |attr_name|
+  match do |results|
+    ret_val = true
+    previous = nil
+    results.each do |result|
+      unless previous.nil?
+        unless attr_value(result, attr_name) >= attr_value(previous, attr_name)
+          ret_val = false
+          break
+        end
+      end
+      
+      previous = result
+    end
+    
+    ret_val
+  end
+end
+
+def attr_value(obj, attr_name)
+  current = obj
+  
+  attr_name.to_s.split('.').each do |name|
+    current = current.send(name.to_sym)
+  end
+  
+  current
+end

data/spec/support/models/developer.rb

@@ -0,0 +1,5 @@
+class Developer < ActiveRecord::Base
+  has_many :games
+  
+  orderable :by => [:name]
+end

data/spec/support/models/game.rb

@@ -0,0 +1,5 @@
+class Game < ActiveRecord::Base
+  belongs_to :developer
+  
+  orderable :by => [:name, :created_at, :"developer.name"], :default => :created_at
+end

data/spec/support/schema.rb

@@ -0,0 +1,12 @@
+ActiveRecord::Schema.define do
+  create_table :developers, :force => true do |t|
+    t.string :name
+    t.timestamps
+  end
+  
+  create_table :games, :force => true do |t|
+    t.string :name
+    t.references :developer
+    t.timestamps
+  end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification 
+name: ar_orderable
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- "Mikko Nyl\xC3\xA9n"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-19 00:00:00 +03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 2
+        - 3
+        - 5
+        version: 2.3.5
+  type: :runtime
+  version_requirements: *id001
+description: ar_orderable adds a consistent way to order results at database level using ActiveRecord. Supports ordering by multiple attributes and by associated model's attributes.
+email: mikko.nylen@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+files: 
+- .gitignore
+- .rvmrc
+- Gemfile
+- README.textile
+- Rakefile
+- VERSION
+- ar_orderable.gemspec
+- init.rb
+- lib/orderable.rb
+- spec/order_belongs_to_association_spec.rb
+- spec/order_case_sensitivity_spec.rb
+- spec/order_multiple_attributes_spec.rb
+- spec/order_spec.rb
+- spec/spec_helper.rb
+- spec/support/database.yml
+- spec/support/factories.rb
+- spec/support/lib/activerecord_test_connector.rb
+- spec/support/matchers/be_in_order.rb
+- spec/support/models/developer.rb
+- spec/support/models/game.rb
+- spec/support/schema.rb
+has_rdoc: true
+homepage: http://github.com/mnylen/ar_orderable
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A small ActiveRecord addition that makes ordering of results easier and cleaner
+test_files: 
+- spec/order_belongs_to_association_spec.rb
+- spec/order_case_sensitivity_spec.rb
+- spec/order_multiple_attributes_spec.rb
+- spec/order_spec.rb
+- spec/spec_helper.rb
+- spec/support/factories.rb
+- spec/support/lib/activerecord_test_connector.rb
+- spec/support/matchers/be_in_order.rb
+- spec/support/models/developer.rb
+- spec/support/models/game.rb
+- spec/support/schema.rb