search_object 0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--format=documentation

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0
+  - rbx-19mode
+script: bundle exec rspec spec
+notifications:
+  email: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## Version 0.1
+
+* initial release

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in search_object.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Radoslav Stankov
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,283 @@
+[![Code Climate](https://codeclimate.com/github/RStankov/SearchObject.png)](https://codeclimate.com/github/RStankov/SearchObject)
+[![Build Status](https://secure.travis-ci.org/RStankov/SearchObject.png)](http://travis-ci.org/RStankov/SearchObject)
+[![Code coverage](https://coveralls.io/repos/RStankov/SearchObject/badge.png?branch=master)](https://coveralls.io/r/RStankov/SearchObject)
+
+# SearchObject
+
+In many of my projects I've needed an object that performs several fairly complicated queries. Or, just some multi-field search forms. Most times I hand-coded them, but they would get complicated over time when other concerns were added like sorting, pagination and so on. So I decided to abstract this away and created ```SearchObject```, a DSL for creating such objects.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'search_object'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install search_object
+
+## Usage
+
+Just include the ```SearchObject.module``` and define your search options:
+
+```ruby
+class PostSearch
+  include SearchObject.module
+
+  # Use .all (Rails4) or .scoped (Rails3) for ActiveRecord objects
+  scope { Post.all }
+
+  option :name             { |scope, value| scope.where name: value }
+  option :created_at       { |scope, dates| scope.created_after dates }
+  option :published, false { |scope, value| value ? scope.unopened : scope.opened }
+end
+```
+
+Then you can just search the given scope:
+
+```ruby
+search = PostSearch.new(params[:filters])
+
+# accessing search options
+search.name                        # => name option
+search.created_at                  # => created at option
+
+# accessing results
+search.count                       # => number of found results
+search.results?                    # => is there any results found
+search.results                     # => found results
+
+# params for url generations
+search.params                     # => option values
+search.params opened: false       # => overwrites the 'opened' option
+```
+
+## Example
+
+You can find example of most imporatant features and plugins - [here](https://github.com/RStankov/SearchObject/tree/master/example).
+
+## Plugins
+
+```SearchObject``` support plugins, which are passed to ```SearchObject.module``` method.
+
+Plugins are just plain Ruby modules, which are included with ```SearchObject.module```. They are located under ```SearchObject::Plugin``` module.
+
+### Paginate plugin
+
+Really simple paginte plugin, which uses the plain ```.limit``` and ```.offset``` methods.
+
+```ruby
+class ProductSearch
+  include SearchObject.module(:paging)
+
+  scope { Product.all }
+
+  option :name
+  option :category_name
+
+  # per page defaults to 25
+  # you can also overwrite per_page method
+  per_page 10
+end
+
+search = ProductSearch.new(params[:filters], params[:page]) # page number is required
+search.page                                                 # => page number
+search.per_page                                             # => per page (10)
+search.results                                              # => paginated page results
+```
+
+Of course if you want more sophisticated pagination plugins you can use:
+
+```ruby
+include SearchObject.module(:will_paginate)
+include SearchObject.module(:kaminari)
+```
+
+### Model plugin
+
+Extends your search object with ```ActiveModel```, so you can use it in rails forms.
+
+```ruby
+class ProductSearch
+  include SearchObject.module(:model)
+
+  scope { Product.all }
+
+  option :name
+  option :category_name
+end
+```
+
+```erb
+# in some view:
+<%= form_for ProductSearch.new do |form| %>
+  <% form.label :name %>
+  <% form.text_field :name %>
+  <% form.label :category_name %>
+  <% form.text_field :category_name %>
+<% end %>
+```
+
+### Sorting plugin
+
+Fixing the pain of dealing with sorting attributes and directions.
+
+```ruby
+class ProductSearch
+  include SearchObject.module(:sorting)
+
+  scope { Product.all }
+
+  sort_by :name, :price
+end
+
+search = ProductSearch.new(sort: 'price desc')
+search.results                                # => Product sorted my price DESC
+search.sort_attribute                         # => 'price'
+search.sort_direction                         # => 'desc'
+
+# Smart sort checking
+search.sort?('price')                         # => true
+search.sort?('price desc')                    # => true
+search.sort?('price asc')                     # => false
+
+# Helpers for dealing with reversing sort direction
+search.reverted_sort_direction                # => 'asc'
+search.sort_direction_for('price')            # => 'asc'
+search.sort_direction_for('name')             # => 'desc'
+
+# Params for sorting links
+search.sort_params_for('name')
+
+```
+
+## Tips & Tricks
+
+### Passing scope as argument
+
+``` ruby
+class ProductSearch
+  include SearchObject.module
+
+  scope :name
+end
+
+# first arguments is treated as scope (if no scope option is provided)
+search = ProductSearch.new(Product.visible, params[:f])
+search.results #=> products
+```
+
+
+### Handling nil options
+
+```ruby
+class ProductSearch
+  include SearchObject.module
+
+  scope { Product.all }
+
+  # nil values returned from option blocks are ignored
+  scope :sold { |scope, value| scope.sold if value }
+end
+```
+
+### Default option block
+
+```ruby
+class ProductSearch
+  include SearchObject.module
+
+  scope { Product.all }
+
+  option :name # automaticly applies => { |scope, value| scope.where name: value unless value.blank? }
+end
+```
+
+### Using instance method in option blocks
+
+```ruby
+class ProductSearch
+  include SearchObject.module
+
+  scope { Product.all }
+
+  option :date { |scope, value| scope.by_date parse_dates(value) }
+
+  private
+
+  def parse_dates(date_string)
+    # some "magic" method to parse dates
+  end
+end
+```
+
+### Active Record is not required at all
+
+```ruby
+class ProductSearch
+  include SearchObject.module
+
+  scope { RemoteEndpoint.fetch_product_as_hashes }
+
+  option :name     { |scope, value| scope.select { |product| product[:name] == value } }
+  option :category { |scope, value| scope.select { |product| product[:category] == value } }
+end
+```
+
+### Overwriting methods
+
+You can have fine grained scope, by overwriting ```initialize``` method:
+
+```ruby
+class ProductSearch
+  include SearchObject.module
+
+  option :name
+  option :category_name
+
+  def initialize(user, filters)
+    super Product.visible_to(user), filters
+  end
+end
+```
+
+Or you can add simple pagination by overwriting both ```initialize``` and ```fetch_results``` (used for fetching results):
+
+```ruby
+class ProductSearch
+  include SearchObject.module
+
+  scope { Product.all }
+
+  option :name
+  option :category_name
+
+  attr_reader :page
+
+  def initialize(filters = {}, page = 0)
+    super filters
+    @page = page.to_i.abc
+  end
+
+  def fetch_results
+    super.paginate page: @page
+  end
+end
+```
+
+## 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'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Run the tests (`rake`)
+6. Create new Pull Request
+
+## License
+
+**[MIT License](https://github.com/RStankov/SearchObject/blob/master/LICENSE.txt)**

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/example/.gitignore

@@ -0,0 +1,16 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile '~/.gitignore_global'
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore the default SQLite database.
+/db/*.sqlite3
+/db/*.sqlite3-journal
+
+# Ignore all logfiles and tempfiles.
+/log/*.log
+/tmp

data/example/.rspec

@@ -0,0 +1 @@
+--color

data/example/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+gem 'rails', '4.0.0'
+gem 'sqlite3'
+gem 'sass-rails', '~> 4.0.0'
+gem 'slim'
+gem 'jquery-rails'
+gem 'bootstrap-sass'
+gem 'will_paginate'
+gem 'will_paginate-bootstrap'
+gem 'rspec-rails'

data/example/README.md

@@ -0,0 +1,34 @@
+# SearchObject example Rails application
+
+This is example application showing, one of the possible usages of ```SearchObject```. It showcases the following features:
+
+  * Basic search object functionality
+  * Default options
+  * Using private method helpers in options
+  * Plugins: model, sorting, will_paginate
+
+## Interesting files:
+
+  * [PostsController](https://github.com/RStankov/SearchObject/blob/master/example/app/controllers/posts_controller.rb)
+  * [PostSearch](https://github.com/RStankov/SearchObject/blob/master/example/app/models/post_search.rb)
+  * [posts/index.html.slim](https://github.com/RStankov/SearchObject/blob/master/example/app/views/posts/index.html.slim)
+  * [PostSearch spec](https://github.com/RStankov/SearchObject/blob/master/example/spec/models/post_search_spec.rb)
+
+## Installation
+
+```
+gem install bundler
+bundle install
+rake db:create
+rake db:migrate
+rake db:seed
+
+rails server
+```
+
+From there just visit: [localhost:3000/](http://localhost:3000/)
+
+
+## Screenshot
+
+![Screenshot](https://raw.github.com/RStankov/SearchObject/master/example/screenshot.png)

data/example/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Example::Application.load_tasks

data/example/app/assets/javascripts/application.js

@@ -0,0 +1,5 @@
+//= require jquery
+
+$('form table :input').on('change', function(e) {
+  $(e.target).closest('form').submit();
+});

data/example/app/assets/stylesheets/application.css.scss

@@ -0,0 +1,40 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */
+
+@import "reset";
+@import "bootstrap";
+
+body { font-family: "Helvetica Neue", Helvetica, Arial, sans-serif !important; font-size: 14px; }
+
+#search-form {
+  padding: 40px;
+  width: 100%;
+  min-width: 900px;
+
+  h1 { font-weight: 500; font-size: 36px; margin-bottom: 20px; }
+
+  input[type="search"],
+  input[type="date"],
+  input[type="text"] { color: #555555; border: 1px solid #cccccc; border-radius: 4px; font-size: 14px; }
+
+  fieldset { margin-bottom: 20px; padding: 10px; border: 1px solid #e7e7e7; border-radius: 4px; background-color: #f8f8f8; }
+  fieldset input[type="submit"] { @extend .btn; @extend .btn-default; }
+  fieldset input[type="search"],
+  fieldset input[type="date"] { vertical-align: middle; height: 34px; padding: 6px 12px; margin-right: 10px; }
+
+  table thead label { color: #428bca; }
+  table thead .active { font-weight: bold; color: black; }
+  table thead input[type="text"] { padding: 0 6px; width: 99%; }
+  table tbody .empty { text-align: center; }
+}