Improve README: Add sort_link examples and a 2nd
controller code example, use f.search_field instead of f.text_field, and clean up code formatting for readability [ci skip]
This commit is contained in:
parent
993ffb1917
commit
65145a426c
111
README.md
111
README.md
|
@ -55,31 +55,33 @@ 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:
|
||||
|
||||
|
@ -89,21 +91,37 @@ def index
|
|||
@people = @q.result(distinct: true)
|
||||
end
|
||||
```
|
||||
or without `distinct:true` for sorting on an associated table's columns (and
|
||||
with preloading each Person's Articles plus pagination in this example:
|
||||
|
||||
```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).
|
||||
|
||||
```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:
|
||||
```erb
|
||||
|
@ -116,13 +134,22 @@ You can also set the `search_form_for` answer format, like this:
|
|||
<% end %>
|
||||
```
|
||||
|
||||
The second main view helper, `sort_link`, is useful for the view table headers:
|
||||
|
||||
```erb
|
||||
<%= content_tag :th, sort_link(@q, :name) %>
|
||||
<%= content_tag :th, sort_link(@q, 'articles.title', 'Title', default_order: :desc) %>
|
||||
<%= content_tag :th, sort_link(@q, 'users.name'), 'User' %>
|
||||
```
|
||||
|
||||
### 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 +183,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])
|
||||
|
@ -221,13 +250,19 @@ end
|
|||
### 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]
|
||||
**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__)
|
||||
|
||||
|
@ -238,14 +273,22 @@ require 'rails/all'
|
|||
|
||||
### 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
|
||||
|
||||
|
|
Loading…
Reference in New Issue