kotovalexarian-likes-github
/
activerecord-hackery--ransack
mirror of https://github.com/activerecord-hackery/ransack.git
1
0
Fork 0
Code Releases Activity

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:
Jon Atack 2014-05-11 17:10:08 +02:00
parent 993ffb1917
commit 65145a426c
1 changed files with 77 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
README.md
View File

@ -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