README.md in ruby_simple_search-0.0.3 vs README.md in ruby_simple_search-2.0.0
- old
+ new
@@ -1,115 +1,147 @@
# RubySimpleSearch
-RubySimpleSearch allows you to search on the table fields (string and text fields)
-very easily.
+The simplest way to search the data in ActiveRecord models.
-Mostly on the admin side, we do have a common text field to search the data on the
-table.
+It offers simple but useful features:
-Sometimes we want to do a search on the title, content and ratings on the post model or
-email, username and description on the user model. For those searches we use MySQL's
-or PostgreSQL's LIKE operator to get the results. While doing the same thing again and again
-on the different models you actually add lots of duplication in your code.
+- [Search on the default attributes](#search-on-the-default-attributes)
+- [Override default search attributes to specific attributes ](#override-default-search-attributes-to-specific-attributes) (Credit goes to [@abdullahtariq1171](https://github.com/abdullahtariq1171))
+- [Search using patterns](#search-using-patterns)
+- [Ruby block support to extend the search query](#ruby-block-support-to-extend-the-search-query)
+- [Simple search returns an `ActiveRecord::Relation` object](#simple-search-returns-an-activerecordrelation-object)
-To avoid duplicating the same code, use RubySimpleSearch :)
+Mostly on the admin side, we do have a standard text field to search the data on the table.
+Sometimes we want to search through the attributes like title, content and ratings on the
+post model or email, username and description on the user model. For those searches, we use
+MySQL's or PostgreSQL's `LIKE` operator to get the results. While doing the same thing again
+and again on the different models, you add lots of duplication in your code.
-#### Version 0.0.3 changes:
-- 'LIKE' pattern is more flexible now. Now you can pass pattern on ```simple_search```
- method directly. Pattern support on the ```simple_search_attributes``` method has been removed
-- Fixed column ambiguous error when used with the joins
+#### Do not repeat yourself, use RubySimpleSearch.
+[](https://travis-ci.org/mechanicles/ruby_simple_search)
-#### RubySimpleSearch Features:
-- Added 'LIKE' pattern support ('beginning', 'ending', 'containing', 'underscore', 'plain').
- By default pattern is 'containing'
-
-```Ruby
- Post.simple_search('york', :pattern => :ending)
- # It will search like '%york'
-
- Post.simple_search('york', :pattern => :begining)
- # It will search like 'york%'
-
- Post.simple_search('york', :pattern => :containing)
- # It will search like '%york%'
-
- Post.simple_search('o', :pattern => :underscore)
- # It will search like '_o_'
-
- Post.simple_search('yourk', :pattern => :plain)
- # It will search like 'york'
-```
-- Added **block** support to ```simple_search``` method, so user can extend the query as per
- his/her requirements (Now you can operate on the integer/decimal values also)
-
-- Added specs
-
-- Added exception handler
-
## Installation
Add this line to your application's Gemfile:
gem 'ruby_simple_search'
And then execute:
- $ bundle
+ $ bundle install
Or install it yourself as:
$ gem install ruby_simple_search
## Usage
-Define attributes that you want to search through RubySimpleSearch
+Define attributes that you want to search on it
```Ruby
class Post < ActiveActiveRecord::Base
include RubySimpleSearch
simple_search_attributes :title, :description
end
```
+
```Ruby
class User < ActiveActiveRecord::Base
include RubySimpleSearch
+ simple_search_attributes :email, :username, :address, :age
+end
+```
+
+## Features
+
+### Search on the default attributes
+If you don't provide any attribute at the time of searching, it will use `simple_search_attributes` from the model.
+
+```ruby
+class User < ActiveActiveRecord::Base
+ include RubySimpleSearch
+
simple_search_attributes :email, :username, :address
end
+
+
+Post.simple_search('york')
+# It will search in :email, :username and :address only
```
-While defining ```simple_search_attributes```, don't add integer/decimal data
-attributes to it, instead of this you can do integer/decimal operation
-by passing block to ```simple_search``` method
-```Ruby
-Post.simple_search('tuto', :pattern => :begining)
-# => posts which have 'tuto%' text in the title or in the description fields
+
+### Override default search attributes to specific attributes
+
+If you want to perform a specific search on particular attributes, you can pass specific attributes with `attributes` option.
+
+```ruby
+class User < ActiveActiveRecord::Base
+ include RubySimpleSearch
+
+ simple_search_attributes :email, :username, :address
+end
+
+Post.simple_search('york')
+# It will search in :email, :username and :address only
+
+Post.simple_search('york', attributes: :address)
+# It will search in :address only
+
+User.simple_search('york', pattern: :ending, attributes: [:email, :address])
+# It will search in :email and :address only with 'ending' pattern
```
-```Ruby
-User.simple_search('mechanicles')
-# => users which have 'mechanicles' text in the email, username and in address
+
+### Search using patterns
+You can pass a `LIKE` pattern to the `simple_search` method.
+
+Patterns:
+
+- beginning
+- ending
+- containing (Default pattern)
+- plain
+
+```ruby
+Post.simple_search('york', pattern: :beginning)
+# It will search like 'york%' and finds any values that start with "york"
+
+Post.simple_search('york', pattern: :ending)
+# It will search like '%york' and finds any values that end with "york"
+
+Post.simple_search('york', pattern: :containing)
+# It will search like '%york%' and finds any values that have "york" in any position
+
+Post.simple_search('york', pattern: :plain)
+# It will search like 'york' and finds any values that have "york" word
```
+
+### Ruby block support to extend the search query
+
```Ruby
-User.simple_search('mechanicles') do |search_term|
- ["and address != ?", search_term]
+User.simple_search('35') do |search_term|
+ ["AND age = ?", search_term]
end
-# => You can pass block to simple_search method so you can extend it as your
-# wish but you need to return an array of valid parameters like you do in #where
-# method
```
+Block should return an array of search condition and values.
+
+### Simple search returns an `ActiveRecord::Relation` object
+
```Ruby
-Model.simple_search('string')
-# => with and without block will return ActiveRecord::Relation object
-```
-```Ruby
+Model.simple_search('string') # => ActiveRecord::Relation object
+
Model.simple_search('string').to_sql
-#OR
+
+# OR
+
User.simple_search('mechanicles') do |search_term|
- ["and address != ?", search_term]
+ ["AND address != ?", search_term]
end.to_sql
-# => will return sql query in string format
+
+# => It will return an SQL query in string format
```
+
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)