move "If you're coming from MetaSearch" section to bottom of readme
It's been eight years since Ransack succeeded MetaSearch. As most developers have likely migrated from MetaSearch to Ransack by now, anyone reading the readme is likely starting fresh with Ransack - so it's perhaps less useful to highlight differences from MetaSearch in the readme's introduction. Move the "Updating From MetaSearch" section to the bottom of the readme, and make sure any important details (like setting the default search param) are covered appropriately within the readme.
This commit is contained in:
parent
46de17eba8
commit
f085e8affd
61
README.md
61
README.md
|
@ -41,28 +41,15 @@ gem 'ransack', github: 'activerecord-hackery/ransack'
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Ransack can be used in one of two modes, simple or advanced.
|
Ransack can be used in one of two modes, simple or advanced. For
|
||||||
|
searching/filtering not requiring complex boolean logic, Ransack's simple
|
||||||
|
mode should meet your needs.
|
||||||
|
|
||||||
|
If you're coming from MetaSearch (Ransack's predecessor), refer to the
|
||||||
|
[Updating From MetaSearch](#updating-from-metasearch) section
|
||||||
|
|
||||||
### Simple Mode
|
### Simple Mode
|
||||||
|
|
||||||
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).
|
|
||||||
|
|
||||||
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
|
|
||||||
`Ransack#result`.
|
|
||||||
|
|
||||||
#### In your controller
|
#### In your controller
|
||||||
|
|
||||||
```ruby
|
```ruby
|
||||||
|
@ -84,6 +71,20 @@ def index
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
|
##### Default search parameter
|
||||||
|
|
||||||
|
Ransack uses a default `:q` param key for search params. This may be changed by
|
||||||
|
setting the `search_key` option in a Ransack initializer file (typically
|
||||||
|
`config/initializers/ransack.rb`):
|
||||||
|
|
||||||
|
```
|
||||||
|
Ransack.configure do |c|
|
||||||
|
# Change default search parameter key name.
|
||||||
|
# Default key name is :q
|
||||||
|
c.search_key = :query
|
||||||
|
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`,
|
||||||
|
@ -903,6 +904,28 @@ en:
|
||||||
title: Old Ransack Namespaced Title
|
title: Old Ransack Namespaced Title
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Updating From MetaSearch
|
||||||
|
|
||||||
|
Ransack 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](default-search-parameter) via setting the `search_key` option
|
||||||
|
in your Ransack intitializer file.
|
||||||
|
|
||||||
|
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
|
||||||
|
`Ransack#result`.
|
||||||
|
|
||||||
## Mongoid
|
## Mongoid
|
||||||
|
|
||||||
Mongoid support has been moved to its own gem at [ransack-mongoid](https://github.com/activerecord-hackery/ransack-mongoid).
|
Mongoid support has been moved to its own gem at [ransack-mongoid](https://github.com/activerecord-hackery/ransack-mongoid).
|
||||||
|
|
Loading…
Reference in New Issue