ransack 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ce6d8c3f3a255efe1c665afc046f8b03c5ff907f
-  data.tar.gz: cca91cd37e10bbcf3c69df6553a4b09cdfc606d8
+  metadata.gz: 0db00f7b95f26e2128972c34185a796559165d06
+  data.tar.gz: f1ae294b2bafceeb8a15429f19451cb52aadfe6a
 SHA512:
-  metadata.gz: f7d39c9fa75f48bcf996e04050b188f1f3c5e47c1ee5f8edd85deb4fdd6193da986d88230b781f8095559db691e1f8ba7d73034107565a3eecc35bf259b509bf
-  data.tar.gz: 3a0a64c7295ccc4fe744a568db56ad24dea62e52f325e9edf750cb729b08ec33f1fcd47bd4dce6d6ee1f53cd0a9639bbd7952dc175908b5b1dc76ee504c317ef
+  metadata.gz: 808bcea8000e9b72d236bed60f17fa66f44ed41b2d6eca83c64ced249f1f96346651312ca44dc0248cf90bc23ed7e8d092232846c6948f22c1f6847ff16079ac
+  data.tar.gz: 4826df4e710ce5022aa7231b77fc12e482832db3bcbef9e111c0bdcee7a5c172038be6087e867c77a249c5fad7c0f4918752f01144e3b4495c28b4039092b759

data/.travis.yml

@@ -5,9 +5,12 @@ sudo: false
 rvm:
   - 2.1
   - 2.0
-  - 1.9.3
+  - 1.9
 
 env:
+  - RAILS=master DB=sqlite3
+  - RAILS=master DB=mysql
+  - RAILS=master DB=postgres
   - RAILS=4-1-stable DB=sqlite3
   - RAILS=4-1-stable DB=mysql
   - RAILS=4-1-stable DB=postgres

data/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Change Log
+This change log was started in August 2014. All notable changes to this project
+henceforth should be documented here.
+
+## Version 1.4.0 - 2014-09-23
+### Added
+
+*   Add support for Rails 4.2.0! Let us know if you encounter any issues.
+
+    *Xiang Li*
+
+*   Add `not_true` and `not_false` predicates and update the "Basic Searching"
+    wiki. Fixes #123, #353.
+
+    *Pedro Chambino*
+
+*   Add `ro.yml` Romanian translation file.
+
+    *Andreas Philippi*
+
+*   Add new documentation in the README explaining how to group queries by `OR`
+    instead of the default `AND` using the `m: 'or'` combinator.
+
+*   Add new documentation in the README and in the source code comments
+    explaining in detail how to handle whitelisting/authorization of
+    attributes, associations, sorts and scopes.
+
+*   Add new documentation in the README explaining in more detail how to use
+    scopes for searching with Ransack.
+
+*   Begin a CHANGELOG.
+
+    *Jon Atack*
+
+### Fixed
+
+*   Fix singular/plural Active Record attribute translations.
+
+    *Andreas Philippi*
+
+*   Fix the params hash being modified by `Search.new` and the Ransack scope.
+
+    *Daniel Rikowski*
+
+*   Apply default scope conditions for association joins (fix for Rails 3).
+
+    Avoid selecting records from joins that would normally be filtered out
+    if they were selected from the base table. Only applies to Rails 3, as
+    this issue was fixed in Rails 4.
+
+    *Andrew Vit*
+
+*   Fix incoherent code examples in the README Associations section that
+    sometimes used `@q` and other times `@search`.
+
+    *Jon Atack*
+
+### Changed
+
+*   Refactor Ransack::Translate.
+
+*   Rewrite much of the Ransack README documentation, including the
+    Associations section code examples and the Authorizations section detailing
+    how to whitelist attributes, associations, sorts and scopes.
+    
+    *Jon Atack*
+
+## Version 1.3.0 - 2014-08-23
+### Added
+
+*   Add search scopes by popular demand. Using `ransackable_scopes`, users can
+    define whitelists for allowed model scopes on a parent table. Not yet
+    implemented for associated models' scopes; scopes must be defined on the
+    parent table.
+
+    *Gleb Mazovetskiy*, *Andrew Vit*, *Sven Schwyn*
+
+*   Add `JOINS` merging.
+
+*   Add `OR` grouping on base search.
+
+*   Allow authorizing/whitelisting attributes, associations, sorts and scopes.
+
+*   Improve boolean predicates’ handling of `false` values.
+
+*   Allow configuring Ransack to raise on instead of ignore unknown search
+    conditions.
+
+*   Allow passing blank values to search without crashing.
+
+*   Add wildcard escaping compatibility for SQL Server databases.
+
+*   Add various I18n translations.

data/Gemfile

@@ -3,7 +3,7 @@ gemspec
 
 gem 'rake'
 
-rails = ENV['RAILS'] || '4-1-stable'
+rails = ENV['RAILS'] || 'master'
 
 gem 'polyamorous', '~> 1.1'
 

data/README.md

@@ -9,7 +9,8 @@ Ransack is a rewrite of [MetaSearch]
 (https://github.com/activerecord-hackery/meta_search)
 created by [Ernie Miller](http://twitter.com/erniemiller)
 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).
+[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.
@@ -25,44 +26,25 @@ instead.
 
 ## Getting started
 
-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):
+In your Gemfile, for the last officially released gem for Rails 3 and 4:
 
 ```ruby
 gem 'ransack'
 ```
 
-Or if you want to use the latest updates on the Ransack master branch:
+Or if you want to use the latest updates (including Rails 4.2 compatibility):
 
 ```ruby
 gem 'ransack', github: 'activerecord-hackery/ransack'
 ```
 
-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', branch: 'rails-4.1'
-```
-
-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'
-```
-
-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.2'
-```
+The other branches (`rails-4`, `rails-4.1`, and `rails-4.2`) were each used for
+running Ransack with the latest upcoming version of Rails at the time. They are
+lighter and somewhat faster-running because they do not have to support previous
+versions of Rails and Active Record. However, once support for that version of
+Rails is merged into Ransack master, the branches are no longer actively
+maintained with the latest fixes and additions to Ransack -- unless the
+community submits pull requests to maintain them, and you are welcome to do so!
 
 ## Usage
 
@@ -87,16 +69,18 @@ If you're coming from MetaSearch, things to note:
   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.
+  `Search#result`.
+  
+  4. 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
+  may 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.
+  to work. If `distinct: true` is causing you problems, another way to remove
+  duplicates is to call `#to_a.uniq` on your collection instead (see the next
+  section below).
 
 ####In your controller
 
@@ -113,6 +97,8 @@ this example, with preloading each Person's Articles and pagination):
 def index
   @q = Person.search(params[:q])
   @people = @q.result.includes(:articles).page(params[:page])
+  # or use `to_a.uniq` to remove duplicates (can also be done in the view):
+  @people = @q.result.includes(:articles).page(params[:page]).to_a.uniq
 end
 ```
 
@@ -126,10 +112,19 @@ which are defined in
 
 ```erb
 <%= search_form_for @q do |f| %>
+
+  # Search if the name field contains...
   <%= f.label :name_cont %>
   <%= f.search_field :name_cont %>
+
+  # Search if an associated articles.title starts with...
   <%= f.label :articles_title_start %>
   <%= f.search_field :articles_title_start %>
+
+  # Attributes may be chained. Search multiple attributes for one value...
+  <%= f.label :name_or_description_or_email_or_articles_title_cont %>
+  <%= f.search_field :name_or_description_or_email_or_articles_title_cont %>
+
   <%= f.submit %>
 <% end %>
 ```
@@ -210,9 +205,10 @@ Article.search(params[:q])
 Article.ransack(params[:q])
 ```
 
-### has_many and belongs_to associations
+### Associations
 
-You can easily use Ransack to search in associated objects.
+You can easily use Ransack to search for objects in `has_many` and `belongs_to`
+associations.
 
 Given you have these associations ...
 
@@ -220,7 +216,7 @@ Given you have these associations ...
 class Employee < ActiveRecord::Base
   belongs_to :supervisor
 
-  # has attribute last_name:string
+  # has attributes first_name:string and last_name:string
 end
 
 class Department < ActiveRecord::Base
@@ -242,8 +238,8 @@ end
 ```ruby
 class SupervisorsController < ApplicationController
   def index
-    @search = Supervisor.search(params[:q])
-    @supervisors = @search.result.includes(:department, :employees)
+    @q = Supervisor.search(params[:q])
+    @supervisors = @q.result.includes(:department, :employees)
   end
 end
 ```
@@ -251,15 +247,15 @@ end
 ... you might set up your form like this ...
 
 ```erb
-<%= search_form_for @search do |f| %>
+<%= search_form_for @q do |f| %>
   <%= f.label :last_name_cont %>
   <%= f.search_field :last_name_cont %>
 
   <%= f.label :department_title_cont %>
   <%= f.search_field :department_title_cont %>
 
-  <%= f.label :employees_last_name_cont %>
-  <%= f.search_field :employees_last_name_cont %>
+  <%= f.label :employees_first_name_or_employees_last_name_cont %>
+  <%= f.search_field :employees_first_name_or_employees_last_name_cont %>
 
   <%= f.submit "search" %>
 <% end %>
@@ -280,50 +276,220 @@ 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
+### Authorization (whitelisting/blacklisting)
 
-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``:
+By default, searching and sorting are authorized on any column of your model
+and no class methods/scopes are whitelisted.
+
+Ransack adds four methods to `ActiveRecord::Base` that you can redefine as
+class methods in your models to apply selective authorization:
+`ransackable_attributes`, `ransackable_associations`, `ransackable_scopes` and
+`ransortable_attributes`.
+
+Here is how these four methods are implemented in Ransack:
 
 ```ruby
-require File.expand_path('../boot', __FILE__)
+def ransackable_attributes(auth_object = nil)
+  # By default returns all column names and any defined ransackers as an array
+  # of strings. For overriding with a whitelist array of strings.
+  column_names + _ransackers.keys
+end
 
-ENV['RANSACK_FORM_BUILDER'] = '::SimpleForm::FormBuilder'
+def ransackable_associations(auth_object = nil)
+  # By default returns the names of all associations as an array of strings.
+  # For overriding with a whitelist array of strings.
+  reflect_on_all_associations.map { |a| a.name.to_s }
+end
 
-require 'rails/all'
+def ransortable_attributes(auth_object = nil)
+  # By default returns the names of all attributes for sorting as an array of
+  # strings. For overriding with a whitelist array of strings.
+  ransackable_attributes(auth_object)
+end
+
+def ransackable_scopes(auth_object = nil)
+  # By default returns an empty array, i.e. no class methods/scopes
+  # are authorized. For overriding with a whitelist array of *symbols*.
+  []
+end
 ```
 
-### Authorization
+Any values not returned from these methods will be ignored by Ransack, i.e.
+they are not authorized.
 
-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:
+All four methods can receive a single optional parameter, `auth_object`. When
+you call the search or ransack method on your model, you can provide a value
+for an `auth_object` key in the options hash which can be used by your own
+overridden methods.
 
-* `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)
+Here is an example that puts all this together, adapted from
+[this blog post by Ernie Miller]
+(http://erniemiller.org/2012/05/11/why-your-ruby-class-macros-might-suck-mine-did/).
+In an `Article` model, add the following `ransackable_attributes` class method
+(preferably private):
+```ruby
+# article.rb
+class Article < ActiveRecord::Base
+
+  private
+
+  def self.ransackable_attributes(auth_object = nil)
+    if auth_object == :admin
+      # whitelist all attributes for admin
+      super
+    else
+      # whitelist only the title and body attributes for other users
+      super & %w(title body) 
+    end
+  end
+end
+```
+Here is example code for the `articles_controller`:
+```ruby
+# articles_controller.rb
+class ArticlesController < ApplicationController
 
-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:
+  def index
+    @q = Article.search(params[:q], auth_object: set_ransack_auth_object)
+    @articles = @q.result
+  end
+  
+  private
 
+  def set_ransack_auth_object
+    current_user.admin? ? :admin : nil
+  end
+end
 ```
-Employee.search({ salary_gt: 100000 }, { auth_object: current_user })
-```
+Trying it out in `rails console`:
+```ruby
+> Article
+=> Article(id: integer, person_id: integer, title: string, body: text) 
+
+> Article.ransackable_attributes
+=> ["title", "body"] 
+
+> Article.ransackable_attributes(:admin)
+=> ["id", "person_id", "title", "body"] 
 
-### Scopes
+> Article.search(id_eq: 1).result.to_sql
+=> SELECT "articles".* FROM "articles"  # Note that search param was ignored!
 
-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:
+> Article.search({ id_eq: 1 }, { auth_object: nil }).result.to_sql
+=> SELECT "articles".* FROM "articles"  # Search param still ignored!
 
+> Article.search({ id_eq: 1 }, { auth_object: :admin }).result.to_sql
+=> SELECT "articles".* FROM "articles"  WHERE "articles"."id" = 1
 ```
+That's it! Now you know how to whitelist/blacklist various elements in Ransack.
+
+### Using Scopes/Class Methods
+
+Continuing on from the preceding section, searching by scopes requires defining
+a whitelist of `ransackable_scopes` on the model class. The whitelist should be
+an array of *symbols*. 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:
+
+```ruby
+class Employee < ActiveRecord::Base
+  scope :active, ->(boolean = true) { (where active: boolean) }
+  scope :salary_gt, ->(amount) { where('salary > ?', amount) }
+
+  # Scopes are just syntactical sugar for class methods, which may also be used:
+
+  def self.hired_since(date)
+    where('start_date >= ?', date)
+  end
+
+  private
+
+  def self.ransackable_scopes(auth_object = nil)
+    if auth_object.try(:admin?)
+      # allow admin users access to all three methods
+      %i(active hired_since salary_gt)
+    else
+      # allow other users to search on active and hired_since only
+      %i(active hired_since)
+    end
+  end
+end
+
 Employee.search({ active: true, hired_since: '2013-01-01' })
+
+Employee.search({ salary_gt: 100_000 }, { auth_object: current_user })
+```
+
+### Grouping queries by OR instead of AND
+
+The default `AND` grouping can be changed to `OR` by adding `m: 'or'` to the
+query hash.
+
+You can easily try it in your controller code by changing `params[:q]` in the
+`index` action to `params[:q].try(:merge, m: 'or')` as follows:
+
+```ruby
+def index
+  @q = Artist.search(params[:q].try(:merge, m: 'or'))
+  @artists = @q.result
+end
+```
+Normally, if you wanted users to be able to toggle between `AND` and `OR`
+query grouping, you would probably set up your search form so that `m` was in
+the URL params hash, but here we assigned `m` manually just to try it out
+quickly.
+
+Alternatively, trying it in the Rails console:
+
+```ruby
+artists = Artist.search(name_cont: 'foo', style_cont: 'bar', m: 'or')
+=> Ransack::Search<class: Artist, base: Grouping <conditions: [
+  Condition <attributes: ["name"], predicate: cont, values: ["foo"]>,
+  Condition <attributes: ["style"], predicate: cont, values: ["bar"]>
+  ], combinator: or>>
+
+artists.result.to_sql
+=> "SELECT \"artists\".* FROM \"artists\"
+    WHERE ((\"artists\".\"name\" ILIKE '%foo%'
+    OR \"artists\".\"style\" ILIKE '%bar%'))"
+```
+
+The combinator becomes `or` instead of the default `and`, and the SQL query
+becomes `WHERE...OR` instead of `WHERE...AND`.
+
+This works with associations as well. Imagine an Artist model that has many
+Memberships, and many Musicians through Memberships:
+
+```ruby
+artists = Artist.search(name_cont: 'foo', musicians_email_cont: 'bar', m: 'or')
+=> Ransack::Search<class: Artist, base: Grouping <conditions: [
+  Condition <attributes: ["name"], predicate: cont, values: ["foo"]>,
+  Condition <attributes: ["musicians_email"], predicate: cont, values: ["bar"]>
+  ], combinator: or>>
+
+artists.result.to_sql
+=> "SELECT \"artists\".* FROM \"artists\"
+    LEFT OUTER JOIN \"memberships\"
+      ON \"memberships\".\"artist_id\" = \"artists\".\"id\"
+    LEFT OUTER JOIN \"musicians\"
+      ON \"musicians\".\"id\" = \"memberships\".\"musician_id\"
+    WHERE ((\"artists\".\"name\" ILIKE '%foo%'
+    OR \"musicians\".\"email\" ILIKE '%bar%'))"
+```
+
+### 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``:
+
+```ruby
+require File.expand_path('../boot', __FILE__)
+
+ENV['RANSACK_FORM_BUILDER'] = '::SimpleForm::FormBuilder'
+
+require 'rails/all'
 ```
 
 ### I18n