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:
Aaron Lipman 2020-12-13 12:02:57 -05:00
parent 46de17eba8
commit f085e8affd
No known key found for this signature in database
GPG Key ID: 247BF5E0C15C6050
1 changed files with 42 additions and 19 deletions

View File

@ -41,28 +41,15 @@ gem 'ransack', github: 'activerecord-hackery/ransack'
## 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
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
```ruby
@ -84,6 +71,20 @@ def index
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
The two primary Ransack view helpers are `search_form_for` and `sort_link`,
@ -903,6 +904,28 @@ en:
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 support has been moved to its own gem at [ransack-mongoid](https://github.com/activerecord-hackery/ransack-mongoid).