openstax_utilities 3.0.0 → 4.0.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NTE4ZjlhOTM0OTAxNzhhMTI2ZWU0ODhiNTIwZTAxZTk3ZGYyOTc0OA==
+    NjczMjZiNWYzMjljMzM4ZjMyM2FlYjg2MGMxNzhlZDUxODNiOWY1MQ==
   data.tar.gz: !binary |-
-    MmE0MTg2ZWRhNWRlMDViMjZjODc5NTM2OGYzYjJmZDdlMDI4Y2QzZQ==
+    ZDMzZDg3N2E2MzRmZjYzNDIxYjA5YjNiOTNmYjBkODllNjM1ODE0ZA==
 SHA512:
   metadata.gz: !binary |-
-    YjkxMmQ2MGJmMjAyMDczNWJmZmExNzk1ODBhZDRjODYyOTNmMmRiZDE5OWZh
-    ZDljYzY5OTkzMTJiZWVjZTBhYWYxODQ2YjQ1Mzc5N2ExNjg4NmIzOTU0YWI4
-    OGFkYTI4N2QyMjk1ZTBiNzk5ZmI3OGNiNTY2ZTQzY2VlOWU0NWI=
+    NzA2YTc4MGI1ZDhjZmU0ZWVlMzc3YzAzMDBlMGZjMzZjODE4NDNjZGNlNzRj
+    YTNkYzU0NDA2YTgzOWUxNTkxZWEzYjZmODAxNDRkOTc0MDZjNzVlMGMwYzYy
+    ZGY0NzQxMGI2ZTJkNWNhMzI3ZGRhOWYwYjRkZDdkNTYzMGQwMWI=
   data.tar.gz: !binary |-
-    YjliMzBmNTk3YjNmMWQyYTE4ZTM4OTc1YmRlZWYyMGZiZTIwMjhmNzFiY2Jh
-    ZjAzMGJhOTk3ODExNzY0NDliM2QxY2JkYjhmNTMyZmVhZDdhZDBmN2M1NmFh
-    OWMzYWY4OTkzY2YzYmY0MmRjZGQ2YTdjOWQyZTQyNjE0OTIzYTI=
+    MzZiN2YyYzBmMTRhOTMzNDFkNTA2MWZiY2JlZDFmZWVmNGJhZGJiN2YwYmM3
+    OGUzYThkOGIxMTQ1ZmY1MDljNTQ5NTZlNTVjNWVlZmQ4N2ZlNGUyM2E0NDg4
+    NGQxMDM1ZWMyNzYwNmFiNWY4MTE1M2VmYjI4YjVkZjM3NGE3NDA=

data/Rakefile

@@ -1,11 +1,12 @@
 #!/usr/bin/env rake
+
 begin
   require 'bundler/setup'
 rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
 
-APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+APP_RAKEFILE = File.expand_path('../spec/dummy/Rakefile', __FILE__)
 load 'rails/tasks/engine.rake'
 
 Bundler::GemHelper.install_tasks
@@ -13,7 +14,7 @@ Bundler::GemHelper.install_tasks
 require 'rspec/core'
 require 'rspec/core/rake_task'
 
-desc "Run all specs in spec directory (excluding plugin specs)"
+desc 'Run all specs in spec directory (excluding plugin specs)'
 RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
 
-task :default => :spec
+task :default => :spec

data/app/handlers/openstax/utilities/abstract_keyword_search_handler.rb

@@ -0,0 +1,92 @@
+# Database-agnostic keyword searching handler
+#
+# Keywords have the format keyword:value
+# Keywords can also be negated with -, as in -keyword:value
+# Values are comma-separated, while keywords are space-separated
+# See https://github.com/bruce/keyword_search for more information
+#
+# Subclasses must set the search_routine class variable,
+# as well as the authorized? method
+#
+# Required:
+#
+#   search_routine - the Lev::Routine that will handle the search
+#
+# Optional (recommended to prevent scraping):
+#
+#   min_characters - the minimum number of characters allowed in the query
+#                    only an error will be returned if the query has less
+#                    than the minimum number of characters allowed
+#                    default: nil (disabled)
+#
+#   max_items - the maximum number of matching items allowed to be returned
+#               no results will be returned if this number is exceeded,
+#               but the total result count will still be returned
+#               applies even if pagination is enabled
+#               default: nil (disabled)
+#
+# This handler expects the following parameters from the user or the UI:
+#
+# Required:
+#
+#   q - the query itself, a String that follows the keyword format above
+#
+# Optional:
+#
+#   order_by - a String used to order the search results - default: 'created_at ASC'
+#   per_page - the number of results returned per page - default: nil (disabled)
+#   page     - the current page number - default: 1
+#
+# This handler's output contains:
+#
+#   outputs[:total_count] - the total number of items that matched the query
+#                           set even when no results are returned due to
+#                           a query that is too short or too generic
+#   outputs[:items]       - the array of objects returned by the search routine
+#
+# See spec/dummy/app/handlers/users_search.rb for an example search handler
+
+require 'lev'
+
+module OpenStax
+  module Utilities
+    class AbstractKeywordSearchHandler
+
+      lev_handler
+
+      protected
+
+      class_attribute :search_routine, :max_items, :min_characters
+
+      def authorized?
+        false
+      end
+
+      def handle
+        raise NotImplementedError if search_routine.nil?
+
+        query = params[:q] || params[:query]
+
+        fatal_error(code: :no_query,
+                    message: 'You must provide a query parameter (q or query).') if query.nil?
+        fatal_error(code: :query_too_short,
+                    message: "The provided query is too short (minimum #{
+                      min_characters} characters).") \
+          if !min_characters.nil? && query.length < min_characters
+
+        items = run(search_routine, query, params).outputs[:items]
+
+        outputs[:total_count] = items.limit(nil).offset(nil).count
+
+        fatal_error(code: :too_many_matches,
+                    message: "The number of matches exceeded the allowed limit of #{
+                      max_items} matches. Please refine your query and try again.") \
+          if !max_items.nil? && outputs[:total_count] > max_items
+
+        outputs[:items] = items.to_a
+      end
+
+    end
+
+  end
+end

data/app/routines/openstax/utilities/abstract_keyword_search_routine.rb

@@ -0,0 +1,149 @@
+# Database-agnostic keyword searching routine
+#
+# Keywords have the format keyword:value
+# Keywords can also be negated with -, as in -keyword:value
+# Values are comma-separated, while keywords are space-separated
+# See https://github.com/bruce/keyword_search for more information
+#
+# Subclasses must set the initial_relation, search_proc and sortable_fields class variables
+#
+#   initial_relation - the ActiveRecord::Relation that contains all
+#                      records to be searched, usually ClassName.unscoped
+#
+#   search_proc - a proc passed to keyword_search's `search` method
+#                 it receives keyword_search's `with` object as argument
+#                 this proc must define the `keyword` blocks for keyword_search
+#                 the relation to be scoped is contained in the @items instance variable
+#
+#   The `to_string_array` helper can help with parsing strings from the query
+#
+#   sortable_fields_map - a Hash that maps the lowercase names of fields
+#                         which can be used to sort the results to symbols
+#                         for their respective database columns
+#                         keys are lowercase strings that should be allowed
+#                         in options[:order_by]
+#                         values are the corresponding database column names
+#                         that will be passed to the order() method
+#
+# Callers of subclass routines provides a query argument and an options hash
+#
+# Required arguments:
+#
+#   query - a string that follows the keyword format above
+#
+# Options hash:
+#
+#     Ordering:
+#
+#       :order_by - list of fields to sort by, with optional sort directions
+#                   can be a String, Array of Strings or Array of Hashes
+#                   default: {"created_at" => :asc}
+#
+#     Pagination:
+#
+#       :per_page - the maximum number of results per page - default: nil (disabled)
+#       :page     - the page to return - default: 1
+#
+# This routine's output contains:
+#
+#   outputs[:items] - an ActiveRecord::Relation that matches the query terms and options
+#
+# You can use the following expression to obtain the
+# total count of records that matched the query terms:
+#
+#   outputs[:items].limit(nil).offset(nil).count
+#
+# See spec/dummy/app/routines/search_users.rb for an example search routine
+
+require 'lev'
+require 'keyword_search'
+
+module OpenStax
+  module Utilities
+    class AbstractKeywordSearchRoutine
+
+      lev_routine transaction: :no_transaction
+
+      protected
+
+      class_attribute :initial_relation, :search_proc, :sortable_fields_map
+
+      def exec(query, options = {})
+        raise NotImplementedError if initial_relation.nil? || \
+          search_proc.nil? || sortable_fields_map.nil?
+
+        @items = initial_relation
+
+        return @items.none unless query.is_a? String
+
+        # Scoping
+
+        ::KeywordSearch.search(query) do |with|
+          instance_exec(with, &search_proc)
+        end
+
+        # Ordering
+
+        order_bys = sanitize_order_bys(options[:order_by])
+        @items = @items.order(order_bys)
+        
+        # Pagination
+
+        per_page = Integer(options[:per_page]) rescue nil
+        unless per_page.nil?
+          page = Integer(options[:page]) rescue 1
+          @items = @items.limit(per_page).offset(per_page*(page-1))
+        end
+
+        outputs[:items] = @items
+      end
+
+      def sanitize_order_by(field, dir = nil)
+        sanitized_field = sortable_fields_map[field.to_s.downcase] || :created_at
+        sanitized_dir = dir.to_s.downcase == 'desc' ? :desc : :asc
+        {sanitized_field => sanitized_dir}
+      end
+
+      def sanitize_order_bys(order_bys)
+        case order_bys
+        when Array
+          order_bys.collect do |ob|
+            case ob
+            when Hash
+              sanitize_order_by(ob.keys.first, ob.values.first)
+            when Array
+              sanitize_order_by(ob.first, ob.second)
+            else
+              sanitize_order_by(ob)
+            end
+          end
+        when Hash
+          order_bys.collect { |k, v| sanitize_order_by(k, v) }
+        else
+          order_bys.to_s.split(',').collect do |ob|
+            fd = ob.split(' ')
+            sanitize_order_by(fd.first, fd.second)
+          end
+        end
+      end
+
+      # Parses a keyword string into an array of strings
+      # User-supplied wildcards are removed and strings are split on commas
+      # Then wildcards are appended or prepended if the append_wildcard or
+      # prepend_wildcard options are specified
+      def to_string_array(str, options = {})
+        sa = case str
+        when Array
+          str.collect{|name| name.gsub('%', '').split(',')}.flatten
+        else
+          str.to_s.gsub('%', '').split(',')
+        end
+        sa = sa.collect{|str| "#{str}%"} if options[:append_wildcard]
+        sa = sa.collect{|str| "%#{str}"} if options[:prepend_wildcard]
+        sa
+      end
+
+    end
+
+  end
+end

data/lib/openstax/utilities/delegate_access_control.rb

@@ -42,6 +42,11 @@ module OpenStax
         EOV
 
       end
+
+      # Convenience method for delegate_access_control
+      def delegate_access_control_to(relation, options = {})
+        delegate_access_control options.merge(to: relation)
+      end
        
     end
 

data/lib/openstax/utilities/engine.rb

@@ -1,3 +1,5 @@
+require "openstax/utilities/action_list"
+
 ActiveSupport::Inflector.inflections do |inflect|
   inflect.acronym 'OpenStax'
 end
@@ -7,14 +9,8 @@ module OpenStax
     class Engine < ::Rails::Engine
       isolate_namespace OpenStax::Utilities
 
-      initializer "openstax_utilities.assets.precompile" do |app|
-        app.config.assets.precompile += %w(openstax_utilities.css openstax_utilities.js)
-      end
-
-      initializer 'openstax_utilities.action_controller' do |app|
-        ActiveSupport.on_load :action_controller do
-          helper OSU::OsuHelper
-        end
+      config.after_initialize do
+        OSU::SITE_NAME = ::Rails.application.class.parent_name.underscore
       end
 
       config.generators do |g|

data/lib/openstax/utilities/helpers/datetime.rb

@@ -4,25 +4,25 @@ module OpenStax::Utilities::Helpers
     def standard_date(datetime)
       datetime.nil? ? 
         "" : 
-        datetime.strftime(OSU.configuration.standard_date_format)
+        datetime.strftime(OpenStax::Utilities.configuration.standard_date_format)
     end
     
     def standard_datetime(datetime)
       datetime.nil? ? 
         "" : 
-        datetime.strftime(OSU.configuration.standard_datetime_format)
+        datetime.strftime(OpenStax::Utilities.configuration.standard_datetime_format)
     end
     
     def standard_time(datetime)
       datetime.nil? ? 
         "" : 
-        datetime.strftime(OSU.configuration.standard_time_format)
+        datetime.strftime(OpenStax::Utilities.configuration.standard_time_format)
     end
     
     def standard_datetime_zone(datetime, zone)
       datetime.nil? ? 
         "" : 
-        datetime.in_time_zone(zone).strftime(OSU.configuration.standard_datetime_format)
+        datetime.in_time_zone(zone).strftime(OpenStax::Utilities.configuration.standard_datetime_format)
     end
     
     def month_year(datetime)

data/{app/helpers → lib}/openstax/utilities/osu_helper.rb

@@ -1,3 +1,9 @@
+require "openstax/utilities/classy_helper"
+require "openstax/utilities/helpers/misc"
+require "openstax/utilities/helpers/partials"
+require "openstax/utilities/helpers/action_list"
+require "openstax/utilities/helpers/datetime"
+
 module OpenStax::Utilities
   module OsuHelper
 
@@ -13,4 +19,6 @@ module OpenStax::Utilities
     end
 
   end
-end
+end
+
+ActionController::Base.send :helper, OpenStax::Utilities::OsuHelper

data/lib/openstax/utilities/version.rb

@@ -1,5 +1,5 @@
 module OpenStax
   module Utilities
-    VERSION = "3.0.0"
+    VERSION = "4.0.0"
   end
 end

data/lib/openstax_utilities.rb

@@ -15,16 +15,10 @@ require "openstax/utilities/enum"
 require "openstax/utilities/ruby"
 require "openstax/utilities/text"
 require "openstax/utilities/network"
-require "openstax/utilities/action_list"
 require "openstax/utilities/acts_as_numberable"
 require "openstax/utilities/delegate_access_control"
 require "openstax/utilities/access_policy"
-
-require "openstax/utilities/classy_helper"
-require "openstax/utilities/helpers/misc"
-require "openstax/utilities/helpers/partials"
-require "openstax/utilities/helpers/action_list"
-require "openstax/utilities/helpers/datetime"
+require "openstax/utilities/osu_helper"
 
 module OpenStax
   module Utilities

data/spec/dummy/README.md

@@ -1 +1 @@
-Dummy application used to test the openstax_utilities gem.
+Dummy application used to test the openstax_utilities gem.

data/spec/dummy/Rakefile

@@ -1,7 +1,6 @@
-#!/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
+Rails.application.load_tasks

data/spec/dummy/app/assets/javascripts/application.js

@@ -5,11 +5,9 @@
 // or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
 //
 // It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
-// the compiled file.
+// compiled file.
 //
-// WARNING: THE FIRST BLANK LINE MARKS THE END OF WHAT'S TO BE PROCESSED, ANY BLANK LINE SHOULD
-// GO AFTER THE REQUIRES BELOW.
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
 //
-//= require jquery
-//= require jquery_ujs
 //= require_tree .

data/spec/dummy/app/assets/stylesheets/application.css

@@ -5,9 +5,11 @@
  * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
  * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
  *
- * You're free to add application-wide styles to this file and they'll appear at the top of the
- * compiled file, but it's generally better to create a new file per style scope.
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any styles
+ * defined in the other CSS/SCSS files in this directory. It is generally better to create a new
+ * file per style scope.
  *
- *= require_self
  *= require_tree .
+ *= require_self
  */