ransack 1.5.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c740816de011eb6b10728dc32b58e179304fad94
-  data.tar.gz: 07fb384c320453fe1176fc9c51261721318fe708
+  metadata.gz: f794e84fb4595e61da2a692b091c475698170fda
+  data.tar.gz: 3c74ff882fc59a32b25c83155c0e7ab4922b013c
 SHA512:
-  metadata.gz: 6647e2d472b4efd1e0051bd293698011c5a89ffdd096456c75da5b44f58b8ac825d3a5292d41a174e6b01e43bfd0bfc996685ee0fd30a13af91eaabb920162e3
-  data.tar.gz: 09e01482d289cfca68527dfce6161a8cf028846da7d510d927b59e155792e1c82b2aa3fc02eec5a4667b47b0fa08a13eb0fb2d542f3e91b368917540d13ce7ed
+  metadata.gz: f70a119cfb73857c715feafa11ed85ad862f4439653e266586e2bcccf6523c5374229483f273e7aa5d2a8ecc8973a1b3cab221393d6cb5e240723db1d63b16ff
+  data.tar.gz: d16a78c96996d5b28ff151ea89a6eb1729743c185e6a88d002b25f03b8326e7fa395fe523a885a02298867e65c80d3a7ad190c3e16e14a89f70314b25db6d03d

data/.travis.yml

@@ -1,32 +1,76 @@
+services: mongodb
+
 language: ruby
 
 sudo: false
 
 rvm:
+  - 2.2
   - 2.1
   - 2.0
   - 1.9
 
 env:
-  - RAILS=master DB=sqlite3
-  - RAILS=master DB=mysql
-  - RAILS=master DB=postgres
+  - RAILS=4-2-stable DB=mongodb
+  - RAILS=4-2-stable DB=sqlite3
+  - RAILS=4-2-stable DB=mysql
+  - RAILS=4-2-stable DB=postgres
+
+  - RAILS=4-1-stable DB=mongodb
   - RAILS=4-1-stable DB=sqlite3
   - RAILS=4-1-stable DB=mysql
   - RAILS=4-1-stable DB=postgres
+
   - RAILS=4-0-stable DB=sqlite3
   - RAILS=4-0-stable DB=mysql
   - RAILS=4-0-stable DB=postgres
+
   - RAILS=3-2-stable DB=sqlite
   - RAILS=3-2-stable DB=mysql
   - RAILS=3-2-stable DB=postgres
+
   - RAILS=3-1-stable DB=sqlite
   - RAILS=3-1-stable DB=mysql
   - RAILS=3-1-stable DB=postgres
+
   - RAILS=3-0-stable DB=sqlite
   - RAILS=3-0-stable DB=mysql
   - RAILS=3-0-stable DB=postgres
 
+matrix:
+  include:
+    - rvm: 2.2
+      env: RAILS=master DB=sqlite3
+    - rvm: 2.2
+      env: RAILS=master DB=mysql
+    - rvm: 2.2
+      env: RAILS=master DB=postgres
+  exclude:
+    - rvm: 2.2
+      env: RAILS=3-0-stable DB=sqlite
+    - rvm: 2.2
+      env: RAILS=3-0-stable DB=mysql
+    - rvm: 2.2
+      env: RAILS=3-0-stable DB=postgres
+
+  allow_failures:
+    - env: RAILS=master DB=sqlite3
+    - env: RAILS=master DB=mysql
+    - env: RAILS=master DB=postgres
+
+    - rvm: 2.2
+      env: RAILS=3-2-stable DB=sqlite
+    - rvm: 2.2
+      env: RAILS=3-2-stable DB=mysql
+    - rvm: 2.2
+      env: RAILS=3-2-stable DB=postgres
+    - rvm: 2.2
+      env: RAILS=3-1-stable DB=sqlite
+    - rvm: 2.2
+      env: RAILS=3-1-stable DB=mysql
+    - rvm: 2.2
+      env: RAILS=3-1-stable DB=postgres
+
 before_script:
   - mysql -e 'create database ransack collate utf8_general_ci;'
   - mysql -e 'use ransack;show variables like "%character%";show variables like "%collation%";'

data/CHANGELOG.md

@@ -1,29 +1,116 @@
 # Change Log
-This change log was started in August 2014. All notable changes to this project
-henceforth should be documented here.
 
-## Version 1.5.1 - 2014-10-30
+## Version 1.6.0 - 2015-01-12
 ### Added
 
-*   Add base specs for search on fields with `_start` and `_end`.
+*   Add support for using Ransack with `Mongoid 4.0` without associations
+    ([PR #407](https://github.com/activerecord-hackery/ransack/pull/407)).
+
+    *Zhomart Mukhamejanov*
+
+*   Add support and tests for passing stringy booleans for ransackable scopes
+    ([PR #460](https://github.com/activerecord-hackery/ransack/pull/460)).
+
+    *Josh Kovach*
+
+*   Add an sort_link option to not display sort direction arrows
+    ([PR #473](https://github.com/activerecord-hackery/ransack/pull/473)).
+
+    *Fred Bergman*
+
+*   Numerous documentation improvements to the README, Contributing Guide and
+    wiki.
 
     *Jon Atack*
 
-*   Add a failing spec for detecting attribute fields containing `_and_` that
-    needs to be fixed. Method names containing `_and_` and `_or_` are still not
-    parsed/detected correctly.
+### Fixed
+
+*   Fix passing arrays to ransackers with Rails 4.2 / Arel 6.0 (pull requests
+    [#486](https://github.com/activerecord-hackery/ransack/pull/486) and
+    [#488](https://github.com/activerecord-hackery/ransack/pull/488)).
+
+    *Idean Labib*
+
+*   Make `search_form_for`'s default `:as` option respect the custom search key
+    if it has been set
+    ([PR #470](https://github.com/activerecord-hackery/ransack/pull/470)).
+    Prior to this change, if you set a custom `search_key` option in the
+    Ransack initializer file, you'd have to also pass an `as: :whatever` option
+    to all of the search forms. Fixes
+    [#92](https://github.com/activerecord-hackery/ransack/issues/92).
+
+    *Robert Speicher*
+
+*   Fix sorting on polymorphic associations (missing downcase)
+    ([PR #467](https://github.com/activerecord-hackery/ransack/pull/467)).
+
+    *Eugen Neagoe*
+
+*   Fix Rails 5 / Arel 5 compatibility after the Arel and Active Record API
+    changed.
+
+*   Fix and add tests for sort_link `default_order` parsing if the option is set
+    as a string instead of symbol.
+
+*   Fix and add a test to handle `nil` in options passed to sort_link.
+
+*   Fix #search method name conflicts in the README.
 
     *Jon Atack*
 
+### Changed
+
+*   Refactor and DRY up FormHelper#SortLink. Encapsulate parsing into a
+    Plain Old Ruby Object with few public methods and small, private functional
+    methods. Limit mutations to explicit methods and mutate no ivars.
+
+*   Numerous speed improvements by using more specific Ruby methods like:
+      - `Hash#each_key` instead of `Hash#keys.each`
+      - `#none?` instead of `select#empty?`
+      - `#any?` instead of `#select` followed by `#any?`
+      - `#flat_map` instead of `#flatten` followed by `#map`
+      - `!include?` instead of `#none?`
+
+*   Replace `string#freeze` instances with top level constants to reduce string
+    allocations in Ruby < 2.1.
+
+*   Remove unneeded `Ransack::` namespacing on most of the constants.
+
+*   In enumerable methods, pass a symbol as an argument instead of a block.
+
+*   Update Travis-ci for Rails 5.0.0 and 4-2-stable.
+
+*   Update the Travis-ci tests and the Gemfile for Ruby 2.2.
+
+*   Replace `#search` with `#ransack` class methods in the README and wiki
+    code examples. Enabling the `#search` alias by default may possibly be
+    deprecated in the next major release (Ransack v.2.0.0) to address
+    [#369](https://github.com/activerecord-hackery/ransack/issues/369).
+
+    *Jon Atack*
+
+## Version 1.5.1 - 2014-10-30
 ### Fixed
 
-*   Fix a regression caused by incorrect string constants in context.rb.
+*   Fix a regression caused by incorrect string constants in `context.rb`.
+
+    *Kazuhiro Nishiyama*
+
+### Added
+
+*   Add base specs for search on fields with `_start` and `_end`.
+
+    *Jon Atack*
 
-    *Kazuhiro NISHIYAMA*
+*   Add a failing spec for detecting attribute fields containing `_and_` that
+    needs to be fixed. Attribute names containing `_and_` and `_or_` are still
+    not parsed/detected correctly.
+
+    *Jon Atack*
 
 ### Changed
 
-*   Remove duplicate code in spec/support/schema.rb.
+*   Remove duplicate code in `spec/support/schema.rb`.
 
     *Jon Atack*
 
@@ -33,8 +120,8 @@ henceforth should be documented here.
 
 *   Add support for multiple sort fields and default orders in Ransack
     `sort_link` helpers
-    ([pull request](https://github.com/activerecord-hackery/ransack/pull/438)).
-   
+    ([PR #438](https://github.com/activerecord-hackery/ransack/pull/438)).
+
     *Caleb Land*, *James u007*
 
 *   Add tests for `lteq`, `lt`, `gteq` and `gt` predicates. They are also
@@ -44,15 +131,15 @@ henceforth should be documented here.
     *Jon Atack*
 
 *   Add tests for unknown attribute names.
-    
+
     *Joe Yates*
 
-*   Add tests for attribute names containing '_or_' and '_and_'.
-    
+*   Add tests for attribute names containing `_or_` and `_and_`.
+
     *Joe Yates*, *Jon Atack*
 
-*   Add tests for attribute names ending with '_start' and '_end'.
-    
+*   Add tests for attribute names ending with `_start` and `_end``.
+
     *Jon Atack*, *Timo Schilling*
 
 *   Add tests for `start`, `not_start`, `end` and `not_end` predicates, with
@@ -164,9 +251,10 @@ henceforth should be documented here.
 *   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
 

data/CONTRIBUTING.md

@@ -1,15 +1,31 @@
+# Contributing to Ransack
+
+Please take a moment to review this document in order to make the contribution
+process easy and effective for everyone involved!
+
 Ransack is an open source project and we encourage contributions.
 
 ## Filing an issue
 
-When filing an issue on the Ransack project, please provide these details:
+A bug is a _demonstrable problem_ that is caused by the code in the repository.
+Good bug reports are extremely helpful! Please do not use the issue tracker for personal support requests.
 
-* A comprehensive list of steps to reproduce the issue, or, _far better_, a failing spec!
-* The version (and branch) of Ransack *and* the versions of Rails and Ruby.
-* Any relevant stack traces ("Full trace" preferred).
+Guidelines for bug reports:
+
+1. **Use the GitHub issue search** — check if the issue has already been
+   reported.
+
+2. **Check if the issue has been fixed** — try to reproduce it using the
+   `master` branch in the repository.
+
+3. **Isolate and report the problem** — ideally create a reduced test
+   case.
+
+When filing an issue, please provide these details:
 
-In 99% of cases, this information is enough to determine the cause and
-solution to the problem that is being described.
+* A comprehensive list of steps to reproduce the issue, or - far better - **a failing spec**.
+* The version (and branch) of Ransack *and* the versions of Rails, Ruby, and your operating system.
+* Any relevant stack traces ("Full trace" preferred).
 
 Any issue that is open for 14 days without actionable information or activity
 will be marked as "stalled" and then closed. Stalled issues can be re-opened
@@ -20,40 +36,56 @@ if the information requested is provided.
 We gladly accept pull requests to fix bugs and, in some circumstances, add new
 features to Ransack.
 
+If you're new to contributing to open source, welcome! It can seem scary, so
+here is a [great blog post to help you get started]
+(http://robots.thoughtbot.com/8-new-steps-for-fixing-other-peoples-code),
+step by step.
+
 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.
+1. Fork the repo, clone it, create a thoughtfully-named branch for your changes,
+   and install the development dependencies by running `bundle install`.
 
-2. Run the tests. We only take pull requests with passing tests, and it's great
-to know that you have a clean slate:
+2. Begin by running the tests. We only take pull requests with passing tests,
+   and it's great to know that you have a clean slate:
 
-        $ bundle install
         $ bundle exec rake spec
 
-3. Add a test for your change. Only refactoring and documentation changes
-require no new tests. If you are adding functionality or fixing a bug, we need
-a test!
+3. Hack away! Please use Ruby features that are compatible down to Ruby 1.9.
+   Since version 1.5, Ransack no longer maintains Ruby 1.8 compatibility.
+
+4. Add tests for your changes. Only refactoring and documentation changes
+   require no new tests. If you are adding functionality or fixing a bug, we
+   need a test!
+
+5. Make the tests pass.
+
+6. Update the Change Log. If you are adding new functionality, document it in
+   the README.
+
+7. Do not change the version number; we will do that on our end.
+
+8. If necessary, rebase your commits into logical chunks, without errors.
 
-4. Make the test pass.
+9. Push the branch up to your fork on Github 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.
 
-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. 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.
+10. If your pull request only contains documentation changes, please remember to
+   add `[skip ci]` to your commit message so the Travis test suite doesn't run
+   needlessly.
 
 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
 day). We may suggest some changes or improvements or alternatives.
 
-Some things that will increase the chance that your pull request is accepted,
-taken straight from the Ruby on Rails guide:
+Some things that will increase the chance that your pull request is accepted:
 
-* Use Rails idioms and helpers.
+* Use idiomatic Ruby and follow the syntax conventions below.
 * Include tests that fail without your code, and pass with it.
 * Update the README, the change log, the wiki documentation... anything that is
   affected by your contribution.
@@ -68,6 +100,7 @@ Syntax:
 * `a = b` and not `a=b`.
 * `a_method { |block| ... }` and not `a_method { | block | ... }` or
 `a_method{|block| ...}`.
-* Follow the conventions you see used in the source already.
+* Prefer simplicity, readability, and maintainability over terseness.
+* Follow the conventions you see used in the code already.
 
 And in case we didn't emphasize it enough: we love tests!

data/Gemfile

@@ -5,35 +5,46 @@ gem 'rake'
 
 rails = ENV['RAILS'] || 'master'
 
-if rails[0,3] == '4.2' || rails == 'master'
-  gem 'arel', github: 'rails/arel', branch: 'master'
+if rails == 'master'
+  gem 'arel', github: 'rails/arel'
 end
 
 gem 'polyamorous', '~> 1.1'
 
+gem 'pry'
+
 # Provide timezone information on Windows
 gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw]
 
 case rails
 when /\// # A path
   gem 'activesupport', path: "#{rails}/activesupport"
-  gem 'activerecord', path: "#{rails}/activerecord"
+  gem 'activerecord', path: "#{rails}/activerecord", require: false
   gem 'actionpack', path: "#{rails}/actionpack"
 when /^v/ # A tagged version
   git 'git://github.com/rails/rails.git', :tag => rails do
     gem 'activesupport'
     gem 'activemodel'
-    gem 'activerecord'
+    gem 'activerecord', require: false
     gem 'actionpack'
   end
 else
   git 'git://github.com/rails/rails.git', :branch => rails do
     gem 'activesupport'
     gem 'activemodel'
-    gem 'activerecord'
+    gem 'activerecord', require: false
     gem 'actionpack'
   end
   if rails == '3-0-stable'
     gem 'mysql2', '< 0.3'
   end
 end
+
+if ENV['DB'] =~ /mongodb/
+  gem 'mongoid', '~> 4.0.0', require: false
+end
+
+# Removed from Ruby 2.2 but needed for testing Rails 3.x.
+group :test do
+  gem 'test-unit', '~> 3.0' if RUBY_VERSION >= '2.2'
+end

data/README.md

@@ -17,16 +17,26 @@ 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)
-search forms against your application's models (demo source code
+search forms for your Ruby on Rails application (demo source code
 [here](https://github.com/activerecord-hackery/ransack_demo)).
 If you're looking for something that simplifies query generation at the model
 or controller layer, you're probably not looking for Ransack (or MetaSearch,
 for that matter). Try [Squeel](https://github.com/activerecord-hackery/squeel)
 instead.
 
+If you're viewing this at
+[github.com/activerecord-hackery/ransack](https://github.com/activerecord-hackery/ransack),
+you're reading the documentation for the master branch with the latest features.
+[View documentation for the last release (1.6.0).](https://github.com/activerecord-hackery/ransack/tree/v.1.6.0)
+
 ## Getting started
 
-Ransack is currently compatible with Rails 3.x, 4.0, 4.1 and 4.2.
+Ransack is compatible with Rails 3 and 4 (including 4.2) on Ruby 1.9 and later.
+We try to keep it functioning with Rails master too, although frequent changes
+in Arel and Active Record make that a moving target. Ransack works
+out-of-the-box with Active Record and features new support for Mongoid 4.0
+(without associations, further details below). If you are on Ruby 1.8, you may
+need to use an earlier version of Ransack like 1.3.0.
 
 In your Gemfile, for the last officially released Ransack gem:
 
@@ -34,7 +44,7 @@ In your Gemfile, for the last officially released Ransack gem:
 gem 'ransack'
 ```
 
-Or, if you would like to use the latest updates:
+Or, if you would like to use the latest updates, use the `master` branch:
 
 ```ruby
 gem 'ransack', github: 'activerecord-hackery/ransack'
@@ -54,6 +64,15 @@ To use one of the branches, for example the `rails-4.1` branch:
 gem 'ransack', github: 'activerecord-hackery/ransack', branch: 'rails-4.1'
 ```
 
+If you are using Rails master, be advised that Ransack master does not yet work
+with the breaking changes in Rails master and Arel master added since December
+2014. The most recent working commits are:
+
+```ruby
+gem 'rails', github: 'rails/rails', ref: '266ff70'
+gem 'arel', github: 'rails/arel', ref: '008445d'
+```
+
 ## Usage
 
 Ransack can be used in one of two modes, simple or advanced.
@@ -77,24 +96,29 @@ 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`.
-  
+  `Ransack#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.
+  result in some. It generates the same SQL as calling `uniq` on the relation.
 
   Please note that for many databases, a sort on an associated table's columns
   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. 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).
+  to work.
+
+  If `distinct: true` or `uniq` is causing invalid SQL, another way to remove
+  duplicates is to call `to_a.uniq` on the collection at the end (see the next
+  section below) -- with the caveat that the de-duping is taking place in Ruby
+  instead of in SQL, which is potentially slower and uses more memory, and that
+  it may display awkwardly with pagination if the number of results is greater
+  than the page size.
 
 ####In your controller
 
 ```ruby
 def index
-  @q = Person.search(params[:q])
+  @q = Person.ransack(params[:q])
   @people = @q.result(distinct: true)
 end
 ```
@@ -103,8 +127,9 @@ this example, with preloading each Person's Articles and pagination):
 
 ```ruby
 def index
-  @q = Person.search(params[:q])
+  @q = Person.ransack(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
@@ -163,6 +188,14 @@ column title or a default sort order:
 <%= sort_link(@q, :name, 'Last Name', default_order: :desc) %>
 ```
 
+With a polymorphic association, you may need to specify the name of the link
+explicitly to avoid an `uninitialized constant Model::Xxxable` error (see issue
+[#421](https://github.com/activerecord-hackery/ransack/issues/421)):
+
+```erb
+<%= sort_link(@q, :xxxable_of_Ymodel_type_some_attribute, 'Attribute Name') %>
+```
+
 You can also sort on multiple fields by specifying an ordered array:
 
 ```erb
@@ -184,6 +217,13 @@ This example toggles the sort directions of both fields, by default
 initially sorting the `last_name` field by ascending order, and the
 `first_name` field by descending order.
 
+The sort link may be displayed without the order indicator arrow by passing
+`hide_indicator: true`:
+
+```erb
+<%= sort_link(@q, :name, hide_indicator: true) %>
+```
+
 ### Advanced Mode
 
 "Advanced" searches (ab)use Rails' nested attributes functionality in order to
@@ -226,12 +266,26 @@ 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:
+that `#search` has already been defined, you can always use the default
+`#ransack` method. For example, the following would be equivalent:
 
 ```ruby
-Article.search(params[:q])
 Article.ransack(params[:q])
+Article.search(params[:q])
+```
+
+Users have reported issues of name conflicts with other gems, so `#search` may
+possibly be deprecated in the next major version of Ransack (2.0).
+
+For now, if Ransack's `#search` method conflicts with the name of another
+method named `search` in your code or another gem, you may resolve it either by
+patching the `extended` class_method in `Ransack::Adapters::ActiveRecord::Base`
+to remove the line `alias :search :ransack unless base.respond_to? :search`, or
+by placing the following line in your Ransack initializer file at
+`config/initializers/ransack.rb`:
+
+```ruby
+Ransack::Adapters::ActiveRecord::Base.class_eval('remove_method :search')
 ```
 
 ### Associations
@@ -267,7 +321,7 @@ end
 ```ruby
 class SupervisorsController < ApplicationController
   def index
-    @q = Supervisor.search(params[:q])
+    @q = Supervisor.ransack(params[:q])
     @supervisors = @q.result.includes(:department, :employees)
   end
 end
@@ -289,7 +343,7 @@ end
   <%= f.submit "search" %>
 <% end %>
 ...
-<%= content_tag :table %>
+<%= content_tag :table do %>
   <%= 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') %>
@@ -318,7 +372,7 @@ class methods in your models to apply selective authorization:
 Here is how these four methods are implemented in Ransack:
 
 ```ruby
-  # Ransackable_attributes, by default, returns all column names
+  # `ransackable_attributes` by default returns all column names
   # and any defined ransackers as an array of strings.
   # For overriding with a whitelist array of strings.
   #
@@ -326,7 +380,7 @@ Here is how these four methods are implemented in Ransack:
     column_names + _ransackers.keys
   end
 
-  # Ransackable_associations, by default, returns the names
+  # `ransackable_associations` by default returns the names
   # of all associations as an array of strings.
   # For overriding with a whitelist array of strings.
   #
@@ -334,7 +388,7 @@ Here is how these four methods are implemented in Ransack:
     reflect_on_all_associations.map { |a| a.name.to_s }
   end
 
-  # Ransortable_attributes, by default, returns the names
+  # `ransortable_attributes` by default returns the names
   # of all attributes available for sorting as an array of strings.
   # For overriding with a whitelist array of strings.
   #
@@ -342,7 +396,7 @@ Here is how these four methods are implemented in Ransack:
     ransackable_attributes(auth_object)
   end
 
-  # Ransackable_scopes, by default, returns an empty array
+  # `ransackable_scopes` by default returns an empty array
   # i.e. no class methods/scopes are authorized.
   # For overriding with a whitelist array of *symbols*.
   #
@@ -376,7 +430,7 @@ class Article < ActiveRecord::Base
       super
     else
       # whitelist only the title and body attributes for other users
-      super & %w(title body) 
+      super & %w(title body)
     end
   end
 end
@@ -388,10 +442,10 @@ Here is example code for the `articles_controller`:
 class ArticlesController < ApplicationController
 
   def index
-    @q = Article.search(params[:q], auth_object: set_ransack_auth_object)
+    @q = Article.ransack(params[:q], auth_object: set_ransack_auth_object)
     @articles = @q.result
   end
-  
+
   private
 
   def set_ransack_auth_object
@@ -404,21 +458,21 @@ Trying it out in `rails console`:
 
 ```ruby
 > Article
-=> Article(id: integer, person_id: integer, title: string, body: text) 
+=> Article(id: integer, person_id: integer, title: string, body: text)
 
 > Article.ransackable_attributes
-=> ["title", "body"] 
+=> ["title", "body"]
 
 > Article.ransackable_attributes(:admin)
-=> ["id", "person_id", "title", "body"] 
+=> ["id", "person_id", "title", "body"]
 
-> Article.search(id_eq: 1).result.to_sql
+> Article.ransack(id_eq: 1).result.to_sql
 => SELECT "articles".* FROM "articles"  # Note that search param was ignored!
 
-> Article.search({ id_eq: 1 }, { auth_object: nil }).result.to_sql
+> Article.ransack({ 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
+> Article.ransack({ id_eq: 1 }, { auth_object: :admin }).result.to_sql
 => SELECT "articles".* FROM "articles"  WHERE "articles"."id" = 1
 ```
 
@@ -456,11 +510,17 @@ class Employee < ActiveRecord::Base
   end
 end
 
-Employee.search({ active: true, hired_since: '2013-01-01' })
+Employee.ransack({ active: true, hired_since: '2013-01-01' })
 
-Employee.search({ salary_gt: 100_000 }, { auth_object: current_user })
+Employee.ransack({ salary_gt: 100_000 }, { auth_object: current_user })
 ```
 
+If the `true` value is being passed via url params or by some other mechanism
+that will convert it to a string (i.e. `active: 'true'` instead of
+`active: true`), the true value will *not* be passed to the scope. If you want
+to pass a `'true'` string to the scope, you should wrap it in an array (i.e.
+`active: ['true']`).
+
 Scopes are a recent addition to Ransack and currently have a few caveats:
 First, a scope involving child associations needs to be defined in the parent
 table model, not in the child model. Second, scopes with an array as an
@@ -469,10 +529,8 @@ wrapped in an array to function (see
 [this issue](https://github.com/activerecord-hackery/ransack/issues/404)),
 which is not compatible with Ransack form helpers. For this use case, it may be
 better for now to use [ransackers]
-(https://github.com/activerecord-hackery/ransack/wiki/Using-Ransackers) instead
-where feasible. Finally, there is also
-[this issue](https://github.com/activerecord-hackery/ransack/issues/403)
-to be aware of. Pull requests with solutions and tests are welcome!
+(https://github.com/activerecord-hackery/ransack/wiki/Using-Ransackers) instead,
+where feasible. Pull requests with solutions and tests are welcome!
 
 ### Grouping queries by OR instead of AND
 
@@ -484,7 +542,7 @@ You can easily try it in your controller code by changing `params[:q]` in the
 
 ```ruby
 def index
-  @q = Artist.search(params[:q].try(:merge, m: 'or'))
+  @q = Artist.ransack(params[:q].try(:merge, m: 'or'))
   @artists = @q.result
 end
 ```
@@ -496,7 +554,7 @@ quickly.
 Alternatively, trying it in the Rails console:
 
 ```ruby
-artists = Artist.search(name_cont: 'foo', style_cont: 'bar', m: 'or')
+artists = Artist.ransack(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"]>
@@ -515,7 +573,7 @@ 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')
+artists = Artist.ransack(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"]>
@@ -591,12 +649,30 @@ en:
         title: Old Ransack Namespaced Title
 ```
 
+## Mongoid
+
+Ransack now works with Mongoid in the same way as Active Record, except that
+with Mongoid, associations are not currently supported. A demo app may be found
+[here](http://ransack-mongodb-demo.herokuapp.com/) and the demo source code is
+[here](https://github.com/Zhomart/ransack-mongodb-demo). A `result` method
+called on a `ransack` search returns a `Mongoid::Criteria` object:
+
+```ruby
+  @q = Person.ransack(params[:q])
+  @people = @q.result # => Mongoid::Criteria
+
+  # or you can add more Mongoid queries
+  @people = @q.result.active.order_by(updated_at: -1).limit(10)
+```
+
 ## Semantic Versioning
 
 Ransack attempts to follow semantic versioning in the format of `x.y.z`, where:
 
 `x` stands for a major version (new features that are not backward-compatible).
+
 `y` stands for a minor version (new features that are backward-compatible).
+
 `z` stands for a patch (bug fixes).
 
 In other words: `Major.Minor.Patch`.