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

[skip ci] Improve docs

This commit is contained in:
Richard Li 2017-04-04 13:00:19 +08:00
parent 8ca8c95c65
commit d2c015d469
1 changed files with 11 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
README.md
View File

@ -7,14 +7,12 @@
[![Code Climate](https://codeclimate.com/github/activerecord-hackery/ransack/badges/gpa.svg)] [![Code Climate](https://codeclimate.com/github/activerecord-hackery/ransack/badges/gpa.svg)]
(https://codeclimate.com/github/activerecord-hackery/ransack) (https://codeclimate.com/github/activerecord-hackery/ransack)
Ransack is a rewrite of [MetaSearch] Ransack is a rewrite of [MetaSearch](https://github.com/activerecord-hackery/meta_search)
(https://github.com/activerecord-hackery/meta_search)
created by [Ernie Miller](http://twitter.com/erniemiller) created by [Ernie Miller](http://twitter.com/erniemiller)
and developed/maintained for years by and developed/maintained for years by
[Jon Atack](http://twitter.com/jonatack) and [Jon Atack](http://twitter.com/jonatack) and
[Ryan Bigg](http://twitter.com/ryanbigg) with the help of a great group of [Ryan Bigg](http://twitter.com/ryanbigg) with the help of a great group of
[contributors] [contributors](https://github.com/activerecord-hackery/ransack/graphs/contributors).
(https://github.com/activerecord-hackery/ransack/graphs/contributors).
While it supports many of the same features as MetaSearch, its underlying While it supports many of the same features as MetaSearch, its underlying
implementation differs greatly from MetaSearch, implementation differs greatly from MetaSearch,
and backwards compatibility is not a design goal. and backwards compatibility is not a design goal.
@ -80,8 +78,7 @@ If you're coming from MetaSearch, things to note:
1. The default param key for search params is now `:q`, instead of `:search`. 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) 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 will still run afoul of URL length limits in most browsers and require a
switch to HTTP POST requests. This key is [configurable] switch to HTTP POST requests. This key is [configurable](https://github.com/activerecord-hackery/ransack/wiki/Configuration).
(https://github.com/activerecord-hackery/ransack/wiki/Configuration).
2. `form_for` is now `search_form_for`, and validates that a Ransack::Search 2. `form_for` is now `search_form_for`, and validates that a Ransack::Search
object is passed to it. object is passed to it.
@ -91,7 +88,7 @@ If you're coming from MetaSearch, things to note:
ActiveRecord::Relation in the case of the ActiveRecord adapter) via a call to ActiveRecord::Relation in the case of the ActiveRecord adapter) via a call to
`Ransack#result`. `Ransack#result`.
####In your controller #### In your controller
```ruby ```ruby
def index def index
@ -112,13 +109,13 @@ def index
end end
``` ```
####In your view #### In your view
The two primary Ransack view helpers are `search_form_for` and `sort_link`, The two primary Ransack view helpers are `search_form_for` and `sort_link`,
which are defined in which are defined in
[Ransack::Helpers::FormHelper](lib/ransack/helpers/form_helper.rb). [Ransack::Helpers::FormHelper](lib/ransack/helpers/form_helper.rb).
####Ransack's `search_form_for` helper replaces `form_for` for creating the view search form #### Ransack's `search_form_for` helper replaces `form_for` for creating the view search form
```erb ```erb
<%= search_form_for @q do |f| %> <%= search_form_for @q do |f| %>
@ -154,7 +151,7 @@ The `search_form_for` answer format can be set like this:
<%= search_form_for(@q, format: :json) do |f| %> <%= search_form_for(@q, format: :json) do |f| %>
``` ```
####Ransack's `sort_link` helper creates table headers that are sortable links #### Ransack's `sort_link` helper creates table headers that are sortable links
```erb ```erb
<%= sort_link(@q, :name) %> <%= sort_link(@q, :name) %>
@ -234,7 +231,7 @@ the order indicator arrow by passing `hide_indicator: true` in the sort link:
<%= sort_link(@q, :name, hide_indicator: true) %> <%= sort_link(@q, :name, hide_indicator: true) %>
``` ```
####Ransack's `sort_url` helper is like a `sort_link` but returns only the url #### Ransack's `sort_url` helper is like a `sort_link` but returns only the url
`sort_url` has the same API as `sort_link`: `sort_url` has the same API as `sort_link`:
@ -443,8 +440,7 @@ List of all possible predicates
The main premise behind Ransack is to provide access to The main premise behind Ransack is to provide access to
**Arel predicate methods**. Ransack provides special methods, called **Arel predicate methods**. Ransack provides special methods, called
_ransackers_, for creating additional search functions via Arel. More _ransackers_, for creating additional search functions via Arel. More
information about `ransacker` methods can be found [here in the wiki] information about `ransacker` methods can be found [here in the wiki](https://github.com/activerecord-hackery/ransack/wiki/Using-Ransackers).
(https://github.com/activerecord-hackery/ransack/wiki/Using-Ransackers).
Feel free to contribute working `ransacker` code examples to the wiki! Feel free to contribute working `ransacker` code examples to the wiki!
### Problem with DISTINCT selects ### Problem with DISTINCT selects
@ -554,8 +550,7 @@ for an `auth_object` key in the options hash which can be used by your own
overridden methods. overridden methods.
Here is an example that puts all this together, adapted from Here is an example that puts all this together, adapted from
[this blog post by Ernie Miller] [this blog post by Ernie Miller](http://erniemiller.org/2012/05/11/why-your-ruby-class-macros-might-suck-mine-did/).
(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 In an `Article` model, add the following `ransackable_attributes` class method
(preferably private): (preferably private):
@ -679,8 +674,7 @@ argument are not easily usable yet, because the array currently needs to be
wrapped in an array to function (see wrapped in an array to function (see
[this issue](https://github.com/activerecord-hackery/ransack/issues/404)), [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 which is not compatible with Ransack form helpers. For this use case, it may be
better for now to use [ransackers] better for now to use [ransackers](https://github.com/activerecord-hackery/ransack/wiki/Using-Ransackers) instead,
(https://github.com/activerecord-hackery/ransack/wiki/Using-Ransackers) instead,
where feasible. Pull requests with solutions and tests are welcome! where feasible. Pull requests with solutions and tests are welcome!
### Grouping queries by OR instead of AND ### Grouping queries by OR instead of AND