active_sort_order 0.9.0 → 0.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29d4251d6a9b034fe9354311a077024e119a7e5de8f15c566ce5e41671e8640a
-  data.tar.gz: 79e4e40796445bf88ee888289255989c8adbcfaecce2b44bb382363f38f29617
+  metadata.gz: 863fc9f8899a7aea2e126c5f482b1bb8d422513c644eaf26f4f58fbc52d82f6b
+  data.tar.gz: 81e3205c167c100991cbb2cf80a3528e6b4c471cfa63fa652d56572d5e981867
 SHA512:
-  metadata.gz: c6cd7b26a6bbc32d2c0c9e78631dffc95c31fb9d907cb36ca37e70b9fdead4b56c4041dc57f2271ef1ee59a8cc5c381b8cea87f14d7f62504ce572663928d193
-  data.tar.gz: c13ca12d41b8afe6247120dac2cc1c02a636e55c55a5852ddffbda4ddb2198599c66d399f1f134246ecb52014d327cd0cfaa0f53161a51c397612736a6dd15ad
+  metadata.gz: f222b38e5900633eb6b2925a33e58d15425848183501b8ff5ab22010ad8fcd68ab2429dbf4de6302dae3155f49026330aa6c41c95fc52b777e13e257045cb7e8
+  data.tar.gz: 85f20d93e24af7b65ffb9371605e18d8729c0b4e2e34d1ad7283bc51beed78016e924a77a55a081d19e90af8c8e81b38d3a010b243de67547337947a1aa88c53

data/CHANGELOG.md

@@ -1,10 +1,23 @@
 CHANGELOG
 ---------
 
-- Unreleased
-  * [View Diff](https://github.com/westonganger/active_sort_order/compare/v0.9.0...master)
+- **Unreleased - [View Diff](https://github.com/westonganger/active_sort_order/compare/v0.9.4...master)**
   * Nothing yet
-  
-- v0.9.0 - Jan 29, 2021
-  * [View Diff](https://github.com/westonganger/active_sort_order/compare/371fc82...v0.9.0)
+
+- **v0.9.4 - [View Diff](https://github.com/westonganger/active_sort_order/compare/v0.9.3...v0.9.4)**
+  * Improve error handling for sort_col_sql argument
+
+- **v0.9.3 - [View Diff](https://github.com/westonganger/active_sort_order/compare/v0.9.2...v0.9.3)**
+  * Allow ability to sort on multiple fields
+
+- **v0.9.2 - Apr 28, 2021 - [View Diff](https://github.com/westonganger/active_sort_order/compare/v0.9.1...v0.9.2)**
+  * Fix deprecation warning in Rails 6.1 for `reorder(nil)`
+
+- **v0.9.1 - Jan 31, 2021 - [View Diff](https://github.com/westonganger/active_sort_order/compare/v0.9.0...v0.9.1)**
+  * General Improvements
+  * Add Github Actions CI supporting multiple version of Ruby, Rails and multiple databases types
+  * Fix bugs with Rails 5.0 and 5.1
+  * Limit supports to Rails 5.0+. Tests were showing some failures with Rails 4.2 so I dropped it.
+
+- **v0.9.0 - Jan 29, 2021 - [View Diff](https://github.com/westonganger/active_sort_order/compare/371fc82...v0.9.0)**
   * Initial Release

data/README.md

@@ -1,92 +1,143 @@
 # Active Sort Order
 
 <a href="https://badge.fury.io/rb/active_sort_order" target="_blank"><img height="21" style='border:0px;height:21px;' border='0' src="https://badge.fury.io/rb/active_sort_order.svg" alt="Gem Version"></a>
-<a href='https://travis-ci.com/westonganger/active_sort_order' target='_blank'><img height='21' style='border:0px;height:21px;' src='https://api.travis-ci.org/westonganger/active_sort_order.svg?branch=master' border='0' alt='Build Status' /></a>
+<a href='https://github.com/westonganger/active_sort_order/actions' target='_blank'><img src="https://github.com/westonganger/active_sort_order/workflows/Tests/badge.svg" style="max-width:100%;" height='21' style='border:0px;height:21px;' border='0' alt="CI Status"></a>
 <a href='https://rubygems.org/gems/active_sort_order' target='_blank'><img height='21' style='border:0px;height:21px;' src='https://ruby-gem-downloads-badge.herokuapp.com/active_sort_order?label=rubygems&type=total&total_label=downloads&color=brightgreen' border='0' alt='RubyGems Downloads' /></a>
 
-Dead simple, fully customizable sorting pattern for ActiveRecord.
+The "easy-peasy" dynamic sorting pattern for ActiveRecord that your Rails apps deserve. Useful for Rails controllers with large data, pagination, etc.
 
-# Installation
+Features:
+
+- Full SQL compatibility
+- Dead Simple. Just [one concern with one scope](#additional-customizations).
+
+## Installation
 
 ```ruby
 gem 'active_sort_order'
 ```
 
-Then add `include ActiveSortOrder` to your ApplicationRecord or models.
+Then add `include ActiveSortOrder` to your ApplicationRecord or individual models.
 
 ```ruby
-### Preferred
 class ApplicationRecord < ActiveRecord::Base
   include ActiveSortOrder
 end
+```
 
-### OR for individual models
+## Dynamic Sorting
 
-class Post < ActiveRecord::Base
-  include ActiveSortOrder
-end
+This gem defines one scope on your models: `sort_order`
 
-### OR for all models without an ApplicationRecord model
+This method uses ActiveRecord's `reorder` under the hood, so any previously defined `order` will be removed upon calling `sort_order`
 
-# config/initializers/active_sort_order.rb
-ActiveSupport.on_load(:active_record) do
-  ### Load for all ActiveRecord models
-  include ActiveSortOrder
+In the below examples we are within a controller and are using the params as our variables:
+
+```ruby
+# app/controllers/posts_controller.rb
+
+case params[:sort]
+when "number_str"
+  sort_col_sql = "CAST(posts.number_str AS int)"
+when "user"
+  ### To sort on multiple fields pass in an Array
+  sort_col_sql = ["users.first_name", "users.last_name"] 
+else
+  sort_col_sql = params[:sort]
 end
+
+### Output combined sort order (if present) and secondary / base sort order
+Post.all.sort_order(sort_col_sql, params[:direction], base_sort_order: "lower(number) ASC, lower(code) ASC")
+
+### Output combined sort order (if present) AND applies the classes base_sort_order (if defined)
+Post.all.sort_order(sort_col_sql, params[:direction]) 
 ```
 
-# Usage
+## Sorting on multiple columns
 
-## Base Order
+##### Method Definition:
 
-You will likely want to define a `base_sort_order` class method to each model. 
+`sort_order(sort_col_sql = nil, sort_direction_sql = nil, base_sort_order: true)`
 
-This will be utilized when not providing a `:base_sort_order` argument.
+Options:
 
-```ruby
-def self.base_sort_order
-  "lower(#{table_name}.name) ASC, lower(#{table_name}.code) ASC" # for example
-end
-```
+- `sort_col_sql` is a SQL String of the column name
+  * Feel free to use any SQL manipulation on the column name
+  * There is no built-in SQL string validation so be sure to handle your sanitization in your project before passing to this method. See [Safely Handling Input](#safely-handling-input)
+  * If blank value provided it will skip the dynamic sort and just apply the `base_sort_order`
+- `sort_direction_sql` is a String of the SQL ORDER BY direction
+  * The SQL String is automatically validated within the few allowable SQL ORDER BY directions.
+  * If nil or "blank string" provided it will fallback to "ASC"
+- `base_sort_order` is a String of the SQL base ordering
+  * If not provided or true it will use the classes `base_sort_order` method (if defined)
+  * If nil or false is provided it will skip the classes `base_sort_order`
 
-## Sorting
+## Base Sort Order
 
-This gem defines one scope on your models: `sort_order`
+To maintain consistency when sorting its always a good idea to have a secondary or base sort order for when duplicates of the main sort column are found or no sort is provided.
 
-This method uses `reorder` so any previously defined `order` will be removed.
+For this you can define a `base_sort_order` class method to your models. 
 
-In the below examples:
+This will be utilized on the `sort_order` method when not providing a direct `:base_sort_order` argument.
 
- - `params[:sort]` is a String of the full SQL column name, feel free to use any SQL as required
- - `params[:direction]` is a String, if nil/blank string value provided it will fallback to "ASC"
+```ruby
+class Post < ActiveRecord::Base
+  include ActiveSortOrder
+
+  def self.base_sort_order
+    "lower(#{table_name}.name) ASC, lower(#{table_name}.code) ASC" # for example
+  end
+
+end
+```
+
+The default behaviours of this are shown below.
 
 ```ruby
 ### Applies the classes base_sort_order (if defined)
 Post.all.sort_order
 
-### Use custom base_sort_order
+### Override the classes base_sort_order
 Post.all.sort_order(base_sort_order: "lower(number) DESC")
+# OR
+Post.all.sort_order(sort_col_sql, params[:direction], base_sort_order: "lower(number) DESC")
 
-### Output combined sort order (if present) AND applies the classes base_sort_order (if defined)
-Post.all.sort_order(params[:sort], params[:direction]) 
+### Skip the classes base_sort_order by providing false, nil will still use classes base_sort_order
+Post.all.sort_order(sort_col_sql, params[:direction], base_sort_order: false) 
+```
+
+## Safely Handling Input
+
+When accepting params or any custom input for column names it is wise to safely map the field name/alias to the correct SQL string rather than directly sending in the params.
 
-### output combined sort order (if present) and applies a custom base_sort_order
-post.all.sort_order(params[:sort], params[:direction], base_sort_order: "lower(number) desc, lower(code) asc")
+Here is an example on how to handle this within your controller:
+
+```ruby
+if params[:sort].present?
+  case params[:sort]
+  when "author_name"
+    sort_col_sql = "authors.name"
+  when "a_or_b"
+    sort_col_sql = "COALESCE(posts.field_a, posts.field_b)"
+  when "price"
+    sort_col_sql = "CAST(REPLACE(posts.price, '$', ',', '') AS int)"
+  else
+    raise "Invalid Sort Column Given: #{params[:sort]}"
+  end
+end
 
-### Skip the classes base_sort_order by providing false or nil
-Post.all.sort_order(params[:sort], params[:direction], base_sort_order: false)
-Post.all.sort_order(params[:sort], params[:direction], base_sort_order: nil)
+Post.all.sort_order(sort_col_sql, params[:direction])
 ```
 
 ## Additional Customizations
 
-This gem is just ONE concern with ONE scope. I strongly encourage you to read the code for this library to understand how it works within your project so that you are capable of customizing the functionality later. You can always copy the code directly into your project for deeper project-specific customizations.
+This gem is just one concern with one scope. I encourage you to read the code for this library to understand how it works within your project so that you are capable of customizing the functionality later. You can always copy the code directly into your project for deeper project-specific customizations.
 
 - [lib/active_sort_order/concerns/sort_order_concern.rb](./lib/active_sort_order/concerns/sort_order_concern.rb)
 
 ## Helper / View Examples
 
-We do not provide built in helpers or view templates because this is a major restriction to applications. Instead we provide simple copy-and-pasteable starter templates
+We do not provide built in helpers or view templates because this is a major restriction to applications. Instead we provide a simple copy-and-pasteable starter template for the sort link:
 
 ```ruby
 ### app/helpers/application_helper.rb
@@ -135,6 +186,6 @@ Then use the link helper within your views like:
 </th>
 ```
 
-# Credits
+## Credits
 
 Created & Maintained by [Weston Ganger](https://westonganger.com) - [@westonganger](https://github.com/westonganger)

data/Rakefile

@@ -14,7 +14,11 @@ task default: [:test]
 task :console do
   require 'active_sort_order'
 
-  require 'test/dummy_app/app/models/post'
+  require_relative 'test/dummy_app/app/models/application_record.rb'
+  require_relative 'test/dummy_app/app/models/post.rb'
+  Dir.glob("test/dummy_app/app/models/*.rb").each do |f|
+    require_relative(f)
+  end
 
   require 'irb'
   binding.irb

data/lib/active_sort_order/concerns/sort_order_concern.rb

@@ -4,22 +4,29 @@ module ActiveSortOrder
 
     included do
       
-      scope :sort_order, ->(sort_str = nil, sort_direction = nil, base_sort_order: "NONE"){
-        if [String, Symbol, NilClass].none?{|x| sort_str.is_a?(x) }
-          raise ArgumentError.new("Invalid first argument `sort_str`, expecting a a String or Symbol")
+      scope :sort_order, ->(sort_col_sql = nil, sort_direction_sql = nil, base_sort_order: true){
+        if !sort_col_sql.is_a?(Array)
+          sort_col_sql = [sort_col_sql].compact
         end
 
-        if sort_str.present?
-          sort_str = sort_str.to_s
+        sort_col_sql.each_with_index do |x, i|
+          if [String, Symbol].exclude?(x.class)
+            raise ArgumentError.new("Invalid first argument `sort_col_sql`, expecting a String or Symbol or Array")
+          else
+            sort_col_sql[i] = x.to_s
+          end
+        end
 
-          if sort_direction.is_a?(Symbol)
-            sort_direction = sort_direction.to_s.gsub('_', ' ')
+        if sort_col_sql.present?
+          ### SORT DIRECTION HANDLING
+          if sort_direction_sql.is_a?(Symbol)
+            sort_direction_sql = sort_direction_sql.to_s.gsub('_', ' ')
           end
 
-          if sort_direction.nil? || (sort_direction.is_a?(String) && sort_direction == "")
-            sort_direction = "ASC"
-          elsif !sort_direction.is_a?(String)
-            raise ArgumentError.new("Invalid second argument `sort_direction` #{sort_direction}, expecting a a String or Symbol")
+          if sort_direction_sql.nil? || (sort_direction_sql.is_a?(String) && sort_direction_sql == "")
+            sort_direction_sql = "ASC"
+          elsif !sort_direction_sql.is_a?(String)
+            raise ArgumentError.new("Invalid second argument `sort_direction_sql`, expecting a String or Symbol")
           else
             valid_directions = [
               "ASC",
@@ -30,22 +37,32 @@ module ActiveSortOrder
               "DESC NULLS LAST",
             ].freeze
 
-            sanitized_sort_direction = sort_direction.split(' ').join(' ')
+            orig_direction_sql = sort_direction_sql
 
-            if !valid_directions.include?(sanitized_sort_direction.upcase)
-              raise ArgumentError.new("Invalid second argument `sort_direction` #{sort_direction}")
+            ### REMOVE DUPLICATE BLANKS - Apparently this also removes "\n" and "\t"
+            sort_direction_sql = orig_direction_sql.split(' ').join(' ')
+
+            if !valid_directions.include?(sort_direction_sql.upcase)
+              raise ArgumentError.new("Invalid second argument `sort_direction_sql`: #{orig_direction_sql}")
             end
           end
 
-          sql_str = "#{sort_str} #{sanitized_sort_direction}"
-        end
-
-        if base_sort_order == "NONE" && self.klass.respond_to?(:base_sort_order)
-          base_sort_order = self.klass.base_sort_order
+          sql_str = sort_col_sql.map{|x| "#{x} #{sort_direction_sql}" }.join(", ")
         end
+        
+        ### BASE SORT ORDER HANDLING
+        if base_sort_order == true
+          if self.respond_to?(:base_sort_order)
+            base_sort_order = self.base_sort_order
 
-        if base_sort_order && !base_sort_order.is_a?(String)
-          raise ArgumentError.new("Invalid :base_sort_order #{base_sort_order}, expecting a String")
+            if [String, NilClass, FalseClass].exclude?(base_sort_order.class)
+              raise ArgumentError.new("Invalid value returned from class method `base_sort_order`")
+            end
+          else
+            base_sort_order = nil
+          end
+        elsif base_sort_order && !base_sort_order.is_a?(String)
+          raise ArgumentError.new("Invalid argument provided for :base_sort_order")
         end
 
         if base_sort_order.present?
@@ -56,9 +73,13 @@ module ActiveSortOrder
           end
         end
 
-        sanitized_str = sql_str.blank? ? nil : Arel.sql(sanitize_sql_for_order(sql_str))
+        if sql_str.blank?
+          next self.where(nil)
+        else
+          sanitized_str = Arel.sql(sanitize_sql_for_order(sql_str))
 
-        next self.reorder(sanitized_str)
+          next self.reorder(sanitized_str)
+        end
       }
 
     end

data/lib/active_sort_order/version.rb

@@ -1,3 +1,3 @@
 module ActiveSortOrder
-  VERSION = "0.9.0".freeze
+  VERSION = "0.9.4".freeze
 end

data/test/dummy_app/config/application.rb

@@ -1,10 +1,5 @@
 require File.expand_path('../boot', __FILE__)
 
-require 'warning'
-Warning.ignore(
-  %r{mail/parsers/address_lists_parser}, ### Hide mail gem warnings
-)
-
 require 'rails/all'
 
 Bundler.require

data/test/dummy_app/config/database.yml

@@ -1,11 +1,20 @@
 default: &default
+<% if defined?(SQLite3) %>
   adapter: sqlite3
-  encoding: unicode
+  database: db/test.sqlite3
+
+<% elsif defined?(Mysql2) %>
+  adapter: mysql2
+  database: active_sort_order_test
+
+<% elsif defined?(PG) %>
+  adapter: postgresql
+  database: active_sort_order_test
+
+<% end %>
 
 development:
   <<: *default
-  database: db/dev.sqlite3
 
 test:
   <<: *default
-  database: db/test.sqlite3

data/test/dummy_app/config/environments/test.rb

@@ -9,7 +9,7 @@ Dummy::Application.configure do
 
   # Configure static asset server for tests with Cache-Control for performance
   config.serve_static_files = true
-  config.public_file_server.headers = { 'Cache-Control' => 'public, max-age=3600' }
+  config.public_file_server.enabled = true
 
   # Log error messages when you accidentally call methods on nil
   config.whiny_nils = true

data/test/dummy_app/db/migrate/20210128155312_set_up_test_tables.rb

@@ -1,4 +1,10 @@
-class SetUpTestTables < ActiveRecord::Migration::Current
+if defined?(ActiveRecord::Migration::Current)
+  migration_klass = ActiveRecord::Migration::Current
+else
+  migration_klass = ActiveRecord::Migration
+end
+
+class SetUpTestTables < migration_klass
 
   def change
     create_table :posts do |t|