active_sort_order 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 29d4251d6a9b034fe9354311a077024e119a7e5de8f15c566ce5e41671e8640a
+  data.tar.gz: 79e4e40796445bf88ee888289255989c8adbcfaecce2b44bb382363f38f29617
+SHA512:
+  metadata.gz: c6cd7b26a6bbc32d2c0c9e78631dffc95c31fb9d907cb36ca37e70b9fdead4b56c4041dc57f2271ef1ee59a8cc5c381b8cea87f14d7f62504ce572663928d193
+  data.tar.gz: c13ca12d41b8afe6247120dac2cc1c02a636e55c55a5852ddffbda4ddb2198599c66d399f1f134246ecb52014d327cd0cfaa0f53161a51c397612736a6dd15ad

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+CHANGELOG
+---------
+
+- Unreleased
+  * [View Diff](https://github.com/westonganger/active_sort_order/compare/v0.9.0...master)
+  * Nothing yet
+  
+- v0.9.0 - Jan 29, 2021
+  * [View Diff](https://github.com/westonganger/active_sort_order/compare/371fc82...v0.9.0)
+  * Initial Release

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Weston Ganger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,140 @@
+# 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://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.
+
+# Installation
+
+```ruby
+gem 'active_sort_order'
+```
+
+Then add `include ActiveSortOrder` to your ApplicationRecord or models.
+
+```ruby
+### Preferred
+class ApplicationRecord < ActiveRecord::Base
+  include ActiveSortOrder
+end
+
+### OR for individual models
+
+class Post < ActiveRecord::Base
+  include ActiveSortOrder
+end
+
+### OR for all models without an ApplicationRecord model
+
+# config/initializers/active_sort_order.rb
+ActiveSupport.on_load(:active_record) do
+  ### Load for all ActiveRecord models
+  include ActiveSortOrder
+end
+```
+
+# Usage
+
+## Base Order
+
+You will likely want to define a `base_sort_order` class method to each model. 
+
+This will be utilized when not providing a `:base_sort_order` argument.
+
+```ruby
+def self.base_sort_order
+  "lower(#{table_name}.name) ASC, lower(#{table_name}.code) ASC" # for example
+end
+```
+
+## Sorting
+
+This gem defines one scope on your models: `sort_order`
+
+This method uses `reorder` so any previously defined `order` will be removed.
+
+In the below examples:
+
+ - `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
+### Applies the classes base_sort_order (if defined)
+Post.all.sort_order
+
+### Use custom base_sort_order
+Post.all.sort_order(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]) 
+
+### 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")
+
+### 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)
+```
+
+## 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.
+
+- [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
+
+```ruby
+### app/helpers/application_helper.rb
+
+module ApplicationHelper
+
+  def sort_link(column, title = nil, opts = {})
+    column = column.to_s
+
+    if title && title.is_a?(Hash)
+      opts = title
+      title = opts[:title]
+    end
+
+    title ||= column.titleize
+
+    if opts[:disabled]
+      return title
+    else
+      if params[:direction].present? && params[:sort].present?
+        direction = (column == params[:sort] && params[:direction] == "asc") ? "desc" : "asc"
+      else
+        direction = "asc"
+      end
+
+      return link_to(title, params.to_unsafe_h.merge(sort: column, direction: direction))
+    end
+  end
+
+end
+```
+
+Then use the link helper within your views like:
+
+```erb
+<th>
+  <%= sort_link :name %>
+</th>
+
+<th>
+  <%= sort_link "companies.name", "Company Name" %>
+</th>
+
+<th>
+  <%= sort_link "companies.name", "Company Name", disabled: !@sort_enabled %>
+</th>
+```
+
+# Credits
+
+Created & Maintained by [Weston Ganger](https://westonganger.com) - [@westonganger](https://github.com/westonganger)

data/Rakefile

@@ -0,0 +1,21 @@
+require File.expand_path(File.dirname(__FILE__) + '/lib/active_sort_order/version.rb')
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: [:test]
+
+task :console do
+  require 'active_sort_order'
+
+  require 'test/dummy_app/app/models/post'
+
+  require 'irb'
+  binding.irb
+end

data/lib/active_sort_order.rb

@@ -0,0 +1,11 @@
+require "active_record"
+
+require "active_sort_order/concerns/sort_order_concern"
+
+module ActiveSortOrder 
+  extend ActiveSupport::Concern
+
+  included do
+    include ActiveSortOrder::SortOrderConcern
+  end
+end

data/lib/active_sort_order/concerns/sort_order_concern.rb

@@ -0,0 +1,67 @@
+module ActiveSortOrder
+  module SortOrderConcern
+    extend ActiveSupport::Concern
+
+    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")
+        end
+
+        if sort_str.present?
+          sort_str = sort_str.to_s
+
+          if sort_direction.is_a?(Symbol)
+            sort_direction = sort_direction.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")
+          else
+            valid_directions = [
+              "ASC",
+              "DESC",
+              "ASC NULLS FIRST",
+              "ASC NULLS LAST",
+              "DESC NULLS FIRST",
+              "DESC NULLS LAST",
+            ].freeze
+
+            sanitized_sort_direction = sort_direction.split(' ').join(' ')
+
+            if !valid_directions.include?(sanitized_sort_direction.upcase)
+              raise ArgumentError.new("Invalid second argument `sort_direction` #{sort_direction}")
+            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
+        end
+
+        if base_sort_order && !base_sort_order.is_a?(String)
+          raise ArgumentError.new("Invalid :base_sort_order #{base_sort_order}, expecting a String")
+        end
+
+        if base_sort_order.present?
+          if sql_str.present?
+            sql_str << ", #{base_sort_order}"
+          else
+            sql_str = base_sort_order
+          end
+        end
+
+        sanitized_str = sql_str.blank? ? nil : Arel.sql(sanitize_sql_for_order(sql_str))
+
+        next self.reorder(sanitized_str)
+      }
+
+    end
+
+  end
+end

data/lib/active_sort_order/version.rb

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

data/test/dummy_app/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Dummy::Application.load_tasks

data/test/dummy_app/app/assets/config/manifest.js

@@ -0,0 +1,3 @@
+//= link_tree ../images
+//= link_directory ../javascripts .js
+//= link_directory ../stylesheets .css .scss

data/test/dummy_app/app/assets/stylesheets/application.css

@@ -0,0 +1,3 @@
+/*
+ *= require_self
+*/

data/test/dummy_app/app/controllers/application_controller.rb

@@ -0,0 +1,3 @@
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+end

data/test/dummy_app/app/models/application_record.rb

@@ -0,0 +1,3 @@
+class ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
+end

data/test/dummy_app/app/models/post.rb

@@ -0,0 +1,3 @@
+class Post < ApplicationRecord
+  include ActiveSortOrder
+end

data/test/dummy_app/app/models/post_with_base_order_a.rb

@@ -0,0 +1,7 @@
+class PostWithBaseOrderA < Post
+
+  def self.base_sort_order
+    "posts.a ASC"
+  end
+
+end

data/test/dummy_app/app/models/post_with_base_order_a_and_b.rb

@@ -0,0 +1,7 @@
+class PostWithBaseOrderAAndB < Post
+
+  def self.base_sort_order
+    "posts.a ASC, posts.b ASC"
+  end
+
+end

data/test/dummy_app/app/models/post_with_base_order_b.rb

@@ -0,0 +1,7 @@
+class PostWithBaseOrderB < Post
+
+  def self.base_sort_order
+    "posts.b ASC"
+  end
+
+end

data/test/dummy_app/app/models/post_with_base_order_b_and_a.rb

@@ -0,0 +1,7 @@
+class PostWithBaseOrderBAndA < Post
+
+  def self.base_sort_order
+    "posts.b ASC, posts.a ASC"
+  end
+
+end

data/test/dummy_app/app/models/post_with_volatile_base_order.rb

@@ -0,0 +1,7 @@
+class PostWithVolatileBaseOrder < Post
+
+  def self.base_sort_order
+    # Will be overwritten in tests
+  end
+
+end

data/test/dummy_app/app/views/layouts/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Dummy App</title>
+  <%= stylesheet_link_tag    "application" %>
+  <%= javascript_include_tag "application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/test/dummy_app/config.ru

@@ -0,0 +1,4 @@
+# This file is used by Rack-based servers to start the application.
+
+require ::File.expand_path('../config/environment',  __FILE__)
+run Dummy::Application

data/test/dummy_app/config/application.rb

@@ -0,0 +1,66 @@
+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
+
+module Dummy
+  class Application < Rails::Application
+    # Settings in config/environments/* take precedence over those specified here.
+    # Application configuration should go into files in config/initializers
+    # -- all .rb files in that directory are automatically loaded.
+
+    # Custom directories with classes and modules you want to be autoloadable.
+    # config.autoload_paths += %W(#{config.root}/extras)
+
+    # Only load the plugins named here, in the order given (default is alphabetical).
+    # :all can be used as a placeholder for all plugins not explicitly named.
+    # config.plugins = [ :exception_notification, :ssl_requirement, :all ]
+
+    # Activate observers that should always be running.
+    # config.active_record.observers = :cacher, :garbage_collector, :forum_observer
+
+    # Set Time.zone default to the specified zone and make Active Record auto-convert to this zone.
+    # Run "rake -D time" for a list of tasks for finding time zone names. Default is UTC.
+    # config.time_zone = 'Central Time (US & Canada)'
+
+    # The default locale is :en and all translations from config/locales/*.rb,yml are auto loaded.
+    # config.i18n.load_path += Dir[Rails.root.join('my', 'locales', '*.{rb,yml}').to_s]
+    # config.i18n.default_locale = :de
+
+    # Configure the default encoding used in templates for Ruby 1.9.
+    config.encoding = "utf-8"
+
+    # Configure sensitive parameters which will be filtered from the log file.
+    config.filter_parameters += [:password]
+
+    # Enable the asset pipeline
+    config.assets.enabled = true
+
+    config.assets.quiet = true
+
+    # Version of your assets, change this if you want to expire all your assets
+    config.assets.version = '1.0'
+
+    config.generators.test_framework = false
+    config.generators.helper = false
+    config.generators.stylesheets = false
+    config.generators.javascripts = false
+
+    config.after_initialize do
+      ActiveRecord::Migration.migrate(Rails.root.join("db/migrate/*").to_s)
+    end
+
+    if ActiveRecord.respond_to?(:gem_version)
+      gem_version = ActiveRecord.gem_version
+      if gem_version.to_s.start_with?("5.2.")
+        config.active_record.sqlite3.represent_boolean_as_integer = true
+      end
+    end
+  end
+end