README: Begin improving ransackable explanations
[skip ci]
This commit is contained in:
parent
28433f9707
commit
db32b0fadb
90
README.md
90
README.md
|
@ -297,16 +297,98 @@ require 'rails/all'
|
||||||
|
|
||||||
### Authorization
|
### Authorization
|
||||||
|
|
||||||
By default, Ransack exposes search on any model column, so make sure you
|
def ransackable_attributes(auth_object = nil)
|
||||||
sanitize your params and only pass the allowed keys. Alternately, you can
|
column_names + _ransackers.keys
|
||||||
define these class methods on your models to apply selective authorization
|
end
|
||||||
based on a given auth object:
|
|
||||||
|
def ransortable_attributes(auth_object = nil)
|
||||||
|
# Here so users can overwrite the attributes
|
||||||
|
# that show up in the sort_select
|
||||||
|
ransackable_attributes(auth_object)
|
||||||
|
end
|
||||||
|
|
||||||
|
def ransackable_associations(auth_object = nil)
|
||||||
|
reflect_on_all_associations.map { |a| a.name.to_s }
|
||||||
|
end
|
||||||
|
|
||||||
|
# For overriding with a whitelist of symbols
|
||||||
|
def ransackable_scopes(auth_object = nil)
|
||||||
|
[]
|
||||||
|
end
|
||||||
|
|
||||||
|
|
||||||
|
### Authorization
|
||||||
|
|
||||||
|
Ransack adds four methods that allow customizing authorization:
|
||||||
|
|
||||||
* `def self.ransackable_attributes(auth_object = nil)`
|
* `def self.ransackable_attributes(auth_object = nil)`
|
||||||
* `def self.ransackable_associations(auth_object = nil)`
|
* `def self.ransackable_associations(auth_object = nil)`
|
||||||
* `def self.ransackable_scopes(auth_object = nil)`
|
* `def self.ransackable_scopes(auth_object = nil)`
|
||||||
* `def self.ransortable_attributes(auth_object = nil)` (for sorting)
|
* `def self.ransortable_attributes(auth_object = nil)` (for sorting)
|
||||||
|
|
||||||
|
By default, Ransack exposes search on any model column, so it is a good idea to
|
||||||
|
sanitize your params and only pass the allowed keys. However, you can
|
||||||
|
define these four class methods on your models to apply selective authorization
|
||||||
|
filters or search scopes.
|
||||||
|
|
||||||
|
Here is how they are implemented in Ransack:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
def ransackable_attributes(auth_object = nil)
|
||||||
|
# Returns the string names of all columns and any defined ransackers.
|
||||||
|
column_names + _ransackers.keys
|
||||||
|
end
|
||||||
|
|
||||||
|
def ransackable_associations(auth_object = nil)
|
||||||
|
# Returns the names of all associations.
|
||||||
|
reflect_on_all_associations.map { |a| a.name.to_s }
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
def ransortable_attributes(auth_object = nil)
|
||||||
|
# Here so users can overwrite the attributes that show up in the sort_select.
|
||||||
|
ransackable_attributes(auth_object)
|
||||||
|
end
|
||||||
|
|
||||||
|
def ransackable_scopes(auth_object = nil)
|
||||||
|
# For overriding with a whitelist of symbols.
|
||||||
|
[]
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
All four methods can receive an optional parameter, `auth_object`. When you
|
||||||
|
call the search or ransack method on your model, you can provide a value for an
|
||||||
|
`:auth_object` key in the options hash, which can be used in your own
|
||||||
|
overridden methods. Putting this all together, you get the following example:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
class Article
|
||||||
|
def self.ransackable_attributes(auth_object = nil)
|
||||||
|
if auth_object == 'admin'
|
||||||
|
super
|
||||||
|
else
|
||||||
|
super & ['title', 'body']
|
||||||
|
end
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
```
|
||||||
|
> Article
|
||||||
|
=> Article(id: integer, person_id: integer, title: string, body: text)
|
||||||
|
|
||||||
|
> Article.ransackable_attributes
|
||||||
|
=> ["title", "body"]
|
||||||
|
|
||||||
|
> Article.ransackable_attributes('admin')
|
||||||
|
=> ["id", "person_id", "title", "body"]
|
||||||
|
|
||||||
|
> Article.search(id_eq: 1).result.to_sql
|
||||||
|
=> SELECT "articles".* FROM "articles" # Note that search param was ignored!
|
||||||
|
|
||||||
|
> Article.search({id_eq: 1}, auth_object: 'admin').result.to_sql
|
||||||
|
=> SELECT "articles".* FROM "articles" WHERE "articles"."id" = 1
|
||||||
|
```
|
||||||
|
|
||||||
Any values not included in the arrays returned from these methods will be
|
Any values not included in the arrays returned from these methods will be
|
||||||
ignored. The auth object should be optional when building the search, and is
|
ignored. The auth object should be optional when building the search, and is
|
||||||
ignored by default:
|
ignored by default:
|
||||||
|
|
Loading…
Reference in New Issue