zable 0.0.8 → 0.0.9

data/README.md

@@ -16,6 +16,7 @@ end
 * **options** - (Hash)
   * **:class** - (String) Html class
   * **:id** - (String) Html id
+  * **:params** - (Hash) Additional params to be appended at the end of every header/pagination link
 
 Within the zable block, you can use the `column` method to define the columns of your table.
 
@@ -35,6 +36,129 @@ end
   * **:title** - (String or Proc) You can use this to designate a custom header title string, or with a proc, supply completely custom header markup.
   * **:sort** - (Boolean, default: true) By default, the header title will be a link that can be used to sort its respective column. However by setting this option to false, the title will not be a link.
 
+If you pass in a block, the content of each cell in that column will be calculated from the block; otherwise the content will be taken from the supplied attribute.
+
+## In the controller
+
+The zable gem provides a single `populate` method to handle sorting, searching/filtering, and pagination. Querying your objects is as simple as this:
+
+```ruby
+def index
+  @items = Item.populate(params)
+  # or
+  @items = current_user.items.populate(params)
+end
+```
+
+As you can see, all me must do is pass in the request's params to the `populate` method. You can also attach the method after a chain of queries.
+
+Below shows an example of all possible passed parameters of interest when using sorting, searching and pagination:
+
+```ruby
+params = {
+  sort: {
+    attr: "column_1", # name of the sorted attribute
+    order: "asc" # 'asc' or 'desc' ('asc' is default)
+  },
+  search: {
+    column_1: "some_search", # key is the attr being searched on, value is the search query
+    column_2: "some_other_search"
+  },
+  page: {
+    num: 1, # page number
+    size: 20 # items per page
+  }
+}
+```
+
+## Sorting
+
+You can easily sort on your models' column attributes via the `sortable` method provided on ActiveRecord.
+
+```ruby
+class Item < ActiveRecord::Base
+  sortable :name, :price, :created_at
+end
+
+# in the view
+zable @items do
+  column(:name)
+  column(:price)
+  column(:created_at)
+end
+```
+
+If you want to sort on something more complex than a column in your database, you can do so by creating a named scope:
+
+```ruby
+class Item < ActiveRecord::Base
+  scope :sort_category, -> asc_or_desc { includes(:category).order("category.name #{asc_or_desc}") }
+end
+
+# in the view
+zable @items do
+  column(:category)
+end
+```
+
+## Searching
+
+Similar to sorting, zable provides a `searchable` method on ActiveRecord.
+
+```ruby
+class Item < ActiveRecord::Base
+  searchable :name, :price, :created_at
+end
+```
+
+This allows us to do equality-based searching on these attributes. Again, if you would like to do something more complex, create a named scope:
+
+```ruby
+class Item < ActiveRecord::Base
+  scope :search_category, -> value { joins(:category).where("upper(items.category) like %#{value.upcase}%") }
+end
+```
+
+## Pagination
+
+Optionally, you can use pagination via [will_paginate](https://github.com/mislav/will_paginate). In the view, simply set the 'paginate' option:
+
+```ruby
+zable @items, paginate: true do
+  ...
+end
+```
+
+As with will_paginate, page size can be set on your model:
+
+```ruby
+class Item
+  self.per_page = 10
+end
+# OR
+WillPaginate.per_page = 10
+```
+
+Additionally, you can set a per_page option directly in the #populate method:
+
+```ruby
+@items = Item.populate(params, per_page: 20)
+```
+
+Lastly, if you have a page size set in the params, this will override any of the previous per_page settings.
+
+```ruby
+params['page']['size'] = 15 # this takes precedence over any other settings
+```
+
+This allows your users to set how many items are shown per page on the front end. To help with this, zable provides a `set_page_size_path(page_size)` helper method. In your view, you can do something like this:
+
+```ruby
+<%= link_to "View 10 per page", set_page_size_path(10) %>
+<%= link_to "View all items", set_page_size_path() %>
+```
+
+As shown above, a nil page_size can be used for showing all items on a single page.
 
 ## Example
 
@@ -57,7 +181,7 @@ end
 index.html.erb:
 ```erb
 <%= 
-  zable @items, :table_class => ["users-table", "shiny-colorful-table"] do
+  zable @items, class: "users-table" do
     column(:name)
     column(:email)
     column(:created_at, :title => "Join Date")

data/app/helpers/zable_helper.rb

@@ -23,4 +23,21 @@ module ZableHelper
     current_sort_order == :desc ? :asc : :desc
   end
 
+  def set_page_size_path(page_size = nil)
+    page_params = if page_size
+      { :page => {:size => page_size, :num => 1} }
+    else
+      { :page => {:size => 'all'} }
+    end
+    current_path_with_params(params.slice(:sort, :search), page_params)
+  end
+
+  def zable_hidden_search_fields
+    fields = ""
+    fields << hidden_field_tag('sort[attr]', params[:sort][:attr]) if params[:sort] && params[:sort][:attr]
+    fields << hidden_field_tag('sort[order]', params[:sort][:order]) if params[:sort] && params[:sort][:order]
+    fields << hidden_field_tag('page[size]', params[:page][:size]) if params[:page] && params[:page][:size]
+    fields.html_safe
+  end
+
 end

data/lib/zable/active_record.rb

@@ -3,7 +3,6 @@ module Zable
   module ActiveRecord
 
     module ClassMethods
-      PAGE_DEFAULTS = { 'num' => 1 }
 
       def scoped_for_sort(params, scoped_object)
         hash = (params[:sort] || {}).stringify_keys
@@ -17,16 +16,24 @@ module Zable
         scoped_object
       end
 
-      def scoped_for_paginate(params, scoped_object)
-        page = (PAGE_DEFAULTS.merge(params[:page] || {})).stringify_keys
-        scoped_object = scoped_object.paginate(:page => page['num'], :per_page => page['size']) if scoped_object.respond_to?(:paginate)
+      def scoped_for_paginate(params, scoped_object, options)
+        page_params = (params[:page] || {}).stringify_keys
+        if scoped_object.respond_to?(:paginate)
+          paginate_opts = {}
+          paginate_opts[:page] = page_params['num'] || 1
+          # params take preference over option, so that we may change page size on the frontend
+          page_size = page_params['size'] || options[:per_page]
+          page_size = 99999999 if page_size == 'all'
+          paginate_opts[:per_page] = page_size if page_size.present?
+          scoped_object = scoped_object.paginate(paginate_opts)
+        end
         scoped_object
       end
 
-      def populate(params={})
+      def populate(params={}, options = {})
         obj = scoped_for_sort(params, self)
         obj = scoped_for_search(params, obj)
-        scoped_for_paginate(params, obj)
+        scoped_for_paginate(params, obj, options)
       end
 
       module Helpers

data/lib/zable/html.rb

@@ -39,30 +39,20 @@ module Zable
       "#{controller.request.fullpath.split("?")[0]}"
     end
 
+    def current_path_with_params(*param_array)
+      all_params = param_array.reject(&:blank?).map {|p| p.to_query.html_safe}.join("&".html_safe)
+      all_params = all_params.sub("%5B", "[").sub("%5D", "]")
+      current_url << "?".html_safe << all_params
+    end
+
     def param(param_type, param_key, attr)
       "#{param_type}[#{param_key}]=#{attr}"
     end
 
     def sort_params(attr)
-      params = []
-      params << param(:sort, "attr", attr[:name])
-      params << param(:sort, "order", attr[:sort_order]) if attr[:sorted?]
-      params.join("&".html_safe)
-    end
-
-    def current_sort_params
-      p = []
-      if params[:sort].present?
-        p << param(:sort, "attr", params[:sort][:attr])
-        p << param(:sort, "order", params[:sort][:order]) if params[:sort][:order].present?
-      end
-      p.join("&".html_safe)
-    end
-
-    def search_params
-      @search.to_a.collect do |param|
-        param(:search, param.first, param.second)
-      end.join("&".html_safe)
+      params = { :sort => {:attr => attr[:name]} }
+      params[:sort][:order] = attr[:sort_order] if attr[:sorted?]
+      params
     end
 
     def sort_arrow_image_file(attr)
@@ -70,8 +60,7 @@ module Zable
     end
 
     def header_cell_href(attr)
-      params = [sort_params(attr), search_params, @_extra_params.to_query.html_safe].reject(&:blank?).join("&".html_safe)
-      current_url << "?".html_safe << params
+      current_path_with_params(sort_params(attr), params.slice(:search), @_extra_params)
     end
 
     def header_cell_link_text(attr)

data/lib/zable/sort.rb

@@ -20,7 +20,7 @@ module Zable
         #   sortable :last_name, :created_at
         def sortable(*attr_names)
           attr_names.each do |attr_name|
-            scope "sort_#{attr_name}", -> options { order("#{table_name}.#{attr_name} #{options[:order]}") }
+            scope "sort_#{attr_name}", -> ordering { order("#{table_name}.#{attr_name} #{ordering}") }
           end
         end
 
@@ -28,7 +28,9 @@ module Zable
 
         def inject_sort_scope(sort_params)
           return unless sort_params
-          self.send scope_for_sort_attribute(sort_params), sort_params
+          sort_params.stringify_keys!
+          sort_params['order'] = 'ASC' if sort_params['order'].nil? || sort_params['order'].upcase != "DESC"
+          self.send scope_for_sort_attribute(sort_params), sort_params['order']
         end
 
         def scope_name_for_attribute(type, attr)
@@ -36,8 +38,6 @@ module Zable
         end
 
         def scope_for_sort_attribute(sort_params)
-          sort_params.stringify_keys!
-          sort_params['order'] = 'ASC' if sort_params['order'].nil? || sort_params['order'].upcase != "DESC"
           scope_name_for_attribute(:sort, sort_params['attr'])
         end
       end

data/lib/zable/view.rb

@@ -61,7 +61,9 @@ module Zable
     def pagination_element
       content_tag :div, :class => 'brownFilterResultsBox' do
         page_entries_info(@collection, @options.slice(:entry_name)) <<
-          will_paginate(@collection, :renderer => Zable::WillPaginate::LinkWithParamsRenderer.new(self, @_extra_params))
+          will_paginate(@collection,
+                        :renderer => Zable::WillPaginate::LinkWithParamsRenderer.new(self, @_extra_params)
+          )
       end
     end
 

data/lib/zable/will_paginate.rb

@@ -10,9 +10,8 @@ module Zable
       end
 
       def url(page)
-        page_param = @zable_view.param(:page, :num, page)
-        all_params = [page_param, @zable_view.current_sort_params, @zable_view.search_params, @params.to_query.html_safe].reject(&:blank?).join("&".html_safe)
-        @zable_view.current_url << "?".html_safe << all_params
+        page_params = {:page => {:num => page}}
+        @zable_view.current_path_with_params(page_params, @zable_view.params.slice(:search, :sort), @params)
       end
 
     protected

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zable
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-05 00:00:00.000000000 Z
+date: 2013-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: will_paginate