ransack 1.2.3 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5aa40c542dc092988fc46513f6f30ea6ccef3ca6
-  data.tar.gz: 22a6a9efcafac2879f41cbaa5f90fdac6d9d85f8
+  metadata.gz: ce6d8c3f3a255efe1c665afc046f8b03c5ff907f
+  data.tar.gz: cca91cd37e10bbcf3c69df6553a4b09cdfc606d8
 SHA512:
-  metadata.gz: f31218e27e2a9aae5cd2bbaf5588627872338c4f5fcb6babb8f2dc4b81abf0c645ea3edb84ee514aaa2d946621c54cbba835400b9389ad8f61bd68356e6c2890
-  data.tar.gz: 117c2bf5a8f01b1461a03073c335dcb544ccf6b09187517123c90235efac7465cf4c9bde21d6f3e75880e3a032b0bc9b4e04a9c006cb7a15111fbadfd6486ed7
+  metadata.gz: f7d39c9fa75f48bcf996e04050b188f1f3c5e47c1ee5f8edd85deb4fdd6193da986d88230b781f8095559db691e1f8ba7d73034107565a3eecc35bf259b509bf
+  data.tar.gz: 3a0a64c7295ccc4fe744a568db56ad24dea62e52f325e9edf750cb729b08ec33f1fcd47bd4dce6d6ee1f53cd0a9639bbd7952dc175908b5b1dc76ee504c317ef

data/.travis.yml

@@ -1,12 +1,11 @@
 language: ruby
 
-before_install:
-  - travis_retry gem install bundler
+sudo: false
 
 rvm:
+  - 2.1
+  - 2.0
   - 1.9.3
-  - 2.0.0
-  - 2.1.1
 
 env:
   - RAILS=4-1-stable DB=sqlite3

data/CONTRIBUTING.md

@@ -5,8 +5,8 @@ Ransack is an open source project and we encourage contributions.
 When filing an issue on the Ransack project, please provide these details:
 
 * A comprehensive list of steps to reproduce the issue.
-* The version of Ransack *and* the version of Rails.
-* Any relevant stack traces ("Full trace" preferred)
+* The version of Ransack *and* the version of Rails and Ruby.
+* Any relevant stack traces ("Full trace" preferred).
 
 In 99% of cases, this information is enough to determine the cause and
 solution to the problem that is being described.
@@ -20,6 +20,10 @@ if the information requested is provided.
 We gladly accept pull requests to fix bugs and, in some circumstances, add new
 features to Ransack.
 
+Before issuing a pull request, please make sure that all specs are passing,
+that any new features have test coverage, and that anything that breaks
+backward compatibility has a very good reason for doing so.
+
 Here's a quick guide:
 
 1. Fork the repo.
@@ -38,7 +42,9 @@ a test!
 
 5. Push to your fork and submit a pull request. If the changes will apply
 cleanly to the latest stable branches and master branch, you will only need
-to submit one pull request.
+to submit one pull request. If the pull request only contains documentation
+changes, please add `[skip ci]` to the commit message so that the Travis test
+suite does not needlessly run.
 
 At this point you're waiting on us. We like to at least comment on, if not
 accept, pull requests within three business days (and, typically, one business
@@ -55,11 +61,13 @@ taken straight from the Ruby on Rails guide:
 Syntax:
 
 * Two spaces, no tabs.
+* 80 characters per line.
 * No trailing whitespace. Blank lines should not have any space.
 * Prefer &&/|| over and/or.
 * `MyClass.my_method(my_arg)` not `my_method( my_arg )` or my_method my_arg.
 * `a = b` and not `a=b`.
-* `a_method { |block| ... }` and not `a_method { | block | ... }`
+* `a_method { |block| ... }` and not `a_method { | block | ... }` or
+`a_method{|block| ...}`.
 * Follow the conventions you see used in the source already.
 
 And in case we didn't emphasize it enough: we love tests!

data/Gemfile

@@ -5,23 +5,22 @@ gem 'rake'
 
 rails = ENV['RAILS'] || '4-1-stable'
 
-gem 'polyamorous', '~> 1.0.0'
+gem 'polyamorous', '~> 1.1'
 
 case rails
 when /\// # A path
   gem 'activesupport', path: "#{rails}/activesupport"
-  gem 'activemodel', path: "#{rails}/activemodel"
   gem 'activerecord', path: "#{rails}/activerecord"
-  gem 'actionpack', path: "#{rails}/activerecord"
+  gem 'actionpack', path: "#{rails}/actionpack"
 when /^v/ # A tagged version
-  git 'git://github.com/rails/rails.git', tag: rails do
+  git 'git://github.com/rails/rails.git', :tag => rails do
     gem 'activesupport'
     gem 'activemodel'
     gem 'activerecord'
     gem 'actionpack'
   end
 else
-  git 'git://github.com/rails/rails.git', branch: rails do
+  git 'git://github.com/rails/rails.git', :branch => rails do
     gem 'activesupport'
     gem 'activemodel'
     gem 'activerecord'

data/README.md

@@ -12,7 +12,7 @@ and maintained by [Ryan Bigg](http://twitter.com/ryanbigg),
 [Jon Atack](http://twitter.com/jonatack) and a great group of [contributors](https://github.com/activerecord-hackery/ransack/graphs/contributors).
 While it supports many of the same features as MetaSearch, its underlying
 implementation differs greatly from MetaSearch,
-and _backwards compatibility is not a design goal._
+and backwards compatibility is not a design goal.
 
 Ransack enables the creation of both simple and
 [advanced](http://ransack-demo.herokuapp.com/users/advanced_search)
@@ -25,28 +25,43 @@ instead.
 
 ## Getting started
 
-In your Gemfile:
+Because ActiveRecord has been evolving quite a bit, your friendly Ransack is
+available in several flavors! Take your pick:
+
+In your Gemfile, for the last officially released gem compatible with Rails
+3.x, 4.0 and 4.1 (for Rails 4.2, use the dedicated `rails-4.2` branch described
+below for now):
+
+```ruby
+gem 'ransack'
+```
+
+Or if you want to use the latest updates on the Ransack master branch:
 
 ```ruby
-gem "ransack"  # Last officially released gem (compatible with Rails 3, 4.0 and 4.1!)
+gem 'ransack', github: 'activerecord-hackery/ransack'
 ```
 
-Or if you want to use the latest updates on the master branch:
+If you are using Rails 4.1, you may prefer the dedicated [Rails 4.1 branch](https://github.com/activerecord-hackery/ransack/tree/rails-4.1) which
+contains the latest updates, supports only 4.1, and is lighter and somewhat
+faster:
 
 ```ruby
-gem "ransack", github: "activerecord-hackery/ransack"  # Track git repo
+gem 'ransack', github: 'activerecord-hackery/ransack', branch: 'rails-4.1'
 ```
 
-If you are on Rails 4.1 (or 4.2.0.alpha or master), you may prefer to use the dedicated [Rails 4.1 branch](https://github.com/activerecord-hackery/ransack/tree/rails-4.1) which contains the latest updates, supports only 4.1 and up, and is lighter and somewhat faster:
+Similarly, if you are using Rails 4.0, you may prefer the dedicated [Rails 4 branch](https://github.com/activerecord-hackery/ransack/tree/rails-4) for the
+same reasons:
 
 ```ruby
-gem "ransack", github: "activerecord-hackery/ransack", branch: "rails-4.1"
+gem 'ransack', github: 'activerecord-hackery/ransack', branch: 'rails-4'
 ```
 
-Similarly, if you are on Rails 4.0, you may prefer to use the dedicated [Rails 4 branch](https://github.com/activerecord-hackery/ransack/tree/rails-4) for the same reasons:
+Last but definitely not least, an experimental [Rails 4.2 branch](https://github.com/activerecord-hackery/ransack/tree/rails-4.2) is
+available for those on the edge:
 
 ```ruby
-gem "ransack", github: "activerecord-hackery/ransack", branch: "rails-4"
+gem 'ransack', github: 'activerecord-hackery/ransack', branch: 'rails-4.2'
 ```
 
 ## Usage
@@ -55,33 +70,35 @@ Ransack can be used in one of two modes, simple or advanced.
 
 ### Simple Mode
 
-This mode works much like MetaSearch, for those of you who are familiar with it, and
-requires very little setup effort.
+This mode works much like MetaSearch, for those of you who are familiar with
+it, and requires very little setup effort.
 
 If you're coming from MetaSearch, things to note:
 
-  1. The default param key for search params is now `:q`, instead of `:search`. This is
-     primarily to shorten query strings, though advanced queries (below) will still
-     run afoul of URL length limits in most browsers and require a switch to HTTP
-     POST requests. This key is
-[configurable](https://github.com/activerecord-hackery/ransack/wiki/Configuration).
+  1. The default param key for search params is now `:q`, instead of `:search`.
+  This is primarily to shorten query strings, though advanced queries (below)
+  will still run afoul of URL length limits in most browsers and require a
+  switch to HTTP POST requests. This key is [configurable]
+  (https://github.com/activerecord-hackery/ransack/wiki/Configuration).
 
-  2. `form_for` is now `search_form_for`, and validates that a Ransack::Search object
-     is passed to it.
+  2. `form_for` is now `search_form_for`, and validates that a Ransack::Search
+  object is passed to it.
 
-  3. Common ActiveRecord::Relation methods are no longer delegated by the search object.
-     Instead, you will get your search results (an ActiveRecord::Relation in the case of
-     the ActiveRecord adapter) via a call to `Search#result`. If passed `distinct: true`,
-     `result` will generate a `SELECT DISTINCT` to avoid returning duplicate rows, even if
-     conditions on a join would otherwise result in some.
+  3. Common ActiveRecord::Relation methods are no longer delegated by the
+  search object. Instead, you will get your search results (an
+  ActiveRecord::Relation in the case of the ActiveRecord adapter) via a call to
+  `Search#result`. If passed `distinct: true`, `result` will generate a `SELECT
+  DISTINCT` to avoid returning duplicate rows, even if conditions on a join
+  would otherwise result in some.
 
-     Please note that for many databases, a sort on an associated table's columns will
-     result in invalid SQL with `distinct: true` -- in those cases, you're on your own,
-     and will need to modify the result as needed to allow these queries to work. Thankfully,
-     9 times out of 10, sort against the search's base is sufficient, though, as that's
-     generally what's being displayed on your results page.
+  Please note that for many databases, a sort on an associated table's columns
+  will result in invalid SQL with `distinct: true` -- in those cases, you're on
+  your own, and will need to modify the result as needed to allow these queries
+  to work. Thankfully, 9 times out of 10, sort against the search's base is
+  sufficient, though, as that's generally what's being displayed on your
+  results page.
 
-In your controller:
+####In your controller
 
 ```ruby
 def index
@@ -89,40 +106,68 @@ def index
   @people = @q.result(distinct: true)
 end
 ```
+or without `distinct:true`, for sorting on an associated table's columns (in
+this example, with preloading each Person's Articles and pagination):
 
-In your view:
+```ruby
+def index
+  @q = Person.search(params[:q])
+  @people = @q.result.includes(:articles).page(params[:page])
+end
+```
+
+####In your view
+
+The two primary Ransack view helpers are `search_form_for` and `sort_link`,
+which are defined in
+[Ransack::Helpers::FormHelper](lib/ransack/helpers/form_helper.rb).
+
+#####1. Ransack's `search_form_for` helper replaces `form_for` for creating the view search form:
 
 ```erb
 <%= search_form_for @q do |f| %>
   <%= f.label :name_cont %>
-  <%= f.text_field :name_cont %>
+  <%= f.search_field :name_cont %>
   <%= f.label :articles_title_start %>
-  <%= f.text_field :articles_title_start %>
+  <%= f.search_field :articles_title_start %>
   <%= f.submit %>
 <% end %>
 ```
 
-`cont` (contains) and `start` (starts with) are just two of the available search predicates.
-See [Constants](https://github.com/activerecord-hackery/ransack/blob/master/lib/ransack/constants.rb) for a full list and the [wiki](https://github.com/activerecord-hackery/ransack/wiki/Basic-Searching) for more description.
+`cont` (contains) and `start` (starts with) are just two of the available
+search predicates. See [Constants]
+(https://github.com/activerecord-hackery/ransack/blob/master/lib/ransack/constants.rb)
+for a full list and the [wiki]
+(https://github.com/activerecord-hackery/ransack/wiki/Basic-Searching)
+for more information.
 
-You can also set the `search_form_for` answer format, like this:
+The `search_form_for` answer format can be set like this:
 ```erb
 <%= search_form_for(@q, format: :pdf) do |f| %>
-  ...
-<% end %>
 
 <%= search_form_for(@q, format: :json) do |f| %>
-  ...
-<% end %>
+```
+
+#####2. Ransack's `sort_link` helper creates table headers that are sortable links:
+
+```erb
+<%= content_tag :th, sort_link(@q, :name) %>
+```
+Additional options can be passed after the column attribute, like a different
+column title or a default sort order:
+
+```erb
+<%= content_tag :th, sort_link(@q, :name, 'Last Name', default_order: :desc) %>
 ```
 
 ### Advanced Mode
 
-"Advanced" searches (ab)use Rails' nested attributes functionality in order to generate
-complex queries with nested AND/OR groupings, etc. This takes a bit more work but can
-generate some pretty cool search interfaces that put a lot of power in the hands of
-your users. A notable drawback with these searches is that the increased size of the
-parameter string will typically force you to use the HTTP POST method instead of GET. :(
+"Advanced" searches (ab)use Rails' nested attributes functionality in order to
+generate complex queries with nested AND/OR groupings, etc. This takes a bit
+more work but can generate some pretty cool search interfaces that put a lot of
+power in the hands of your users. A notable drawback with these searches is
+that the increased size of the parameter string will typically force you to use
+the HTTP POST method instead of GET. :(
 
 This means you'll need to tweak your routes...
 
@@ -156,7 +201,9 @@ construct much more complex search forms, such as the one on the
 
 ### Ransack #search method
 
-Ransack will try to to make `#search` available in your models, but in the case that `#search` has already been defined, you can use `#ransack` instead. For example the following would be equivalent:
+Ransack will try to to make `#search` available in your models, but in the case
+that `#search` has already been defined, you can use `#ransack` instead. For
+example the following would be equivalent:
 
 ```ruby
 Article.search(params[:q])
@@ -196,7 +243,7 @@ end
 class SupervisorsController < ApplicationController
   def index
     @search = Supervisor.search(params[:q])
-    @supervisors = @search.result(distinct: true)
+    @supervisors = @search.result.includes(:department, :employees)
   end
 end
 ```
@@ -206,21 +253,40 @@ end
 ```erb
 <%= search_form_for @search do |f| %>
   <%= f.label :last_name_cont %>
-  <%= f.text_field :last_name_cont %>
+  <%= f.search_field :last_name_cont %>
 
   <%= f.label :department_title_cont %>
-  <%= f.text_field :department_title_cont %>
+  <%= f.search_field :department_title_cont %>
 
   <%= f.label :employees_last_name_cont %>
-  <%= f.text_field :employees_last_name_cont %>
+  <%= f.search_field :employees_last_name_cont %>
 
   <%= f.submit "search" %>
 <% end %>
+...
+<%= content_tag :table %>
+  <%= content_tag :th, sort_link(@q, :last_name) %>
+  <%= content_tag :th, sort_link(@q, 'departments.title') %>
+  <%= content_tag :th, sort_link(@q, 'employees.last_name') %>
+<% end %>
 ```
 
-## Using SimpleForm
+### Using Ransackers to add custom search functions via Arel
+
+The main premise behind Ransack is to provide access to
+**Arel predicate methods**. Ransack provides special methods, called
+_ransackers_, for creating additional search functions via Arel. More
+information about `ransacker` methods can be found [here in the wiki]
+(https://github.com/activerecord-hackery/ransack/wiki/Using-Ransackers).
+Feel free to contribute working `ransacker` code examples to the wiki!
+
+### Using SimpleForm
+
+If you want to combine form builders of ransack and SimpleForm, just set the
+RANSACK_FORM_BUILDER environment variable before Rails started, e.g. in
+``config/application.rb`` before ``require 'rails/all'`` and of course use
+``gem 'simple_form'`` in your ``Gemfile``:
 
-If you want to combine form builders of ransack and SimpleForm, just set the RANSACK_FORM_BUILDER environment variable before Rails started, e.g. in ``config/application.rb`` before ``require 'rails/all'`` and of course use ``gem 'simple_form'`` in your ``Gemfile``:
 ```ruby
 require File.expand_path('../boot', __FILE__)
 
@@ -229,16 +295,55 @@ ENV['RANSACK_FORM_BUILDER'] = '::SimpleForm::FormBuilder'
 require 'rails/all'
 ```
 
-## I18n
+### Authorization
+
+By default, Ransack exposes search on any model column, so make sure you
+sanitize your params and only pass the allowed keys. Alternately, you can
+define these class methods on your models to apply selective authorization
+based on a given auth object:
+
+* `def self.ransackable_attributes(auth_object = nil)`
+* `def self.ransackable_associations(auth_object = nil)`
+* `def self.ransackable_scopes(auth_object = nil)`
+* `def self.ransortable_attributes(auth_object = nil)` (for sorting)
+
+Any values not included in the arrays returned from these methods will be
+ignored. The auth object should be optional when building the search, and is
+ignored by default:
+
+```
+Employee.search({ salary_gt: 100000 }, { auth_object: current_user })
+```
+
+### Scopes
+
+Searching by scope requires defining a whitelist of `ransackable_scopes` on the
+model class. By default all class methods (e.g. scopes) are ignored. Scopes
+will be applied for matching `true` values, or for given values if the scope
+accepts a value:
+
+```
+Employee.search({ active: true, hired_since: '2013-01-01' })
+```
+
+### I18n
 
-Ransack translation files are available in [Ransack::Locale](lib/ransack/locale). You may also be interested in one of the many translations for Ransack available at http://www.localeapp.com/projects/2999.
+Ransack translation files are available in
+[Ransack::Locale](lib/ransack/locale). You may also be interested in one of the
+many translations for Ransack available at
+http://www.localeapp.com/projects/2999.
 
 ## Contributions
 
 To support the project:
 
-* Use Ransack in your apps, and let us know if you encounter anything that's broken or missing. A failing spec is awesome. A pull request with tests that pass is even better! Before filing an issue or pull request, be sure to read the [Contributing Guide](CONTRIBUTING.md).
-* Spread the word on Twitter, Facebook, and elsewhere if Ransack's been useful to you. The more people who are using the project, the quicker we can find and fix bugs!
+* Use Ransack in your apps, and let us know if you encounter anything that's
+broken or missing. A failing spec is awesome. A pull request with tests that
+pass is even better! Before filing an issue or pull request, be sure to read
+the [Contributing Guide](CONTRIBUTING.md).
+* Spread the word on Twitter, Facebook, and elsewhere if Ransack's been useful
+to you. The more people who are using the project, the quicker we can find and
+fix bugs!
 
 ## Copyright
 

data/lib/ransack.rb

@@ -10,7 +10,7 @@ end
 
 Ransack.configure do |config|
   Ransack::Constants::AREL_PREDICATES.each do |name|
-    config.add_predicate name, arel_predicate: name
+    config.add_predicate name, :arel_predicate => name
   end
 
   Ransack::Constants::DERIVED_PREDICATES.each do |args|

data/lib/ransack/adapters/active_record/3.0/context.rb

@@ -68,6 +68,22 @@ module Ransack
           .type
         end
 
+        # All dependent JoinAssociation items used in the search query
+        #
+        def join_associations
+          @join_dependency.join_associations
+        end
+
+        def join_sources
+          raise NotImplementedError,
+          "ActiveRecord 3.0 does not use join_sources or support joining relations with Arel::Join nodes. Use join_associations."
+        end
+
+        def alias_tracker
+          raise NotImplementedError,
+          "ActiveRecord 3.0 does not have an alias tracker"
+        end
+
         private
 
         def get_parent_and_attribute_name(str, parent = @base)