actionset 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ee8a50300e9e0918965a3c32ec78d1f740233add
-  data.tar.gz: 27789ef2fb5e1ff75f1a58ca0bc29c0f4d6fb938
+  metadata.gz: 15622f077374c1ce7a76dea96c6523f1418e0f6d
+  data.tar.gz: a4054979eea205a3ee260f3781372dd9682411b7
 SHA512:
-  metadata.gz: 66d724b335536136cd5ac2efdcaf644cf9586ae7f837a51dbf9acf8da6042b664ad9a1da5307f3b8c9f8e6c8ac3e7d031199dc893ad7baf5c04856302435a554
-  data.tar.gz: 304690a7e523c824c230349eeced3bf0871adb9bcb98614cc538960982e564612f16a72301440df0ddf45c2ebb5935e31b903677d2ab6f71b6f8d70d32e56b9d
+  metadata.gz: ddc6b85bc1518198c5528dc983c8e820aafaf8051a609e3b5a8a0c8ee62d42108d821f87d46ac630ed815f0b481105c8bfbc4d2b8699e32fd599aa362fffc334
+  data.tar.gz: 282a1915bfc5868e9ffce1df55425210f530469e54a3f6ace1536b95c652c21376b38db41f98dca593bab6a514fd1157af84afdbf4a9ad928fe3818a9933486f

data/.rubocop.yml

@@ -1,11 +1,5 @@
 AllCops:
   TargetRubyVersion: 2.3
-  Include:
-    - Rakefile
-  Exclude:
-    - bin/*
-    - db/**/*
-    - spec/*_helper.rb
 Metrics/LineLength:
   Max: 120
   # To make it possible to copy or click on URIs in the code, we allow lines
@@ -20,6 +14,10 @@ Style/SignalException:
   EnforcedStyle: semantic
 Metrics/BlockLength:
   Exclude:
-    - 'actionset.gemspec'
+    - 'activeset.gemspec'
     - 'spec/**/*_spec.rb'
     - '**/schema.rb'
+Naming/VariableNumber:
+  EnforcedStyle: snake_case
+Style/DateTime:
+  AllowCoercion: true

data/.travis.yml

@@ -1,5 +1,9 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.3.1
-before_install: gem install bundler -v 1.15.4
+  - 2.4.1
+before_install:
+  - gem install bundler -v 1.15.4
+  - export TZ=America/New_York
+after_success:
+  - bash < (curl -s https://codecov.io/bash)

data/CHANGELOG

@@ -1,3 +1,16 @@
+v 0.7.0
+  - overhaul the specs
+    + update the data model to be more extensive and expressive
+    + update to the new FactoryBot gem
+    + write programmatic specs for extensive coverage
+    + ensure factories don't have duplicate attributes
+    + add specs for ARel operators in filtering
+  - update the README
+  - add another exception to the Ruby typcaster (`to_onum`)
+  - update dependency on ActiveSet to 0.8.x
+v 0.6.0
+  - Refactor to work with versions 0.7.x of ActiveSet
+  - Move and rename the typecasting class for attribute values
 v 0.5.4
   - Allow the `form_for_object_from_param` helper to accept defaults hash
 v 0.5.3

data/README.md

@@ -1,11 +1,14 @@
 # ActionSet
 
+[![Build Status](https://travis-ci.com/fractaledmind/actionset.svg?branch=master)](https://travis-ci.com/fractaledmind/actionset)
+[![codecov](https://codecov.io/gh/fractaledmind/actionset/branch/master/graph/badge.svg)](https://codecov.io/gh/fractaledmind/actionset)
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'actionset'
+gem 'actionset', require: 'action_set'
 ```
 
 And then execute:
@@ -18,7 +21,92 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+In order to make the **`ActionSet`** helper methods available to your application, you need to `include` the module into your `ApplicationController`.
+
+```ruby
+class ApplicationController < ActionController::Base
+    include ActionSet
+end
+```
+
+Or, if you only want or need **`ActionSet`** in certain controllers, you can `include` the module directly into those controllers.
+
+The simplest setup is to use the `process_set` helper method in your `index` action. Typically, `index` actions look something like the following:
+
+```ruby
+def index
+  @things = Thing.all
+end
+```
+
+In order to wire up the filtering, sorting, and paginating behaviors, we simply need to update our `index` action to:
+
+```ruby
+def index
+  @things = process_set(Thing.all)
+end
+```
+
+Now, `@things` will be properly filtered, sorted, and paginated according to the request parameters.
+
+> **Note:** `process_set` applies pagination and will paginate your collection regardless of the request parameters. Unless there are request parameters overriding the defaults, your collection will be paginated to 25 items per page showing the first 25 items (page 1). If you want to only filter and sort _without_ paginating, simply use the `filter_set` and `sort_set` helper methods directly, e.g. `sort_set(filter_set(Thing.all))`
+
+> **Note:** If you use some authorization library, like [`Pundit`](https://github.com/varvet/pundit), which applies authorization scoping to your `index` action, you can compose that behavior with **`ActionSet`** easily:
+> ```ruby
+> def index
+>   @things = process_set(policy_scope(Thing.all))
+> end
+> ```
+
+In addition to filtering, sorting, and paginating, **`ActionSet`** provides exporting functionality via the `export_set` helper method. One common use case is to have an `index` action that renders a filtered, sorted, and paginated collection, but allows for a CSV export as well. In such cases, you typically want the HTML collection to be paginated, but the CSV not to be. This behavior is also relatively simple to achieve:
+
+```ruby
+def index
+  things = sort_set(filter_set(Thing.all))
+
+  respond_to do |f|
+    f.html  { @things = paginate_set(things) }
+    f.csv   { export_set(things) }
+  end
+end
+```
+
+With our controller properly wired up, we now simply need to have our views submitting request parameters in the shape that **`ActionSet`** expects. **`ActionSet`** provides view helpers to simplify such work.
+
+Sorting is perhaps the simplest to setup. To create an (ARIA accessible) anchor link to sort by some particular attribute, use the `sort_link_for` view helper. You pass the attribute name (or dot-separated path), and then can add the text for the link (defaults to title-casing your attribute) and/or any HTML attributes you'd like added to the anchor link. A notable feature of the `sort_link_for` helper is that it intelligently infers the sort direction from whatever the current request state is. That is, if no sorting has been applied for that attribute, the link will apply sorting to that attribute in the _ascending_ direction. If sorting is currently being applied for that attribute in the _ascending_ direction, the link will apply sorting to that attribute in the _descending_ direction, and vice versa.
+
+Filtering is somewhat more involved. **`ActionSet`** expects filters to be placed under the `filter` request parameter, aside from that one expectation, we leave all other view layer implementation details up to you. You can build your filtering interface however best fits your application. However, if you need a simple default, we suggest the following pattern: a simple form on your `index` action view that simply reloads that action with whatever filter params the user has submitted. In Rails, building such a form is relatively simple:
+
+```erb
+<%= form_for(form_for_object_from_param(:filter),
+             method: :get,
+             url: things_path) do |form| %>
+  <div class="form-group">
+    <%= form.label(:attribute, class: 'control-label') %>
+    <%= form.text_field(:attribute, class: 'form-control') %>
+  </div>
+
+  <div class="text-right">
+    <%= form.submit 'Save', class: 'btn btn-primary' %>
+  </div>
+<% end %>
+```
+
+We tell the `form_for` helper to make a `GET` request back to our `index` action (`things_path` in this example). The only odd bit is what we pass as the object to `form_for`; you will note we pass `form_for_object_from_param(:filter)`. This `form_for_object_from_param` view helper is provided by **`ActionSet`** and does precisely what it says—it provides an object (an `OpenStruct` object to be precise) that encodes whatever request parameters are nested under the param name given, where that object will work properly with the `form_for` helper. This view helper allows us to build forms we the user's filter inputs will be retained across searches.
+
+For pagination, like filtering, we don't enforce any view-layer specifics. You simply need to pass request parameters under the `paginate` param, specifically the `page` and `size` params. However, **`ActionSet`** does provide a simple default pagination UI component via the `pagination_links_for` view helper. You simply pass your processed set to this view helper, and it will render HTML in this structure:
+
+![alt text](https://raw.githubusercontent.com/fractaledmind/actionset/master/pagination.png)
+
+```html
+<nav class="pagination" aria-label="Page navigation">
+    <a class="page-link page-first" href="/foos?paginate%5Bpage%5D=1">« First</a>
+    <a rel="prev" class="page-link page-prev" href="/foos?paginate%5Bpage%5D=1">‹ Prev</a>
+    <span class="page-current">Page&nbsp;<strong>2</strong>&nbsp;of&nbsp;<strong>3</strong></span>
+    <a rel="next" class="page-link page-next" href="/foos?paginate%5Bpage%5D=3">Next ›</a>
+    <a class="page-link page-last" href="/foos?paginate%5Bpage%5D=3">Last »</a>
+</nav>
+```
 
 ## Development
 

data/actionset.gemspec

@@ -5,7 +5,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = 'actionset'
-  spec.version       = '0.6.0'
+  spec.version       = '0.7.0'
   spec.authors       = ['Stephen Margheim']
   spec.email         = ['stephen.margheim@gmail.com']
 
@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'activeset', '>= 0.7.1'
+  spec.add_dependency 'activeset', '>= 0.8.0'
   spec.add_dependency 'activesupport', '>= 4.0.2'
   spec.add_dependency 'railties'
 
@@ -32,8 +32,9 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'database_cleaner'
   spec.add_development_dependency 'capybara'
   spec.add_development_dependency 'combustion'
-  spec.add_development_dependency 'factory_girl'
+  spec.add_development_dependency 'factory_bot'
   spec.add_development_dependency 'faker'
   spec.add_development_dependency 'simplecov'
   spec.add_development_dependency 'simplecov-console'
+  spec.add_development_dependency 'ransack'
 end

data/lib/action_set.rb

@@ -24,7 +24,7 @@ module ActionSet
 
     def filter_set(set)
       active_set = ensure_active_set(set)
-      active_set = active_set.filter(filter_structure(set)) if filter_params.any?
+      active_set = active_set.filter(filter_instructions_for(set)) if filter_params.any?
       active_set
     end
 
@@ -34,49 +34,67 @@ module ActionSet
       active_set
     end
 
+    # TODO: should we move the default value setting to this layer,
+    # and have ActiveSet require instructions for pagination?
     def paginate_set(set)
       active_set = ensure_active_set(set)
-      active_set = active_set.paginate(paginate_structure)
+      active_set = active_set.paginate(paginate_instructions)
       active_set
     end
 
     def export_set(set)
       return send_file(set, export_set_options(request.format)) if set.is_a?(String) && File.file?(set)
+
       active_set = ensure_active_set(set)
-      exported_data = active_set.export(export_structure)
+      exported_data = active_set.export(export_instructions)
       send_data(exported_data, export_set_options(request.format))
     end
 
     private
 
-    def filter_structure(set)
-      filter_params.flatten_keys.reject { |_, v| v.blank? }.each_with_object({}) do |(keypath, value), memo|
-        instruction = ActiveSet::AttributeInstruction.new(keypath, value)
-        item_with_value = set.find { |i| !instruction.value_for(item: i).nil? }
-        item_value = instruction.value_for(item: item_with_value)
-        typecast_value = ActionSet::AttributeValue.new(value)
-                           .cast(to: item_value.class)
+    def filter_instructions_for(set)
+      filter_params.flatten_keys.reject { |_, v| v.try(:empty?) }.each_with_object({}) do |(keypath, value), memo|
+        typecast_value = if value.respond_to?(:each)
+                           value.map { |v| filter_typecasted_value_for(keypath, v, set) }
+                         else
+                           filter_typecasted_value_for(keypath, value, set)
+                         end
 
         memo[keypath] = typecast_value
       end
     end
 
-    def paginate_structure
+    def filter_typecasted_value_for(keypath, value, set)
+      instruction = ActiveSet::AttributeInstruction.new(keypath, value)
+      item_with_value = set.find { |i| !instruction.value_for(item: i).nil? }
+      item_value = instruction.value_for(item: item_with_value)
+      ActionSet::AttributeValue.new(value)
+                               .cast(to: item_value.class)
+    end
+
+    def paginate_instructions
       paginate_params.transform_values(&:to_i)
     end
 
-    def export_structure
+    def export_instructions
       {}.tap do |struct|
         struct[:format] = export_params[:format] || request.format.symbol
         columns_params = export_params[:columns]&.map do |column|
           Hash[column&.map do |k, v|
             is_literal_value = ->(key) { key.to_s == 'value*' }
-            key = is_literal_value.(k) ? 'value' : k
-            val = is_literal_value.(k) ? send(v) : v
+            key = is_literal_value.call(k) ? 'value' : k
+            val = is_literal_value.call(k) ? send(v) : v
             [key, val]
           end]
         end
-        struct[:columns] = columns_params || send(:export_set_columns) || []
+
+        struct[:columns] = if columns_params&.any?
+                             columns_params
+                           elsif respond_to?(:export_set_columns, true)
+                             send(:export_set_columns)
+                           else
+                             [{}]
+                           end
       end
     end
 

data/lib/action_set/attribute_value.rb

@@ -46,7 +46,7 @@ module ActionSet
         @possible_typecasters ||= String.instance_methods
                                         .map(&:to_s)
                                         .select { |m| m.start_with? 'to_' }
-                                        .reject { |m| %[to_v8].include? m }
+                                        .reject { |m| %w[to_v8 to_onum].include? m }
       end
 
       def typecast(method_name)
@@ -144,10 +144,12 @@ module ActionSet
       def process
         return if @raw.is_a? @target
         return unless @target.eql?(ActiveSupport::TimeWithZone)
+
         time_value = ActiveModelAdapter.new(@raw, Time).process
 
         return unless time_value.is_a?(Time)
         return time_value unless time_value.respond_to?(:in_time_zone)
+
         time_value.in_time_zone
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: actionset
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Stephen Margheim
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-11-08 00:00:00.000000000 Z
+date: 2018-12-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activeset
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.7.1
+        version: 0.8.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.7.1
+        version: 0.8.0
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -151,7 +151,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: factory_girl
+  name: factory_bot
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -206,6 +206,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ransack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Easily filter, sort, and paginate enumerable sets via web requests.
 email:
 - stephen.margheim@gmail.com
@@ -248,6 +262,7 @@ files:
 - lib/action_set/helpers/sort/link_for_helper.rb
 - lib/action_set/helpers/sort/next_direction_for_helper.rb
 - lib/action_set/helpers/sort/path_for_helper.rb
+- pagination.png
 homepage: https://github.com/fractaledmind/actionset
 licenses:
 - MIT