Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kanety/findout
https://github.com/kanety/findout
Last synced: 8 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/kanety/findout
- Owner: kanety
- License: mit
- Created: 2019-08-03T12:05:34.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2019-08-24T07:18:41.000Z (over 5 years ago)
- Last Synced: 2024-12-25T04:04:42.902Z (23 days ago)
- Language: Ruby
- Size: 22.5 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Findout
A finder base converting query parameters to ActiveRecord relation via Arel.
## Dependencies
* ruby 2.5+
* activerecord 5.2+
* activesupport 5.2+
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'findout'
```
Then execute:
$ bundle
## Usage
Prepare your models:
```ruby
class User < ApplicationRecord
belongs_to :group
end
class Group < ApplicationRecord
has_many :users
end
```
Make your finder using `Findout::Base`:
```ruby
class ApplicationFinder
include Findout::Base
end
class UsersFinder < ApplicationFinder
end
```
Use finder as follows:
```ruby
params = {
# query parameters
:q => {
:id => { :gteq => 1, :lteq => 10 },
:name => { :eq => 'NAME' }
},
# sort parameters
:s => [
{ :name => :asc },
{ :id => :desc }
]
}
UsersFinder.search(params)
# SELECT "users".* FROM "users"
# WHERE "users"."id" >= 1 AND "users"."id" <= 10 AND "users"."name" = 'NAME'
# ORDER BY "users"."name" ASC, "users"."id" DESC
```
### Operators
This gem supports Arel operators like followings:
* eq, not_eq, eq_any, eq_all, not_eq_any, not_eq_all
* lt, lteq, lt_any, lt_all, lteq_any, lteq_all
* gt, gteq, gt_any, gt_all, gteq_any, gteq_all
* in, not_in, in_any, in_all, not_in_any, not_in_all
* between, not_between
* matches, does_not_match, matches_any, matches_all, does_not_match_any, does_not_match_all
* asc, desc
`eq` is used as a default operator if you ommit it.
This gem also supports following operators for convenience:
* word_any: matches to column which contains ANY words in the text.
* word_all: matches to column which contains ALL words in the text.
### Shorthand
Shorthand is supported to handle parameters more easy.
Shorthand notation is defined as attribute name and operator concatenated with `_`.
For example:
```ruby
UsersFinder.search(:q => {
'id_gteq' => 1, 'id_lteq' => 10
})
# SELECT "users".* FROM "users" WHERE "users"."id" >= 1 AND "users"."id" <= 10
```
The shorthand is converted to hash and merged each other internally.
You should be careful about the value of hash is not overwritten by another value.
### Association
You can use association names defined by `belongs_to`, `has_many` and so on.
Association notation is defined as association name and column name concatenated with `.`.
For example:
```ruby
# association
UsersFinder.search(:q => {
"group.id" => { :gteq => 1, :lteq => 10 }
})
# SELECT "users".* FROM "users"
# INNER JOIN "groups" ON "groups"."id" = "users"."group_id"
# WHERE "groups"."id" >= 1 AND "groups"."id" <= 10
# nested association
UsersFinder.search(:q => {
"group.users.id" => { :gteq => 1, :lteq => 10 }
})
# SELECT "users".* FROM "users"
# INNER JOIN "groups" ON "groups"."id" = "users"."group_id"
# INNER JOIN "users" "users_groups" ON "users_groups"."group_id" = "groups"."id"
# WHERE "users"."id" >= 1 AND "users"."id" <= 10
```
### Alternate parameters
You can alter parameters in the finder class to replace complex conditions with simple parameters.
For example:
```ruby
class UsersFinder < ApplicationFinder
alter :keyword, [:name, :title].map { |attr| "or_#{attr}_word_all" }
end
UsersFinder.search(:q => {
:keyword => 'aa bb'
})
# SELECT "users".* FROM "users"
# WHERE (("users"."name" ILIKE '%aa%' AND "users"."name" ILIKE '%bb%') OR
# ("users"."title" ILIKE '%aa%' AND "users"."title" ILIKE '%bb%'))
```
### Chain relations
You can chain ActiveRecord relations to build complex sql.
For example:
```ruby
class UsersFinder < ApplicationFinder
chain :name_and_title, :search_name_and_title
def search_name_and_title(value)
if value.present?
model.where(name: value[:name], title: value[:title])
end
end
end
UsersFinder.search(:q => {
:name_and_title => { name: 'aa', title: 'bb' }
})
# SELECT "users".* FROM "users" WHERE "users"."name" = 'aa' AND "users"."title" = 'bb'
```
### Sort helper
This gem adds a helper method in the view for building sort link.
For example:
```ruby
<%= findout_sort_link 'ID', { id: :asc } %>
<% @users.each do |user| %>
<%= user.id %>
<% end %>
```
If you clicks the link generated by `findout_sort_link`,
the sort direction is replaced with `desc` automatically.
It also appends html class to the link. Default classes are `sort-asc` and `sort-desc`.
### Configurations
Put the following code into `config/initializers`:
```ruby
Findout::Config.configure do |config|
# query key mapping
config.query_key = { where: :q, order: :s }
# separator for association
config.association_separator = '.'
# sort class mapping
config.sort_class = { asc: 'sort-asc', desc: 'sort-desc' }
end
```
## Contributing
Bug reports and pull requests are welcome at https://github.com/kanety/findout.
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).