2011-06-07 01:32:03 +00:00
# Ransack
2014-04-24 07:14:51 +00:00
[![Build Status ](https://travis-ci.org/activerecord-hackery/ransack.svg )]
(https://travis-ci.org/activerecord-hackery/ransack)
[![Gem Version ](https://badge.fury.io/rb/ransack.svg )]
(http://badge.fury.io/rb/ransack)
2015-04-05 10:11:02 +00:00
[![Code Climate ](https://codeclimate.com/github/activerecord-hackery/ransack/badges/gpa.svg )]
(https://codeclimate.com/github/activerecord-hackery/ransack)
2014-04-24 07:14:51 +00:00
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 ),
2014-08-29 23:31:39 +00:00
[Jon Atack ](http://twitter.com/jonatack ) and a great group of [contributors]
(https://github.com/activerecord-hackery/ransack/graphs/contributors).
2014-04-24 07:14:51 +00:00
While it supports many of the same features as MetaSearch, its underlying
implementation differs greatly from MetaSearch,
2014-08-17 22:49:55 +00:00
and backwards compatibility is not a design goal.
2014-04-24 07:14:51 +00:00
Ransack enables the creation of both simple and
[advanced ](http://ransack-demo.herokuapp.com/users/advanced_search )
2014-12-12 23:00:50 +00:00
search forms for your Ruby on Rails application (demo source code
2014-04-24 07:14:51 +00:00
[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.
2011-06-07 01:32:03 +00:00
2014-12-17 23:01:21 +00:00
If you're viewing this at
2014-12-17 23:05:07 +00:00
[github.com/activerecord-hackery/ransack ](https://github.com/activerecord-hackery/ransack ),
2014-12-17 23:01:21 +00:00
you're reading the documentation for the master branch with the latest features.
2015-08-20 10:46:41 +00:00
[View documentation for the last release (1.7.0). ](https://github.com/activerecord-hackery/ransack/tree/v1.7.0 )
2014-12-17 23:01:21 +00:00
2011-06-07 01:32:03 +00:00
## Getting started
2015-09-04 19:05:17 +00:00
Ransack is compatible with Rails 3, 4 and 5 on Ruby 1.9 and later.
JRuby 9 ought to work as well (see
2015-07-22 21:41:47 +00:00
[this ](https://github.com/activerecord-hackery/polyamorous/issues/17 )).
If you are using Ruby 1.8 or an earlier JRuby and run into compatibility
issues, you can use an earlier version of Ransack, say, up to 1.3.0.
2015-03-22 16:57:17 +00:00
2015-08-20 08:22:31 +00:00
Ransack works out-of-the-box with Active Record and also features limited
2015-11-16 22:42:40 +00:00
support for Mongoid 4 (without associations, further details
2015-08-20 08:22:31 +00:00
[below ](https://github.com/activerecord-hackery/ransack#mongoid )).
2015-03-22 16:57:17 +00:00
2015-04-05 10:53:20 +00:00
In your Gemfile, for the last officially released gem:
2014-07-24 15:38:27 +00:00
```ruby
gem 'ransack'
```
2014-11-06 22:56:24 +00:00
Or, if you would like to use the latest updates, use the `master` branch:
2011-06-07 01:32:03 +00:00
2013-05-04 05:13:46 +00:00
```ruby
2014-07-25 09:50:47 +00:00
gem 'ransack', github: 'activerecord-hackery/ransack'
2013-05-04 05:13:46 +00:00
```
2012-04-11 18:20:46 +00:00
2015-09-04 19:05:17 +00:00
September 2015 update: If you are using Rails 5 (master) and need pagination
that works with Ransack, there is an
[updated version of the `will_paginate` gem here ](https://github.com/jonatack/will_paginate ).
It is also optimized for Ruby 2.2+. To use it, in your Gemfile:
`gem 'will_paginate', github: 'jonatack/will_paginate'` .
2015-08-20 08:19:58 +00:00
## Issues tracker
* Before filing an issue, please read the [Contributing Guide ](CONTRIBUTING.md ).
* File an issue if a bug is caused by Ransack, is new (has not already been reported), and _can be reproduced from the information you provide_ .
* Contributions are welcome, but please do not add "+1" comments to issues or pull requests :smiley:
2015-11-16 22:20:10 +00:00
* Please do not use the issue tracker for personal support requests. Stack Overflow is a better place for that where a wider community can help you!
2015-08-20 08:19:58 +00:00
2011-06-07 01:32:03 +00:00
## Usage
Ransack can be used in one of two modes, simple or advanced.
### Simple Mode
2014-05-11 15:10:08 +00:00
This mode works much like MetaSearch, for those of you who are familiar with
it, and requires very little setup effort.
2011-06-07 01:32:03 +00:00
If you're coming from MetaSearch, things to note:
2014-05-11 15:10:08 +00:00
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.
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
2015-01-05 18:00:35 +00:00
`Ransack#result` .
2014-11-18 22:48:45 +00:00
2014-05-11 15:39:38 +00:00
####In your controller
2011-06-07 01:32:03 +00:00
2013-05-04 05:13:46 +00:00
```ruby
def index
2015-01-05 18:00:35 +00:00
@q = Person.ransack(params[:q])
2013-08-06 17:47:59 +00:00
@people = @q .result(distinct: true)
2013-05-04 05:13:46 +00:00
end
```
2015-11-16 22:26:52 +00:00
or without `distinct: true` , for sorting on an associated table's columns (in
2014-05-11 15:39:38 +00:00
this example, with preloading each Person's Articles and pagination):
2014-05-11 15:10:08 +00:00
```ruby
def index
2015-01-05 18:00:35 +00:00
@q = Person.ransack(params[:q])
2014-05-11 15:10:08 +00:00
@people = @q .result.includes(:articles).page(params[:page])
2014-12-09 19:52:37 +00:00
2014-12-09 19:37:48 +00:00
# or use `to_a.uniq` to remove duplicates (can also be done in the view):
2014-12-09 19:52:37 +00:00
@people = @q .result.includes(:articles).page(params[:page]).to_a.uniq
2014-05-11 15:10:08 +00:00
end
```
2011-06-07 01:32:03 +00:00
2014-05-11 15:39:38 +00:00
####In your view
2011-06-07 01:32:03 +00:00
2014-05-11 15:10:08 +00:00
The two primary Ransack view helpers are `search_form_for` and `sort_link` ,
2014-08-17 22:36:50 +00:00
which are defined in
[Ransack::Helpers::FormHelper ](lib/ransack/helpers/form_helper.rb ).
2014-05-11 15:10:08 +00:00
2015-04-05 10:11:02 +00:00
####Ransack's `search_form_for` helper replaces `form_for` for creating the view search form
2014-05-11 15:31:09 +00:00
2013-05-04 05:13:46 +00:00
```erb
< %= search_form_for @q do |f| %>
2014-09-05 22:52:05 +00:00
2014-09-05 22:25:32 +00:00
# Search if the name field contains...
2013-05-04 05:13:46 +00:00
< %= f.label :name_cont %>
2014-05-11 15:10:08 +00:00
< %= f.search_field :name_cont %>
2014-09-05 22:52:05 +00:00
2014-09-05 22:25:32 +00:00
# Search if an associated articles.title starts with...
2013-05-04 05:13:46 +00:00
< %= f.label :articles_title_start %>
2014-05-11 15:10:08 +00:00
< %= f.search_field :articles_title_start %>
2014-09-05 22:52:05 +00:00
2014-09-05 22:25:32 +00:00
# Attributes may be chained. Search multiple attributes for one value...
2014-09-05 23:06:01 +00:00
< %= f.label :name_or_description_or_email_or_articles_title_cont %>
2014-09-05 23:10:12 +00:00
< %= f.search_field :name_or_description_or_email_or_articles_title_cont %>
2014-09-05 22:52:05 +00:00
2013-05-04 05:13:46 +00:00
< %= f.submit %>
< % end %>
```
2011-06-07 01:32:03 +00:00
2014-05-11 15:10:08 +00:00
`cont` (contains) and `start` (starts with) are just two of the available
2015-04-05 10:11:02 +00:00
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 )
2014-08-17 22:36:50 +00:00
for more information.
2012-03-29 14:50:36 +00:00
2014-05-11 15:39:38 +00:00
The `search_form_for` answer format can be set like this:
2015-04-05 10:11:02 +00:00
2014-04-21 15:23:50 +00:00
```erb
< %= search_form_for(@q, format: :pdf) do |f| %>
< %= search_form_for(@q, format: :json) do |f| %>
```
2015-04-05 10:11:02 +00:00
####Ransack's `sort_link` helper creates table headers that are sortable links
2014-05-11 15:10:08 +00:00
```erb
2014-10-05 20:58:08 +00:00
< %= sort_link(@q, :name) %>
2014-05-11 15:31:09 +00:00
```
Additional options can be passed after the column attribute, like a different
column title or a default sort order:
```erb
2014-10-05 21:04:40 +00:00
< %= sort_link(@q, :name, 'Last Name', default_order: :desc) %>
2014-05-11 15:10:08 +00:00
```
2014-11-18 22:48:45 +00:00
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') %>
```
2014-10-05 20:58:08 +00:00
You can also sort on multiple fields by specifying an ordered array:
2014-10-04 00:43:53 +00:00
```erb
2014-10-05 21:04:40 +00:00
< %= sort_link(@q, :last_name, [:last_name, 'first_name asc'], 'Last Name') %>
2014-10-04 00:43:53 +00:00
```
2014-10-05 20:58:08 +00:00
In the example above, clicking the link will sort by `last_name` and then
`first_name` . Specifying the sort direction on a field in the array tells
Ransack to _always_ sort that particular field in the specified direction.
Multiple `default_order` fields may also be specified with a hash:
```erb
2014-10-14 20:17:30 +00:00
< %= sort_link(@q, :last_name, %i(last_name first_name),
2014-10-05 21:04:40 +00:00
default_order: { last_name: 'asc', first_name: 'desc' }) %>
2014-10-05 20:58:08 +00:00
```
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.
2014-10-04 00:43:53 +00:00
2014-11-25 22:57:34 +00:00
The sort link may be displayed without the order indicator arrow by passing
`hide_indicator: true` :
2014-11-24 15:48:29 +00:00
```erb
< %= sort_link(@q, :name, hide_indicator: true) %>
```
2015-08-21 17:21:32 +00:00
Alternatively, all sort links may be displayed without the order indicator arrow
by adding this to an initializer file like `config/initializers/ransack.rb` :
```ruby
Ransack.configure do |c|
c.hide_sort_order_indicators = true
end
```
2011-06-07 01:32:03 +00:00
### Advanced Mode
2014-05-11 15:10:08 +00:00
"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. :(
2011-06-07 01:32:03 +00:00
This means you'll need to tweak your routes...
2013-05-04 05:13:46 +00:00
```ruby
resources :people do
collection do
2013-08-06 17:47:59 +00:00
match 'search' => 'people#search', via: [:get, :post], as: :search
2013-05-04 05:13:46 +00:00
end
end
```
2011-06-07 01:32:03 +00:00
... and add another controller action ...
2013-05-04 05:13:46 +00:00
```ruby
def search
index
render :index
end
```
2012-03-29 14:50:36 +00:00
2011-06-07 01:32:03 +00:00
... and update your `search_form_for` line in the view ...
2013-05-04 05:13:46 +00:00
```erb
2013-08-06 17:47:59 +00:00
< %= search_form_for @q , url: search_people_path,
html: { method: :post } do |f| %>
2013-05-04 05:13:46 +00:00
```
2011-06-07 01:32:03 +00:00
2014-04-28 14:49:26 +00:00
Once you've done so, you can make use of the helpers in [Ransack::Helpers::FormBuilder ](lib/ransack/helpers/form_builder.rb ) to
2011-06-11 18:22:41 +00:00
construct much more complex search forms, such as the one on the
2013-12-18 19:45:49 +00:00
[demo page ](http://ransack-demo.heroku.com ) (source code [here ](https://github.com/activerecord-hackery/ransack_demo )).
2011-06-07 01:32:03 +00:00
2014-03-26 15:13:55 +00:00
### Ransack #search method
2015-01-14 12:09:45 +00:00
Ransack will try to to make the class method `#search` available in your
models, but if `#search` has already been defined elsewhere, you can always use
the default `#ransack` class method. So the following are equivalent:
2014-03-26 15:13:55 +00:00
2014-04-12 02:44:42 +00:00
```ruby
2014-03-26 15:13:55 +00:00
Article.ransack(params[:q])
2015-01-05 18:00:35 +00:00
Article.search(params[:q])
2014-03-26 15:13:55 +00:00
```
2015-01-14 12:09:45 +00:00
Users have reported issues of `#search` name conflicts with other gems, so
the `#search` method alias might be deprecated in the next major version of
Ransack (2.0). It's advisable to use the default `#ransack` instead.
2015-01-05 18:00:35 +00:00
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
2014-11-09 22:33:40 +00:00
`config/initializers/ransack.rb` :
```ruby
Ransack::Adapters::ActiveRecord::Base.class_eval('remove_method :search')
```
2014-09-01 21:43:58 +00:00
### Associations
2012-10-06 21:14:47 +00:00
2014-09-01 21:43:58 +00:00
You can easily use Ransack to search for objects in `has_many` and `belongs_to`
associations.
2012-10-06 21:14:47 +00:00
2015-01-14 10:54:00 +00:00
Given these associations...
2012-10-06 21:14:47 +00:00
2013-05-04 05:13:46 +00:00
```ruby
class Employee < ActiveRecord::Base
belongs_to :supervisor
2012-10-06 21:14:47 +00:00
2014-09-05 23:37:37 +00:00
# has attributes first_name:string and last_name:string
2013-05-04 05:13:46 +00:00
end
2012-10-06 21:14:47 +00:00
2013-05-04 05:13:46 +00:00
class Department < ActiveRecord::Base
has_many :supervisors
2012-10-06 21:14:47 +00:00
2013-05-04 05:13:46 +00:00
# has attribute title:string
end
2012-10-06 21:14:47 +00:00
2013-05-04 05:13:46 +00:00
class Supervisor < ActiveRecord::Base
belongs_to :department
has_many :employees
2012-10-06 21:14:47 +00:00
2014-09-05 23:37:37 +00:00
# has attribute last_name:string
2013-05-04 05:13:46 +00:00
end
```
2012-10-06 21:14:47 +00:00
2015-01-14 10:54:00 +00:00
... and a controller...
2012-10-06 21:14:47 +00:00
2013-05-04 05:13:46 +00:00
```ruby
class SupervisorsController < ApplicationController
def index
2015-01-05 18:00:35 +00:00
@q = Supervisor.ransack(params[:q])
2014-09-01 21:43:58 +00:00
@supervisors = @q .result.includes(:department, :employees)
2013-05-04 05:13:46 +00:00
end
end
```
2012-10-06 21:14:47 +00:00
2015-01-14 10:54:00 +00:00
... you might set up your form like this...
2012-10-06 21:14:47 +00:00
2013-05-04 05:13:46 +00:00
```erb
2014-09-01 21:43:58 +00:00
< %= search_form_for @q do |f| %>
2013-05-04 05:13:46 +00:00
< %= f.label :last_name_cont %>
2014-05-11 15:31:09 +00:00
< %= f.search_field :last_name_cont %>
2012-10-06 21:14:47 +00:00
2013-05-04 05:13:46 +00:00
< %= f.label :department_title_cont %>
2014-05-11 15:31:09 +00:00
< %= f.search_field :department_title_cont %>
2012-10-06 21:14:47 +00:00
2014-09-05 23:30:37 +00:00
< %= f.label :employees_first_name_or_employees_last_name_cont %>
< %= f.search_field :employees_first_name_or_employees_last_name_cont %>
2012-10-06 21:14:47 +00:00
2013-05-04 05:13:46 +00:00
< %= f.submit "search" %>
< % end %>
2014-05-11 15:31:09 +00:00
...
2014-12-10 23:16:58 +00:00
< %= content_tag :table do %>
2014-05-11 15:31:09 +00:00
< %= content_tag :th, sort_link(@q, :last_name) %>
2015-08-21 09:54:20 +00:00
< %= content_tag :th, sort_link(@q, :department_title) %>
< %= content_tag :th, sort_link(@q, :employees_last_name) %>
2014-05-11 15:31:09 +00:00
< % end %>
2013-05-04 05:13:46 +00:00
```
2012-10-06 21:14:47 +00:00
2015-08-21 09:54:20 +00:00
If you have trouble sorting on associations, try using an SQL string with the
pluralized table (`'departments.title'`,`'employees.last_name'`) instead of the
symbolized association (`:department_title)`, `:employees_last_name` ).
2015-12-20 01:23:02 +00:00
### Ransack Aliases
You can customize the attribute names for your Ransack searches by using a `ransack_alias` . This is particularly useful for long attribute names that are necessary when querying associations or multiple columns.
```ruby
class Post < ActiveRecord::Base
belongs_to :author
# Abbreviate :author_first_name_or_author_last_name to :author
ransack_alias :author, :author_first_name_or_author_last_name
end
```
Now, rather than using `:author_first_name_or_author_last_name_cont` in your form, you can simply use `:author_cont` . This serves to produce more expressive query parameters in your URLs.
```erb
< %= search_form_for @q do |f| %>
< %= f.label :author_cont %>
< %= f.search_field :author_cont %>
< % end %>
```
2015-01-14 10:54:00 +00:00
2014-05-09 21:28:43 +00:00
### Using Ransackers to add custom search functions via Arel
2014-05-07 22:03:04 +00:00
The main premise behind Ransack is to provide access to
2014-05-11 15:10:08 +00:00
**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]
2014-05-07 22:03:04 +00:00
(https://github.com/activerecord-hackery/ransack/wiki/Using-Ransackers).
Feel free to contribute working `ransacker` code examples to the wiki!
2015-12-05 22:46:54 +00:00
### Problem with DISTINCT selects
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. 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 will
will need to modify the result as needed to allow these queries to work.
For example, you could call joins and includes on the result which has the
effect of adding those tables columns to the select statement, overcoming
the issue, like so:
```ruby
def index
@q = Person.ransack(params[:q])
@people = @q .result(distinct: true)
.includes(:articles)
.joins(:articles)
.page(params[:page])
end
```
If the above doesn't help, you can also use ActiveRecord's `select` query
to explicitly add the columns you need, which brute force's adding the
columns you need that your SQL engine is complaining about, you need to
make sure you give all of the columns you care about, for example:
```ruby
def index
@q = Person.ransack(params[:q])
@people = @q .result(distinct: true)
.select('people.*, articles.name, articles.description')
.page(params[:page])
end
```
A final way of last resort is to call `to_a.uniq` on the collection at the end
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.
For example:
```ruby
def index
@q = Person.ransack(params[:q])
@people = @q .result.includes(:articles).page(params[:page]).to_a.uniq
end
```
2014-08-29 23:48:00 +00:00
### Authorization (whitelisting/blacklisting)
2014-06-22 09:15:10 +00:00
2014-09-13 20:36:54 +00:00
By default, searching and sorting are authorized on any column of your model
and no class methods/scopes are whitelisted.
2014-08-29 23:48:00 +00:00
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
2014-08-29 23:31:39 +00:00
`ransortable_attributes` .
2014-08-29 22:00:03 +00:00
2014-08-29 22:09:47 +00:00
Here is how these four methods are implemented in Ransack:
2014-08-29 22:00:03 +00:00
```ruby
2015-01-13 18:11:52 +00:00
# `ransackable_attributes` by default returns all column names
2014-09-24 16:45:37 +00:00
# and any defined ransackers as an array of strings.
# For overriding with a whitelist array of strings.
#
def ransackable_attributes(auth_object = nil)
column_names + _ransackers.keys
end
2014-08-29 22:00:03 +00:00
2015-01-13 18:11:52 +00:00
# `ransackable_associations` by default returns the names
2014-09-24 16:45:37 +00:00
# of all associations as an array of strings.
2014-09-19 21:14:17 +00:00
# For overriding with a whitelist array of strings.
2014-09-24 16:45:37 +00:00
#
def ransackable_associations(auth_object = nil)
reflect_on_all_associations.map { |a| a.name.to_s }
end
2014-08-29 22:09:47 +00:00
2015-01-13 18:11:52 +00:00
# `ransortable_attributes` by default returns the names
2014-09-24 16:45:37 +00:00
# of all attributes available for sorting as an array of strings.
# For overriding with a whitelist array of strings.
#
def ransortable_attributes(auth_object = nil)
ransackable_attributes(auth_object)
end
2014-09-13 20:36:54 +00:00
2015-01-13 18:11:52 +00:00
# `ransackable_scopes` by default returns an empty array
2014-09-24 16:45:37 +00:00
# i.e. no class methods/scopes are authorized.
# For overriding with a whitelist array of *symbols* .
#
def ransackable_scopes(auth_object = nil)
[]
end
2014-08-29 22:00:03 +00:00
```
2014-09-13 20:36:54 +00:00
Any values not returned from these methods will be ignored by Ransack, i.e.
they are not authorized.
2014-08-29 23:31:39 +00:00
2014-08-29 22:09:47 +00:00
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
2014-08-29 23:48:00 +00:00
for an `auth_object` key in the options hash which can be used by your own
2014-08-29 22:32:29 +00:00
overridden methods.
2014-08-31 12:42:07 +00:00
Here is an example that puts all this together, adapted from
2014-08-29 23:48:00 +00:00
[this blog post by Ernie Miller]
(http://erniemiller.org/2012/05/11/why-your-ruby-class-macros-might-suck-mine-did/).
2014-08-31 12:42:07 +00:00
In an `Article` model, add the following `ransackable_attributes` class method
(preferably private):
2014-09-24 16:45:37 +00:00
2014-08-29 22:00:03 +00:00
```ruby
2014-08-31 12:42:07 +00:00
class Article < ActiveRecord::Base
private
2014-08-29 22:00:03 +00:00
def self.ransackable_attributes(auth_object = nil)
2014-08-31 12:42:07 +00:00
if auth_object == :admin
2014-08-29 22:44:15 +00:00
# whitelist all attributes for admin
2014-08-29 22:00:03 +00:00
super
else
2014-08-29 22:32:29 +00:00
# whitelist only the title and body attributes for other users
2014-11-18 22:48:45 +00:00
super & %w(title body)
2014-08-29 22:00:03 +00:00
end
end
end
```
2014-09-24 16:45:37 +00:00
2014-08-31 12:42:07 +00:00
Here is example code for the `articles_controller` :
2014-09-24 16:45:37 +00:00
2014-08-31 12:42:07 +00:00
```ruby
class ArticlesController < ApplicationController
def index
2015-01-05 18:00:35 +00:00
@q = Article.ransack(params[:q], auth_object: set_ransack_auth_object)
2014-08-31 12:42:07 +00:00
@articles = @q .result
end
2014-11-18 22:48:45 +00:00
2014-08-31 12:42:07 +00:00
private
def set_ransack_auth_object
current_user.admin? ? :admin : nil
end
end
2014-08-29 22:00:03 +00:00
```
2014-09-24 16:45:37 +00:00
2014-08-31 12:42:07 +00:00
Trying it out in `rails console` :
2014-09-24 16:45:37 +00:00
2014-08-31 12:42:07 +00:00
```ruby
2014-08-29 22:00:03 +00:00
> Article
2014-11-18 22:48:45 +00:00
=> Article(id: integer, person_id: integer, title: string, body: text)
2014-08-29 22:00:03 +00:00
> Article.ransackable_attributes
2014-11-18 22:48:45 +00:00
=> ["title", "body"]
2014-08-29 22:00:03 +00:00
2014-08-31 12:42:07 +00:00
> Article.ransackable_attributes(:admin)
2014-11-18 22:48:45 +00:00
=> ["id", "person_id", "title", "body"]
2014-08-29 22:00:03 +00:00
2015-01-05 18:00:35 +00:00
> Article.ransack(id_eq: 1).result.to_sql
2014-08-29 22:00:03 +00:00
=> SELECT "articles".* FROM "articles" # Note that search param was ignored!
2015-01-05 18:00:35 +00:00
> Article.ransack({ id_eq: 1 }, { auth_object: nil }).result.to_sql
2014-09-02 09:28:17 +00:00
=> SELECT "articles".* FROM "articles" # Search param still ignored!
2015-01-05 18:00:35 +00:00
> Article.ransack({ id_eq: 1 }, { auth_object: :admin }).result.to_sql
2014-08-29 22:00:03 +00:00
=> SELECT "articles".* FROM "articles" WHERE "articles"."id" = 1
```
2014-09-24 16:45:37 +00:00
2014-08-29 23:48:00 +00:00
That's it! Now you know how to whitelist/blacklist various elements in Ransack.
2014-08-29 22:00:03 +00:00
2014-09-10 22:18:43 +00:00
### Using Scopes/Class Methods
2014-06-22 09:15:10 +00:00
2014-09-10 22:18:43 +00:00
Continuing on from the preceding section, searching by scopes requires defining
2014-09-19 21:22:40 +00:00
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:
2014-06-22 09:15:10 +00:00
2014-08-29 23:31:39 +00:00
```ruby
2014-09-10 21:59:12 +00:00
class Employee < ActiveRecord::Base
2015-11-16 22:16:51 +00:00
scope :activated, ->(boolean = true) { where(active: boolean) }
2014-09-10 22:46:25 +00:00
scope :salary_gt, ->(amount) { where('salary > ?', amount) }
2014-09-10 21:59:12 +00:00
2014-09-10 22:46:25 +00:00
# Scopes are just syntactical sugar for class methods, which may also be used:
2014-09-10 21:59:12 +00:00
2014-09-10 22:46:25 +00:00
def self.hired_since(date)
where('start_date >= ?', date)
2014-09-10 21:59:12 +00:00
end
private
2014-09-10 22:18:43 +00:00
def self.ransackable_scopes(auth_object = nil)
if auth_object.try(:admin?)
2014-09-11 17:02:12 +00:00
# allow admin users access to all three methods
2015-11-16 22:16:51 +00:00
%i(activated hired_since salary_gt)
2014-09-10 22:18:43 +00:00
else
2015-11-16 22:16:51 +00:00
# allow other users to search on `activated` and `hired_since` only
%i(activated hired_since)
2014-09-10 21:59:12 +00:00
end
2014-09-10 22:18:43 +00:00
end
2014-09-11 17:02:12 +00:00
end
2014-09-10 21:59:12 +00:00
2015-11-16 22:16:51 +00:00
Employee.ransack({ activated: true, hired_since: '2013-01-01' })
2014-08-29 23:31:39 +00:00
2015-01-05 18:00:35 +00:00
Employee.ransack({ salary_gt: 100_000 }, { auth_object: current_user })
2014-06-22 09:15:10 +00:00
```
2015-11-16 22:42:40 +00:00
In Rails 3 and 4, if the `true` value is being passed via url params or some
other mechanism that will convert it to a string, the true value may not be
passed to the ransackable scope unless you wrap it in an array
(i.e. `activated: ['true']` ). This is currently resolved in Rails 5 :smiley:
2014-10-30 17:24:43 +00:00
2014-10-03 17:06:57 +00:00
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
argument are not easily usable yet, because the array currently needs to be
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]
2014-11-02 00:10:34 +00:00
(https://github.com/activerecord-hackery/ransack/wiki/Using-Ransackers) instead,
2014-10-30 17:24:43 +00:00
where feasible. Pull requests with solutions and tests are welcome!
2014-10-01 22:05:15 +00:00
2014-09-05 23:18:03 +00:00
### Grouping queries by OR instead of AND
The default `AND` grouping can be changed to `OR` by adding `m: 'or'` to the
2014-09-05 23:30:37 +00:00
query hash.
2014-09-07 21:29:41 +00:00
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:
2014-09-07 21:18:07 +00:00
```ruby
def index
2015-01-05 18:00:35 +00:00
@q = Artist.ransack(params[:q].try(:merge, m: 'or'))
2014-09-07 21:18:07 +00:00
@artists = @q .result
end
```
2014-09-07 21:29:41 +00:00
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.
2014-09-07 21:18:07 +00:00
Alternatively, trying it in the Rails console:
2014-09-05 23:18:03 +00:00
```ruby
2015-01-05 18:00:35 +00:00
artists = Artist.ransack(name_cont: 'foo', style_cont: 'bar', m: 'or')
2014-09-05 23:18:03 +00:00
=> 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%'))"
```
2014-09-07 21:05:06 +00:00
The combinator becomes `or` instead of the default `and` , and the SQL query
becomes `WHERE...OR` instead of `WHERE...AND` .
2014-09-05 23:18:03 +00:00
This works with associations as well. Imagine an Artist model that has many
Memberships, and many Musicians through Memberships:
```ruby
2015-01-05 18:00:35 +00:00
artists = Artist.ransack(name_cont: 'foo', musicians_email_cont: 'bar', m: 'or')
2014-09-05 23:18:03 +00:00
=> 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
2014-10-22 21:53:26 +00:00
If you would like to combine the Ransack and SimpleForm form builders, set the
`RANSACK_FORM_BUILDER` environment variable before Rails boots up, e.g. in
`config/application.rb` before `require 'rails/all'` as shown below (and add
2014-10-23 21:09:35 +00:00
`gem 'simple_form'` in your Gemfile).
2014-09-05 23:18:03 +00:00
```ruby
require File.expand_path('../boot', __FILE__ )
ENV['RANSACK_FORM_BUILDER'] = '::SimpleForm::FormBuilder'
require 'rails/all'
```
2014-05-09 21:28:43 +00:00
### I18n
2013-10-07 11:47:52 +00:00
2014-05-11 15:10:08 +00:00
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.
2012-10-06 21:14:47 +00:00
2014-10-22 21:41:58 +00:00
Predicate and attribute translations in forms may be specified as follows (see
2014-10-22 21:53:26 +00:00
the translation files in [Ransack::Locale ](lib/ransack/locale ) for more examples):
2014-10-22 21:41:58 +00:00
2014-10-22 21:53:26 +00:00
locales/en.yml:
2014-10-22 21:41:58 +00:00
```yml
en:
ransack:
asc: ascending
desc: descending
predicates:
cont: contains
not_cont: not contains
start: starts with
end: ends with
gt: greater than
lt: less than
2015-02-18 16:26:13 +00:00
models:
person: Passanger
2014-10-22 21:41:58 +00:00
attributes:
person:
name: Full Name
article:
title: Article Title
body: Main Content
```
Attribute names may also be changed globally, or under `activerecord` :
```yml
en:
attributes:
model_name:
model_field1: field name1
model_field2: field name2
activerecord:
attributes:
namespace/article:
title: AR Namespaced Title
namespace_article:
title: Old Ransack Namespaced Title
```
2014-11-04 20:18:57 +00:00
## Mongoid
2014-11-04 00:45:12 +00:00
2014-11-04 20:25:57 +00:00
Ransack now works with Mongoid in the same way as Active Record, except that
2014-11-04 20:18:57 +00:00
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
2014-11-04 20:25:57 +00:00
[here ](https://github.com/Zhomart/ransack-mongodb-demo ). A `result` method
2015-01-05 18:00:35 +00:00
called on a `ransack` search returns a `Mongoid::Criteria` object:
2014-11-04 00:45:12 +00:00
```ruby
2015-01-05 18:00:35 +00:00
@q = Person.ransack(params[:q])
2014-11-04 20:18:57 +00:00
@people = @q .result # => Mongoid::Criteria
2014-11-04 00:45:12 +00:00
2014-11-04 20:18:57 +00:00
# or you can add more Mongoid queries
@people = @q .result.active.order_by(updated_at: -1).limit(10)
2014-11-04 00:45:12 +00:00
```
2015-08-19 12:36:17 +00:00
_NOTE: Ransack currently works with either Active Record or Mongoid, but not
both in the same application. If both are present, Ransack will default to
Active Record only. Here is the code containing the logic:_
```ruby
@current_adapters ||= {
:active_record => defined?(::ActiveRecord::Base),
:mongoid => defined?(::Mongoid) & & !defined?(::ActiveRecord::Base)
}
```
2015-08-19 08:46:18 +00:00
2014-10-26 22:21:01 +00:00
## Semantic Versioning
Ransack attempts to follow semantic versioning in the format of `x.y.z` , where:
2014-10-26 22:25:16 +00:00
`x` stands for a major version (new features that are not backward-compatible).
2014-11-04 20:25:57 +00:00
2014-10-26 22:25:16 +00:00
`y` stands for a minor version (new features that are backward-compatible).
2014-11-04 20:25:57 +00:00
2014-10-26 22:25:16 +00:00
`z` stands for a patch (bug fixes).
2014-10-26 22:21:01 +00:00
2014-10-26 22:25:16 +00:00
In other words: `Major.Minor.Patch` .
2014-10-26 22:21:01 +00:00
2011-06-07 01:32:03 +00:00
## Contributions
2012-03-29 14:50:36 +00:00
To support the project:
2011-06-07 01:32:03 +00:00
2014-05-11 15:10:08 +00:00
* Use Ransack in your apps, and let us know if you encounter anything that's
2014-10-14 20:17:30 +00:00
broken or missing. A failing spec to demonstrate the issue is awesome. A pull
request with passing tests is even better!
* Before filing an issue or pull request, be sure to read and follow the
[Contributing Guide ](CONTRIBUTING.md ).
* Please use Stack Overflow or other sites for questions or discussion not
directly related to bug reports, pull requests, or documentation improvements.
2014-05-11 15:10:08 +00:00
* 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!
2011-06-07 01:32:03 +00:00
## Copyright
2015-03-29 07:03:05 +00:00
Copyright © 2011-2015 [Ernie Miller ](http://twitter.com/erniemiller )