mincer 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 48b963be79455d1a78fb2ba3ba717e7797a1c68b
-  data.tar.gz: 38811ae437f8dd4e35d338e7abcd1a50988df393
+  metadata.gz: e760eb485129e914fb5ac87ab37ded1217ba6114
+  data.tar.gz: 99cba1c3544b4b7f294ceeb9f0fe25535e9943a1
 SHA512:
-  metadata.gz: 9eaae3dda688bbb12f58fd56ce8850e5570354e8ed232bcff89614617c97dd73cd46018322559ddc5288c51a5e52425d7b5f3492deb89ac8898249a7b1fb995b
-  data.tar.gz: fd7512ad6cc69e82410e525a517db83657050f6f40bdb0bc0741e97b507239e68ce2918622ded82012f7a74a0c5503f51c5c7177ee67f3fc4fa7bac0eceb1002
+  metadata.gz: 09778cda72e7c9fb49542418647e8610c787a0ec5c79176773accc5a89d92593347c6347a76fe518aff83c1f432b78a29ef3b2ee5d14e464476fe61c0dfd0851
+  data.tar.gz: b77528eea0f446b5f832a44696c32f74777c375512210ad6412e9173017a746672ec881a905ca68b196c0d78e8cc9f92f510dc91ce2eb6b9a5add5cfe789493a

data/.gitignore

@@ -20,3 +20,5 @@ Guardfile
 atlassian-ide-plugin.xml
 .rspec
 spec/database.yml
+.ruby-gemset
+.ruby-version

data/README.md

@@ -3,7 +3,14 @@
 [![Code Climate](https://codeclimate.com/repos/52b775836956801ba7000bdb/badges/ec5d5862e4b89d10695c/gpa.png)](https://codeclimate.com/repos/52b775836956801ba7000bdb/feed)
 [![Gem Version](https://badge.fury.io/rb/mincer.png)](http://badge.fury.io/rb/mincer)
 
-TODO: Write a gem description
+Mincer is an ActiveRecord::Relation wrapper that applies usefull features to your queries. It can:
+
+[Paginate](#pagination)     
+[Sort](#sort)   
+[Search](#search)   
+[Dump to Json(Using postgres >= 9.2)](#json)    
+[Generate digest(usefull for caching)](#digest) 
+
 
 ## Installation
 
@@ -20,8 +27,232 @@ Or install it yourself as:
     $ gem install mincer
 
 ## Usage
+Lets assume we have 2 models
+
+    class Employee < ActiveRecord::Base
+        belongs_to :company
+    end
+    
+    class Company < ActiveRecord::Base
+        has_many :employees
+    end
+    
+Lets create class EmployeesListQuery class that will inherit from Mincer::Base, and instantiate it
+
+    class EmployeesListQuery < Mincer::Base
+        # method should always return relation
+        def build_query(relation, args)
+            custom_select = <<-SQL
+                employees.id, 
+                employees.full_name as employee_name, 
+                companies.name as company_name
+            SQL
+            relation.joins(:company).select(custom_select)
+        end
+    end
+    
+    employees = EmployeesListQuery.new(Employee)
+
+`employees` will delegate all methods, that it can't find on itself, to relation objects. This means you can use
+`employess` as you would use any ActiveRecord::Relation object:
+
+    <% employees.each do |employee| %>
+        <%= employee.employee_name %>
+        <%= employee.company_name %>
+    <% end %>
+    
+
+Now lets's look what more can we do with this object
+
+<a name="pagination"/>
+### Pagination
+Mincer supports [kaminari](https://github.com/amatsuda/kaminari) and [will_paginate](https://github.com/mislav/will_paginate). In order to use pagination you need to include one of them 
+to your `Gemfile`. Example of using pagination
+
+    employees = EmployeesListQuery.new(Employee, {'page' => 2, 'per_page' => 10})
+    
+By default all `Micner` objects will use pagination, even if no arguments are passed. To set default values for pagination please refer to `kaminari` or `will_paginate` documentation.
+
+To disable pagination you can use class method `skip_pagination!`:
+
+    class EmployeesListQuery < Mincer::Base
+        skip_pagination!
+        
+        # method should always return relation
+        def build_query(relation, args)
+            custom_select = <<-SQL
+                employees.id, 
+                employees.full_name as employee_name, 
+                companies.name as company_name
+            SQL
+            relation.joins(:company).select(custom_select)
+        end
+    end
+
+<a name="sort"/>
+### Sorting
+
+Example of using sorting:
+
+    employees = EmployeesListQuery.new(Employee, {'sort' => 'employee_name', 'order' => 'DESC'})
+    
+By default all Mincer objects will sort by attribute `id` and order `ASC`. To change defaults you can override 
+them like this
+
+    class EmployeesListQuery < Mincer::Base
+        # method should always return relation
+        def build_query(relation, args)
+            custom_select = <<-SQL
+                employees.id, 
+                employees.full_name as employee_name, 
+                companies.name as company_name
+            SQL
+            relation.joins(:company).select(custom_select)
+        end
+        
+      def default_sort_attribute
+        'employee_name'
+      end
+
+      def default_sort_order
+        'DESC'
+      end
+    end    
+    
+To disable sorting use class method `skip_sorting!` like this:
+
+    class EmployeesListQuery < Mincer::Base
+        skip_sorting!
+        
+        # method should always return relation
+        def build_query(relation, args)
+            custom_select = <<-SQL
+                employees.id, 
+                employees.full_name as employee_name, 
+                companies.name as company_name
+            SQL
+            relation.joins(:company).select(custom_select)
+        end
+    end
+
+Mincer will validate `sort` and `order` params and will not allow to sort by attributes that do not exist.
+Default white list consists of all atttributes from original scope, in our example `Employee.attribute_name`.
+You can expand the list overriding `allowed_sort_attributes` list like this:
+
+    def allowed_sort_attributes
+        super + %w{employee_name company_name}
+    end
+This will allow to sort by all Employee attributes + `employee_name` and `company_name`
+
+Or restrict like this:
+
+    def allowed_sort_attributes
+        %w{employee_name}
+    end
+in this example sorting allowed only by `employee_name`.
+
+#### ActionView
+
+If you are using Rails or bare ActionView there are few helper methods at your disposal to help generating links
+for sorting. Currently there are 2 methods available: `sort_url_for` and `sort_class_for`.
+
+Example of usage in HAML:
+    
+    %ul
+        %li{ :class => (sort_class_for employees, 'id') }
+            = link_to 'ID', sort_url_for(employees, 'id')
+        %li{ :class => (sort_class_for employees, 'employee_name') }
+            = link_to 'Employee', sort_url_for(employees, 'employee_name')
+        %li{ :class => (sort_class_for employees, 'company_name') }
+            = link_to 'Company', sort_url_for(employees, 'company_name')
+      
+In this example `li` will receive `class="sorted order_down"` or `class="sorted order_up"` if this attribue was used for search.
+Generated url will be enchanced with `sort` and `order` attributes.
+
+<a name="search"/>
+### Search
+
+Currently Mincer uses [Textacular](https://github.com/textacular/textacular) for search. This sets alot of restrictions: 
+1. Works only with postgres
+2. You have to include `textacular` to your Gemfile
+3. You have to install postgres extension that [Textacular](https://github.com/textacular/textacular) uses for searching.
+
+Example of usage:
+
+    employees = EmployeesListQuery.new(Employee, {'pattern' => 'whatever'})
+
+This will use `simple_search`, and if it will return no entries Mincer will run `fuzzy_search`. For more details on what
+is the difference between them, plese look refer to `textacular` github [page](https://github.com/textacular/textacular).
+
+<a name="json"/>
+### JSON generation
+
+Mincer allowes you to dump query result to JSON using [Postgres JSON Functions](http://www.postgresql.org/docs/9.3/static/functions-json.html)
+Didn't had time to do benchmarks - but its' extremely fast.
+
+Pros: 
+
+1. Speed
+2. No extra dependencies(you don't need any other JSON generators)
+
+Cons:
+
+1. Works only with postgres version >= 9.2
+2. If you are using ruby methods to generate some fields - you won't be able to use them in Mincer objects(Carrierwave image_urls, resource urls). You will have to duplicate logic inside postgres select query.
+
+To dump query result to json string you have to call `to_json` on Mincer object:
+
+    EmployeesListQuery.new(Employee).to_json
+    
+In our example it will return something like this 
+
+    "[{\"id\":1,\"employee_name\":\"John Smith\",\"company_name\":\"Microsoft\"},{\"id\":2,\"employee_name\":\"Jane Smith\",\"company_name\":\"37 Signals\"}]"
+    
+In addition you can pass option `root` to `to_json` method if you need to include root to json string:
+    
+    EmployeesListQuery.new(Employee).to_json(root: 'employees')
+    # returns
+    "{\"employees\":[{\"id\":1,\"employee_name\":\"John Smith\",\"company_name\":\"Microsoft\"},{\"id\":2,\"employee_name\":\"Jane Smith\",\"company_name\":\"37 Signals\"}]}"
+
+<a name="digest"/> 
+### Digest
+
+Digest is very usefull for cache invalidation on your views when you are using custom queries. We will modify a bit example:
+
+    class EmployeesListQuery < Mincer::Base
+        digest! %w{employee_updated_at company_updated_at}
+    
+        def build_query(relation, args)
+            custom_select = <<-SQL
+                employees.id, 
+                employees.full_name as employee_name, 
+                companies.name as company_name,
+                employees.updated_at as employee_updated_at, 
+                companies.updated_at as company_updated_at
+            SQL
+            relation.joins(:company).select(custom_select)
+        end
+    end
+
+In this example we will use 2 updated_at timestamps to generate digest. Whenever one of them will change - digest will change also. To get digest you should use method `digest` on Mincer model
+
+    EmployeesListQuery.new(Employee).digest # "\\x20e93b4dc5e029130f3d60d697137934"
+    
+To generate digest you need to install extension 'pgcrypto'. If you use Rails, please use migration for that
+    
+    enable_extension 'pgcrypto'
+    
+or run `CREATE EXTENSION IF NOT EXISTS pgcrypto;`
+
+
+## TODO
+
+1. Create general configuration for Mincer that would allow:
+    1. Changing sort html classes
+    2. Changing default arguments(sort, order, pattern, page, per_page..)
+    3. Disabling some processors for all Mincer objects
+2. Create rails generators.
 
-TODO: Write usage instructions here
 
 ## Contributing
 

data/lib/mincer/processors/search.rb

@@ -9,7 +9,7 @@ module Mincer
         if Mincer.postgres? && !textacular?
           warn 'You must include "textacular" to  your Gemfile to use search'
           @relation
-        elsif Mincer.postgres? && @args['pattern']
+        elsif Mincer.postgres? && @args['pattern'].present?
           @relation.basic_search(@args['pattern']).presence || @relation.fuzzy_search(@args['pattern'])
         else
           @relation

data/lib/mincer/processors/sort.rb

@@ -7,13 +7,17 @@ module Mincer
       end
 
       def apply
-        relation = @relation.order("#{sort_attr} #{order_attr}")
+        relation = @relation.order(sort_string)
         @mincer.sort_attribute, @mincer.sort_order = relation.try(:order_values).try(:first).try(:split)
         relation
       end
 
+      def sort_string
+        sort_attr ? "#{sort_attr} #{order_attr}, #{@mincer.default_sort_attribute}" : "#{@mincer.default_sort_attribute} #{order_attr}"
+      end
+
       def sort_attr
-        (@mincer.allowed_sort_attributes.include?(@args['sort']) && @args['sort']) || @mincer.send(:default_sort_attribute)
+        @mincer.allowed_sort_attributes.include?(@args['sort']) && @args['sort']
       end
 
       def order_attr

data/lib/mincer/version.rb

@@ -1,7 +1,7 @@
 module Mincer
 
   def self.version
-    Gem::Version.new '0.1.0'
+    Gem::Version.new '0.1.1'
   end
 
   module VERSION #:nodoc:

data/spec/lib/processors/search_spec.rb

@@ -33,6 +33,11 @@ describe ::Mincer::Processors::Search do
           query = subject.new(ActiveRecordModel, { 'pattern' => 'Bingo' })
           query.to_a.count.should eq(1)
         end
+
+        it 'avoids search when pattern is an empty string or spaces' do
+          query = subject.new(ActiveRecordModel, { 'pattern' => ' ' })
+          query.to_a.count.should eq(3)
+        end
       end
 
 

data/spec/support/sqlite3_adapter.rb

@@ -1,4 +1,4 @@
 def setup_basic_sqlite3_table
   ActiveRecord::Base.establish_connection(:adapter => 'sqlite3', :database => ':memory:')
-  ActiveRecord::Base.connection.execute('CREATE TABLE active_record_models (id INTEGER UNIQUE, text STRING)')
+  ActiveRecord::Base.connection.execute('CREATE TABLE active_record_models (id INTEGER PRIMARY KEY, text STRING)')
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mincer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Alex Krasinsky
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-23 00:00:00.000000000 Z
+date: 2014-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord