acts_as_explorable 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cf09cef7bef8fb847eceda7eb6ab0ffe5a3d9d72
-  data.tar.gz: a7b61b25db90271f6787c8e3140ca097500f5445
+  metadata.gz: ca6b20cded2582f1fa6dca8e87fd30615b9c4512
+  data.tar.gz: dd8e130814dc5e150a70078f183768cde2283e9e
 SHA512:
-  metadata.gz: 3856e51cda905223c8d4c3d35456d7db75d69573bf810c0d61f911f0432e3069f24ea53c1bb749690d8ad58e4750755d63a46f0c7592fabf258b5f650698d16b
-  data.tar.gz: 8f2fec4eb042b5a9f48aa665cc37c51b3a5e7251c9e9f485de2b415db2bc9c8df0a450dd97c74efaacd03011118bbfdea5e19c6f3d9814cef64d50077e6d0f6f
+  metadata.gz: 4919b4d6661210538aeffa136d2457e55bc3e2cdf100f92a1fe04ba765b87b9821c87d6e2f1d3f07d146a0e6634a36d17e05501137ef469bf86048906ac619af
+  data.tar.gz: 89c32aba539deaaa7c69ddc6f5e438446d1fff6375e66a84c5139b3508cfce068de26207f66dbc3adc62012444826e86f322601cce8a30573d78fc0949e935a0

data/Guardfile

@@ -2,4 +2,5 @@ guard 'rspec', cmd: 'bundle exec rspec' do
   watch(%r{^spec/.+_spec\.rb})
   watch(%r{^lib/(.+)\.rb})     { |m| "spec/lib/#{m[1]}_spec.rb" }
   watch('spec/spec_helper.rb') { "spec" }
+  watch('spec/support/database.rb') { "spec" }
 end

data/README.md

@@ -1,8 +1,10 @@
 # Acts As Explorable
 
-[![Build Status](https://travis-ci.org/hiasinho/acts_as_explorable.svg?branch=develop)](https://travis-ci.org/hiasinho/acts_as_explorable) [![Code Climate](https://codeclimate.com/github/hiasinho/acts_as_explorable/badges/gpa.svg)](https://codeclimate.com/github/hiasinho/acts_as_explorable) [![Inline docs](http://inch-ci.org/github/hiasinho/acts_as_explorable.svg?branch=develop)](http://inch-ci.org/github/hiasinho/acts_as_explorable)
+[![Gem Version](https://badge.fury.io/rb/acts_as_explorable.svg)](http://badge.fury.io/rb/acts_as_explorable) [![Build Status](https://travis-ci.org/hiasinho/acts_as_explorable.svg?branch=develop)](https://travis-ci.org/hiasinho/acts_as_explorable) [![Code Climate](https://codeclimate.com/github/hiasinho/acts_as_explorable/badges/gpa.svg)](https://codeclimate.com/github/hiasinho/acts_as_explorable) [![Inline docs](http://inch-ci.org/github/hiasinho/acts_as_explorable.svg?branch=develop)](http://inch-ci.org/github/hiasinho/acts_as_explorable)
 
-Acts As Explorable is a Ruby Gem specifically written for ActiveRecord models.
+Acts As Explorable extends ActiveRecord models with a `search` class method. This method can be fed with a quer like `Madrid in:city position:MF sort:club`. Which means *"Get all players who play in Madrid on the midfielder position and sort the results by the club names"*.
+
+Acts As Explorable is a Ruby Gem specifically written for ActiveRecord models. It uses [Arel](https://github.com/rails/arel) to build query parts.
 
 ## Installation
 
@@ -13,19 +15,137 @@ Acts As Explorable is a Ruby Gem specifically written for ActiveRecord models.
 
 ### Install
 
-THIS GEM IS NOT RELEASED YET. SO, THIS WON'T WORK!
-
 Just add the following to your Gemfile.
 
 ```ruby
-gem 'acts_as_explorable', '~> 0.0.1'
+gem 'acts_as_explorable', '~> 0.1.1'
 ```
 
 And follow that up with a ``bundle install``.
 
 ## Usage
 
-TODO
+To enable the explorable plugin, just include the following lines into your model:
+
+```ruby
+class Foo < ActiveRecord::Base
+  extend ActsAsExplorable
+  explorable
+end
+```
+
+Now you have the `.search` method on your model, which can be invoked like 
+
+```ruby
+Foo.search('Awesome in:bar')
+```
+
+A query string consists of two different types: The values (random words) and filters (starting with a word followed by a `:` and again a word -> `in:bar`). As of writing this, there are three different kinds of filters.
+
+### Filters
+
+A filter always consists of an element (the string before the `:`) and the *"modifiers"*, which can be appended with a `,`. Optional you can add a `-` for options (only used in `sort:` at the moment).
+
+#### In
+
+The `in:` filter makes use of the values given in the query string. It looks up these values in the given columns. For example the following query will look up all posts with the word *"Zlatan"* in the title or the body:
+
+`Zlatan in:title,body`
+
+You can do that by defining the `in:` filter on your model:
+
+```ruby
+class Post < ActiveRecord::Base
+  extend ActsAsExplorable
+  explorable in: [:title, :body]
+end
+```
+
+As you see, it is possible to look up the value in different columns. This generates some SQL like:
+
+```sql
+SELECT posts.* FROM posts 
+  WHERE (posts.title ILIKE '%Zlatan%' OR posts.body ILIKE '%Zlatan%') 
+```
+
+#### Sort
+
+The `sort:` filter does (guess what?!) sorting. Just write `sort:` followed by the columns you want to sort. You can also append a `-desc` or `-asc` for the direction. So the query `sort:created_at-asc` sorts all posts be the `created_at` column in ascending direction. 
+
+Just define the `sort:` filter for your model:
+
+```ruby
+class Player < ActiveRecord::Base
+  extend ActsAsExplorable
+  explorable sort: [:title, :created_at]
+end
+```
+
+You can add more sorts just by addding the with a comma. `sort:created_at-asc,title-desc`. This produces the following SQL:
+
+```sql
+SELECT posts.* FROM posts 
+  ORDER BY posts.created_at ASC, posts.title DESC
+```
+
+#### Dynamic Filters
+
+This is where the *"magic"* happens. Say you have a model that represents a football player. And this player plays on a specific position. If you want to find all midfielders you could do `MF in:position` or you could use a dynamic filter.
+
+You can define these filters on your model and assign options to them like this:
+
+```ruby
+class Player < ActiveRecord::Base
+  extend ActsAsExplorable
+  explorable position: ['GK', 'DF', 'MF', 'FW']
+end
+```
+
+Now, given a quer string `position:MF,FW` will give you all midfielders an forwards. Nice! This is the SQL:
+
+```sql
+SELECT players.* FROM players 
+  WHERE (players.position IN ('MF','FW')) 
+```
+
+#### Wrap Up
+
+So, using all these examples, assuming you have this model:
+
+```ruby
+class Post < ActiveRecord::Base
+  extend ActsAsExplorable
+  explorable in: [:title, :body],
+             sort: [:title, :created_at],
+             state: ['draft', 'published', 'trash']
+
+  scope :older_than, -> (date) { where(%q{created_at <= ?}, date) }
+end
+```
+
+You could query all posts in *draft* state with *"Zlatan"* in the title or body and sort the ascending by their creation date.
+
+`Zlatan in:title,body sort:created_at-asc state:draft`
+
+```ruby
+Post.search('Zlatan in:title,body sort:created_at-asc state:draft')
+```
+
+Now we have a SQL like this:
+
+```ruby
+SELECT posts.* FROM posts 
+  WHERE (posts.title ILIKE '%Zlatan%' OR posts.body ILIKE '%Zlatan%')
+    AND (posts.state IN ('draft'))
+  ORDER BY 
+    posts.created_at ASC
+```
+
+You can also append your scopes:
+
+```ruby
+Post.search('Zlatan in:title,body sort:created_at-asc state:draft').older_than(DateTime.now)
+```
 
 ## Testing
 
@@ -42,11 +162,8 @@ Acts as explorable is released under the [MIT License](http://www.opensource.org
 
 ## TODO
 
-### v0.1
-- Fill this README file
-- Release v0.0.1 to rubygems
-
 ###v0.x
 - Add tests for postgres and mysql
 - Query string validation helper for use in forms
 - Use methods in addition to fields
+- Use named scopes

data/lib/acts_as_explorable/version.rb

@@ -1,3 +1,3 @@
 module ActsAsExplorable
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acts_as_explorable
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Mathias Schneider