listings 0.1.4 → 0.1.5

data/README.md

@@ -22,6 +22,7 @@ A listing data source have built in support for ActiveRecord and Arrays.
       * [paginates_per](#paginates_per)
       * [export](#export)
       * [css](#css)
+    * [Testing](#testing)
     * [i18n](#i18n)
     * [Templates](#templates)
     * [Javascript api](#javascript-api)
@@ -63,6 +64,7 @@ Create `config/initializers/listings.rb` file to make general configurations. Li
 # file: config/initializers/listings.rb
 Listings.configure do |config|
   config.theme = 'twitter-bootstrap-3' # defaults to 'twitter-bootstrap-2'
+  config.push_url = true # User html5 history push_state to allow back/forward navigation. defaults to false
 end
 ```
 
@@ -241,12 +243,26 @@ It supports `title:` and a block
   end
 ```
 
+Also `render:` option can be used to suppress the rendering of the filter, but allowing the user to filter by it. For example to filter by the id:
+
+```ruby
+  filter :id, render: false
+```
+
 Filters are rendered by default by the side of the listing. With `layout` method you can change this and render them on the top.
 
 ```ruby
   layout filters: :top
 ```
 
+Custom filters allows definition of custom meaning to a key. This filters are not rendered.
+
+```ruby
+  custom_filter :order_lte do |items, value|
+    items.where('"order" <= ?', value.to_i)
+  end
+```
+
 ### paginates_per
 
 Page size can be specified by `paginates_per`
@@ -303,6 +319,32 @@ A `column` also support a `class` option to specify a css class to be applied on
   column :title, class: 'title-style'
 ```
 
+## Testing
+
+Include `listings/rspec` in your `spec_helper.rb`
+
+```ruby
+# file: spec/spec_helper.rb
+require 'listings/rspec'
+```
+
+Ensure listing is able to render
+
+```ruby
+# file: spec/listings/tracks_listing_spec.rb
+require 'spec_helper'
+
+RSpec.describe TracksListing, type: :listing do
+  let(:listing) { query_listing :tracks }
+
+  it 'should get tracks' do
+    # ... data setup ...
+    items = listing.items.to_a
+    # ... assert expected items ...
+  end
+end
+```
+
 ## i18n
 
 Although titles can be specified in the listing definition, i18n support is available. Add to your locales:
@@ -336,6 +378,30 @@ use
 refreshListing('tracks')
 ```
 
+Change filters
+
+```
+$('#tracks.listings').trigger("listings:filter:key:clear", 'album_name')
+$('#tracks.listings').trigger("listings:filter:key:set", ['album_name', 'Best of'])
+```
+
+## View Helpers
+
+Use `render_listing` helper to include the listing by its `name`.
+
+```
+= render_listing :tracks
+```
+
+Use `listings_link_to_filter` helper to render a link that will set a filter. Used to example when you want the user to be able to click on a cell value to filter upon that.
+
+```ruby
+  column artist: :name do |album, value|
+    listings_link_to_filter(value, :artist_id, album.artist_id)
+  end
+```
+
+
 ## Templates
 
 There are a number of templates involved in rendering the listing. These templates can be rendered by the hosting app per listing or theme basis.

data/app/assets/javascripts/listings.js

@@ -120,20 +120,17 @@ $(function(){
   $('.listing').on('click', 'a.filter, .filter a', function(e) {
     elem = $(this);
     var listingElement = elem.closest('.listing');
-    clearSelectedItems(listingElement);
-
     var key = elem.data('key');
     var value = elem.data('value');
 
     var search_data = listingElement.data('search');
     if (search_data.filters[key] == value) {
-      delete search_data.filters[key];
+      listingElement.trigger("listings:filter:key:clear", key)
     } else {
-      search_data.filters[key] = value;
+      listingElement.trigger("listings:filter:key:set", [key, value])
     }
 
-    listingElement.data('search', search_data);
-    updateListingFromSearchData(listingElement);
+    e.preventDefault();
   }).on("listings:loaded", function(e){
     // highlight current filter
     var listingElement = $(this).closest('.listing');
@@ -145,8 +142,42 @@ $(function(){
       listingElement.find(filerLinkSelector).closest('.filter').addClass('active');
     }
 
+    if (listingElement.data('config').push_url && listingElement.data('skip-push-url') !== true) {
+      listingElement.data('skip-push-url', false);
+      var url = listingElement.data('url');
+      var queryStringStart = url.indexOf('?');
+      var queryString = queryStringStart == -1 ? '' : url.substring(queryStringStart);
+      history.pushState({listing: '#' + listingElement.attr('id')}, document.title, location.href.split('?')[0] + queryString);
+    }
+
+  }).on("listings:filter:key:set", function(event, key, value) {
+    var listingElement = $(this).closest('.listing');
+    clearSelectedItems(listingElement);
+
+    var search_data = listingElement.data('search');
+    search_data.filters[key] = value;
+    listingElement.data('search', search_data);
+
+    updateListingFromSearchData(listingElement);
+  }).on("listings:filter:key:clear", function(event, key) {
+    var listingElement = $(this).closest('.listing');
+    clearSelectedItems(listingElement);
+
+    var search_data = listingElement.data('search');
+    delete search_data.filters[key];
+    listingElement.data('search', search_data);
+
+    updateListingFromSearchData(listingElement);
   });
 
+  window.onpopstate = function(event) {
+    if (event.state && event.state.listing) {
+      var listing = $(event.state.listing);
+      listing.data('skip-push-url', true);
+      $.get(listing.data('url').split('?')[0] + '?' + document.location.href.split('?')[1]);
+    }
+  };
+
   function searchEscape(value) {
     if (value.toString().indexOf(" ") == -1) {
       return value;

data/app/controllers/listings/listings_controller.rb

@@ -16,8 +16,11 @@ module Listings
       @listing = prepare_listing params, view_context, false
 
       respond_to do |format|
-        format.csv { send_data @listing.to_csv, filename: "#{params[:listing]}.csv" }
-        format.xls { render 'listings/export' }
+        format.csv { send_data @listing.to_csv, filename: @listing.export_filename(:csv) }
+        format.xls do
+          headers["Content-Disposition"] = "attachment; filename=\"#{@listing.export_filename(:xls)}\""
+          render 'listings/export'
+        end
       end
     end
 

data/app/views/listings/_listing.html.haml

@@ -1,4 +1,4 @@
-.listing{:id => listing.name, :'data-url' => listing.url, :'data-search' => listing.search_data.to_json }
+.listing{:id => listing.name, :'data-url' => listing.url, :'data-search' => listing.search_data.to_json, :'data-config' => listing.client_config.to_json }
   = listings_partial_render 'table_full', listing
 
 :javascript

data/app/views/listings/_table_content.html.haml

@@ -34,7 +34,7 @@
               = listing.export_message
             - listing.export_formats.each do |format|
               %li
-                = link_to format, listing.url_for_format(format)
+                = link_to format, listing.url_for_format(format), download: true
 
 
   - else

data/app/views/listings/twitter-bootstrap-2/_side_filters.html.haml

@@ -1,5 +1,5 @@
 .filters
-  - listing.filters.reverse.each do |filter_view|
+  - listing.filters_to_render.reverse.each do |filter_view|
     %ul.nav.nav-list.well
       %li.nav-header
         = "Filter by #{filter_view.human_name}"

data/app/views/listings/twitter-bootstrap-2/_top_filters.html.haml

@@ -1,4 +1,4 @@
-- listing.filters.each do |filter_view|
+- listing.filters_to_render.each do |filter_view|
   %li.dropdown.pull-right
     %a.dropdown-toggle(data-toggle="dropdown" href="#")
       = filter_view.human_name

data/app/views/listings/twitter-bootstrap-3/_side_filters.html.haml

@@ -1,5 +1,5 @@
 .filters.list-group
-  - listing.filters.reverse.each do |filter_view|
+  - listing.filters_to_render.reverse.each do |filter_view|
     %a.list-group-item.disabled(href="#")
       = "Filter by #{filter_view.human_name}"
     - filter_view.values.each do |value|

data/app/views/listings/twitter-bootstrap-3/_top_filters.html.haml

@@ -1,4 +1,4 @@
-- listing.filters.each do |filter_view|
+- listing.filters_to_render.each do |filter_view|
   %li.dropdown
     %a.dropdown-toggle(data-toggle="dropdown" href="#")
       = filter_view.human_name

data/lib/listings/action_view_extensions.rb

@@ -5,7 +5,13 @@ module Listings
       options.reverse_merge! :params => {}
       params_for_listing = {:listing => key}.merge(params).merge(options[:params]).with_indifferent_access
       listing = prepare_listing(params_for_listing, self)
-      listings_partial_render 'listing', listing
+      res = listings_partial_render 'listing', listing
+      Kaminari::Helpers::Tag.paginate_with_listings(nil)
+      res
+    end
+
+    def listings_link_to_filter(text, key, value)
+      link_to text, '#', onclick: "$(this).closest('.listing').trigger('listings:filter:key:set', ['#{key}', '#{escape_javascript(value)}']);return false;"
     end
 
     def listings_partial_render(view, listing, options = {})
@@ -22,7 +28,7 @@ module Listings
       params.delete :controller
       params.delete :action
 
-      Kaminari::Helpers::Tag.listings = view_context.listings
+      Kaminari::Helpers::Tag.paginate_with_listings(view_context.listings)
 
       listing_class = lookup_listing_class(params[:listing])
       listing_class.new.tap do |listing|

data/lib/listings/base.rb

@@ -46,7 +46,7 @@ module Listings
 
     def parse_filter(text, filter_keys)
       filters = {}
-      filter_keys.each do |key|
+      filter_keys.sort_by {|k| -k.length }.each do |key|
         text = collect_filter text, key, filters
       end
 
@@ -88,12 +88,12 @@ module Listings
       end
 
       if filterable?
-        filters.each do |filter_view|
+        filters_to_render.each do |filter_view|
           filter_view.values # prepare values
         end
 
         self.search_filters.each do |key, filter_value|
-          data_source.filter(filter_with_key(key).field, filter_value)
+          filter_with_key(key).apply_filter(filter_value)
         end
       end
 
@@ -217,5 +217,17 @@ module Listings
     def theme
       Listings.configuration.theme
     end
+
+    def export_filename(format)
+      "#{kind.gsub(' ', '_')}_#{Time.now.to_s.gsub(' ', '_')}.#{format}"
+    end
+
+    def filters_to_render
+      filters.select { |f| f.render? }
+    end
+
+    def client_config
+      { push_url: Listings.configuration.push_url }
+    end
   end
 end

data/lib/listings/base_field_view.rb

@@ -35,5 +35,9 @@ module Listings
     def is_field?
       @field_description.is_field?
     end
+
+    def descriptor
+      @field_description
+    end
   end
 end

data/lib/listings/configuration.rb

@@ -13,9 +13,11 @@ module Listings
 
   class Configuration
     attr_accessor :theme
+    attr_accessor :push_url # use html5 pushState to allow back navigation of listings. default false.
 
     def initialize
       @theme = 'twitter-bootstrap-2'
+      @push_url = false
     end
   end
 end

data/lib/listings/configuration_methods.rb

@@ -5,6 +5,8 @@ require 'listings/column_descriptor'
 require 'listings/column_view'
 require 'listings/filter_descriptor'
 require 'listings/filter_view'
+require 'listings/custom_filter_descriptor'
+require 'listings/custom_filter_view'
 
 module Listings
   module ConfigurationMethods
@@ -57,7 +59,7 @@ module Listings
 
       def filters
         @filters ||= self.class.filters.map do |fd|
-          FilterView.new(self, fd)
+          fd.build(self)
         end
       end
     end
@@ -162,6 +164,10 @@ module Listings
         filters << FilterDescriptor.new(path, props, proc)
       end
 
+      def custom_filter(key, &proc)
+        filters << CustomFilterDescriptor.new(key, proc)
+      end
+
       def layout(props = {})
         @layout_options = props
       end

data/lib/listings/custom_filter_descriptor.rb

@@ -0,0 +1,19 @@
+module Listings
+  class CustomFilterDescriptor
+    attr_reader :key
+    attr_reader :proc
+
+    def initialize(key, proc)
+      @key = key
+      @proc = proc
+    end
+
+    def build(listing)
+      CustomFilterView.new(listing, self)
+    end
+
+    def apply_filter(value)
+      data_source.filter(field, value)
+    end
+  end
+end

data/lib/listings/custom_filter_view.rb

@@ -0,0 +1,25 @@
+module Listings
+  class CustomFilterView
+    attr_reader :listing
+    attr_reader :descriptor
+
+    def initialize(listing, descriptor)
+      @listing = listing
+      @descriptor = descriptor
+    end
+
+    def key
+      @descriptor.key
+    end
+
+    def render?
+      false
+    end
+
+    def apply_filter(value)
+      listing.data_source.transform_items do |items|
+        listing.instance_exec items, value, &@descriptor.proc
+      end
+    end
+  end
+end

data/lib/listings/filter_descriptor.rb

@@ -3,5 +3,9 @@ module Listings
     def initialize(path, props, proc)
       super
     end
+
+    def build(listing)
+      FilterView.new(listing, self)
+    end
   end
 end

data/lib/listings/filter_view.rb

@@ -15,5 +15,13 @@ module Listings
         value
       end
     end
+
+    def render?
+      @field_description.props.fetch(:render, true)
+    end
+
+    def apply_filter(value)
+      listing.data_source.filter(field, value)
+    end
   end
 end

data/lib/listings/kaminari_helpers_tag_patch.rb

@@ -1,20 +1,29 @@
 module Kaminari
   module Helpers
     class Tag
+      def self.paginate_with_listings(val)
+        Thread.current[:listings] = val
+      end
 
-      def self.listings=(val)
-        @@listings=val
+      def self.listings_to_paginate_with
+        Thread.current[:listings]
       end
 
       # patch kaminari helpers
       # passing options of mountable engine routes seems to not be working
-      def page_url_for(page)
-        @params.delete :page
-        params = {@param_name => page}.merge(@params).with_indifferent_access
-        params.delete :controller
-        params.delete :action
-        @@listings.listing_content_url(params)
+      def page_url_for_with_listing(page)
+        if Kaminari::Helpers::Tag.listings_to_paginate_with
+          @params.delete :page
+          params = {@param_name => page}.merge(@params).with_indifferent_access
+          params.delete :controller
+          params.delete :action
+          Kaminari::Helpers::Tag.listings_to_paginate_with.listing_content_url(params)
+        else
+          page_url_for_without_listing(page)
+        end
       end
+
+      alias_method_chain :page_url_for, :listing
     end
   end
 end

data/lib/listings/rspec.rb

@@ -0,0 +1,5 @@
+require "listings/rspec/listings_helpers"
+
+RSpec.configure do |config|
+  config.include RSpec::ListingsHelpers, type: :listing
+end

data/lib/listings/sources/active_record_data_source.rb

@@ -29,6 +29,10 @@ module Listings::Sources
       end
     end
 
+    def transform_items
+      @items = yield @items
+    end
+
     def scope
       @items = yield @items
       @items_for_filter = yield @items_for_filter
@@ -39,7 +43,7 @@ module Listings::Sources
     end
 
     def values_for_filter(field)
-      @items_for_filter.reorder(field.query_column).pluck("distinct #{field.query_column}").reject(&:nil?)
+      field.all_values(@items_for_filter)
     end
 
     def search(fields, value)
@@ -62,7 +66,6 @@ module Listings::Sources
 
     def joins(relation)
       @items = @items.eager_load(relation)
-      @items_for_filter = @items_for_filter.joins(relation)
     end
 
     def build_field(path)
@@ -89,10 +92,28 @@ module Listings::Sources
     end
   end
 
-  class ActiveRecordField < Field
+  class BaseActiveRecordField < Field
     delegate :connection, to: :data_source
     delegate :quote_table_name, :quote_column_name, to: :connection
 
+    def initialize(data_source)
+      super(data_source)
+    end
+
+    def all_values(items)
+      prepare_pluck(items).reorder(query_column).pluck("distinct #{query_column}").reject(&:nil?)
+    end
+
+    def prepare_pluck(items)
+      items
+    end
+
+    def sort(items, direction)
+      items.reorder("#{query_column} #{direction}")
+    end
+  end
+
+  class ActiveRecordField < BaseActiveRecordField
     def initialize(attribute_name, data_source)
       super(data_source)
       @attribute_name = attribute_name
@@ -106,10 +127,6 @@ module Listings::Sources
       "#{quote_table_name(data_source.items.table_name)}.#{quote_column_name(@attribute_name)}"
     end
 
-    def sort(items, direction)
-      items.reorder("#{query_column} #{direction}")
-    end
-
     def key
       @attribute_name.to_s
     end
@@ -119,10 +136,7 @@ module Listings::Sources
     end
   end
 
-  class ActiveRecordAssociationField < Field
-    delegate :connection, to: :data_source
-    delegate :quote_table_name, :quote_column_name, to: :connection
-
+  class ActiveRecordAssociationField < BaseActiveRecordField
     def initialize(path, data_source)
       super(data_source)
       @path = path
@@ -130,6 +144,10 @@ module Listings::Sources
       data_source.joins(path[0])
     end
 
+    def prepare_pluck(items)
+      items.joins(@path[0])
+    end
+
     def value_for(item)
       result = item
       @path.each do |attribute_name|
@@ -144,10 +162,6 @@ module Listings::Sources
       "#{quote_table_name(association.reflection.table_name)}.#{quote_column_name(@path[1])}"
     end
 
-    def sort(items, direction)
-      items.reorder("#{query_column} #{direction}")
-    end
-
     def key
       @path.join('_')
     end

data/lib/listings/sources/data_source.rb

@@ -8,6 +8,10 @@ module Listings::Sources
     def items
     end
 
+    # free transform items. used usually to filter the result with logic given by a block
+    def transform_items
+    end
+
     # applies filter to the items
     # scope will be called with a block with the ongoing items
     # the result of the block is used as the narrowed items

data/lib/listings/sources/object_data_source.rb

@@ -9,6 +9,10 @@ module Listings::Sources
       @items
     end
 
+    def transform_items
+      @items = yield @items
+    end
+
     def paginate(page, page_size)
       @items = Kaminari.paginate_array(@items).page(page).per(page_size)
     end

data/lib/listings/version.rb

@@ -1,3 +1,3 @@
 module Listings
-  VERSION = "0.1.4"
+  VERSION = "0.1.5"
 end

data/lib/listings/view_helper_methods.rb

@@ -19,6 +19,8 @@ module Listings
         view_context.listings.listing_export_url build_params(:format => format)
       end
 
+      # TODO add url_for_filter that will build the search string
+
       def build_params(more_params)
         res = view_context.params.merge(:listing => self.name).merge(params).merge(more_params)
         res.delete param_page

data/spec/dummy/app/listings/tracks_listing.rb

@@ -6,6 +6,11 @@ class TracksListing < Listings::Base
   filter album: :id, title: 'The Album Id' do |value|
     "#{value}!"
   end
+  filter :order, render: false
+
+  custom_filter :order_lte do |items, value|
+    items.where('"order" <= ?', value.to_i)
+  end
 
   column :order
   column :title, searchable: true

data/spec/dummy/config/initializers/listings.rb

@@ -0,0 +1,3 @@
+Listings.configure do |config|
+  config.push_url = true
+end

data/spec/dummy/db/seeds.rb

@@ -5,7 +5,10 @@ require 'factory_girl'
   Post.create! title: "post n-#{sn}", author: "john-#{(sn % 4) + 1}", category: "category-#{(sn % 3) + 1}"
 end
 
-
 (1..10).each do |sn|
   FactoryGirl.create :album
 end
+
+(1..10).each do |sn|
+  FactoryGirl.create :track, album: nil
+end

data/spec/factories/tracks.rb

@@ -1,13 +1,13 @@
 FactoryGirl.define do
   factory :track do
     title
-    order 1
+    order
     album nil
   end
 
   factory :object_track do
     title
-    order 1
+    order
     album nil
   end
 

data/spec/factories/traits.rb

@@ -6,4 +6,8 @@ FactoryGirl.define do
   sequence :name do |n|
     "name #{rand(1000)} #{n}"
   end
+
+  sequence :order do |n|
+    rand(20)
+  end
 end

data/spec/lib/filter_parser_spec.rb

@@ -28,12 +28,18 @@ describe Listings do
     assert_parse_filter "album_name:'me 2' ", {album_name: "me 2"}, ""
 
     assert_parse_filter "album_name:me-1", {album_name: "me-1"}, ""
+
+    assert_parse_filter_with_keys "project_id:3", [:id, :project_id], {project_id:"3"}, ""
   end
 
   def assert_parse_filter(text, hash, left_text)
+    assert_parse_filter_with_keys(text, hash.keys, hash, left_text)
+  end
+
+  def assert_parse_filter_with_keys(text, keys, hash, left_text)
     listing = Listings::Base.new
 
-    filters, s = listing.parse_filter text, hash.keys
+    filters, s = listing.parse_filter text, keys
 
     s.should eq(left_text)
     filters.should eq(hash)

data/spec/spec_helper.rb

@@ -4,7 +4,7 @@ require File.expand_path("../dummy/config/environment", __FILE__)
 require 'rspec/rails'
 require 'rspec/autorun'
 require 'factory_girl_rails'
-require File.expand_path("../../lib/rspec", __FILE__)
+require File.expand_path("../../lib/listings/rspec", __FILE__)
 
 # Requires supporting ruby files with custom matchers and macros, etc,
 # in spec/support/ and its subdirectories.
@@ -42,5 +42,4 @@ RSpec.configure do |config|
   config.order = "random"
 
   config.include FactoryGirl::Syntax::Methods
-  config.include RSpec::ListingsHelpers, type: :listing
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: listings
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-22 00:00:00.000000000 Z
+date: 2015-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -210,12 +210,16 @@ files:
 - lib/listings/column_view.rb
 - lib/listings/configuration.rb
 - lib/listings/configuration_methods.rb
+- lib/listings/custom_filter_descriptor.rb
+- lib/listings/custom_filter_view.rb
 - lib/listings/dynamic_binding.rb
 - lib/listings/engine.rb
 - lib/listings/filter_descriptor.rb
 - lib/listings/filter_view.rb
 - lib/listings/filters/base.rb
 - lib/listings/kaminari_helpers_tag_patch.rb
+- lib/listings/rspec/listings_helpers.rb
+- lib/listings/rspec.rb
 - lib/listings/scope_descriptor.rb
 - lib/listings/sources/active_record_data_source.rb
 - lib/listings/sources/data_source.rb
@@ -224,8 +228,6 @@ files:
 - lib/listings/version.rb
 - lib/listings/view_helper_methods.rb
 - lib/listings.rb
-- lib/rspec/listings_helpers.rb
-- lib/rspec.rb
 - lib/tasks/listings_tasks.rake
 - LICENSE
 - Rakefile
@@ -265,6 +267,7 @@ files:
 - spec/dummy/config/environments/test.rb
 - spec/dummy/config/initializers/backtrace_silencers.rb
 - spec/dummy/config/initializers/inflections.rb
+- spec/dummy/config/initializers/listings.rb
 - spec/dummy/config/initializers/mime_types.rb
 - spec/dummy/config/initializers/secret_token.rb
 - spec/dummy/config/initializers/session_store.rb
@@ -313,18 +316,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 3767681349647885791
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 3767681349647885791
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23.2
@@ -367,6 +364,7 @@ test_files:
 - spec/dummy/config/environments/test.rb
 - spec/dummy/config/initializers/backtrace_silencers.rb
 - spec/dummy/config/initializers/inflections.rb
+- spec/dummy/config/initializers/listings.rb
 - spec/dummy/config/initializers/mime_types.rb
 - spec/dummy/config/initializers/secret_token.rb
 - spec/dummy/config/initializers/session_store.rb

data/lib/rspec.rb

@@ -1 +0,0 @@
-require "rspec/listings_helpers"