irie 1.0.0

data/Rakefile

@@ -0,0 +1,21 @@
+require 'bundler'
+require 'rake/testtask'
+require 'appraisal'
+
+Bundler::GemHelper.install_tasks
+
+Rake::TestTask.new do |t|
+  t.libs = ['lib','test']
+  t.test_files = Dir.glob(["test/**/*_test.rb"])
+  t.verbose = true
+end
+
+task :default => [:test]
+task :spec => [:test]
+
+desc "Setup Appraisal."
+task 'appraisal:setup' do
+  Rake::Task['appraisal:cleanup'].invoke
+  Rake::Task['appraisal:gemfiles'].invoke
+  Rake::Task['appraisal:install'].invoke
+end

data/lib/irie.rb

@@ -0,0 +1,23 @@
+require 'irie/version'
+require 'irie/configuration_error'
+require 'irie/config'
+require 'irie/class_methods'
+require 'irie/param_aliases'
+require 'irie/extensions/autorender_count'
+require 'irie/extensions/params_to_joins'
+require 'irie/extensions/conversion/nil_params'
+require 'irie/extensions/count'
+require 'irie/extensions/index_query'
+require 'irie/extensions/limit'
+require 'irie/extensions/offset'
+require 'irie/extensions/order'
+require 'irie/extensions/paging/autorender_page_count'
+require 'irie/extensions/paging'
+require 'irie/extensions/param_filters'
+require 'irie/extensions/query_filter'
+require 'irie/extensions/query_includes'
+require 'irie/extensions/smart_layout'
+
+class ::ActionController::Base
+  extend ::Irie::ClassMethods
+end

data/lib/irie/class_methods.rb

@@ -0,0 +1,61 @@
+module Irie
+  module ClassMethods
+
+    protected
+
+    def extensions(*extension_syms)
+      ::Irie::CONTROLLER_OPTIONS.each do |key|
+        class_attribute key, instance_writer: true unless respond_to?(key)
+        # doing unless self.send(key.to_sym) to ensure parent override of defaults is kept
+        self.send("#{key}=".to_sym, ::Irie.send(key)) unless self.send(key.to_sym)
+      end
+
+      #raise "self.inherited_resources_defined_actions = #{inherited_resources_defined_actions.inspect}\n\ninstance_methods = #{self.instance_methods.collect(&:to_s).sort.join(', ')}\n\nself.autoincludes = #{self.autoincludes.inspect}" if $gary
+
+      self.autoincludes.keys.each do |action_sym|
+        if self.instance_methods.include?(action_sym.to_sym)
+          autoloading_extensions = self.autoincludes[action_sym]
+          if autoloading_extensions && autoloading_extensions.size > 0
+            extension_syms += autoloading_extensions
+          end
+        end
+      end
+      
+      extensions! extension_syms
+    end
+
+    # Load specified extensions in the order defined by self.extension_include_order.
+    def extensions!(*extension_syms)
+      return extension_syms if extension_syms.length == 0
+
+      extension_syms = extension_syms.flatten.collect {|es| es.to_sym}.compact
+
+      if extension_syms.include?(:all)
+        ordered_extension_syms = self.extension_include_order.dup
+      else
+        extensions_without_defined_order = extension_syms.uniq - self.extension_include_order.uniq
+        if extensions_without_defined_order.length > 0
+          raise ::Irie::ConfigurationError.new "The following must be added to the self.extension_include_order array in Irie configuration: #{extensions_without_defined_order.collect(&:inspect).join(', ')}"
+        else
+          ordered_extension_syms = self.extension_include_order & extension_syms
+        end
+      end
+
+      # load requested extensions
+      ordered_extension_syms.each do |arg_sym|
+        if module_class_name = self.available_extensions[arg_sym]
+          begin
+            logger.debug("Irie::ClassMethods.extensions! #{self} including #{module_class_name}") if ::Irie.debug?
+            include module_class_name.constantize
+          rescue NameError => e
+            raise ::Irie::ConfigurationError.new "Failed to constantize '#{module_class_name}' with extension key #{arg_sym.inspect} in self.available_extensions. Error: \n#{e.message}\n#{e.backtrace.join("\n")}"
+          end      
+        else
+          raise ::Irie::ConfigurationError.new "#{arg_sym.inspect} isn't defined in self.available_extensions"
+        end
+      end
+
+      extension_syms
+    end
+  end
+end

data/lib/irie/config.rb

@@ -0,0 +1,131 @@
+module Irie
+
+  CONTROLLER_OPTIONS = [
+    :autoincludes,
+    :available_actions,
+    :available_extensions,
+    :can_filter_by_default_using,
+    :debug,
+    :function_param_names,
+    :id_is_primary_key_param,
+    :number_of_records_in_a_page,
+    :predicate_prefix,
+    :update_should_return_entity,
+    :extension_include_order
+  ]
+
+  class << self
+    CONTROLLER_OPTIONS.each{|name|attr_accessor name; define_method("#{name}?") { !!public_send(name) } }
+    def configure(&blk); class_eval(&blk); end
+
+    # Adds to extension_include_order and extension_include_order, e.g.
+    #   ::Irie.register_extension :boolean_params, '::Focal::Irie::BooleanParams'
+    # Is equivalent to:
+    #   ::Irie.available_extensions[:boolean_params] = '::Focal::Irie::BooleanParams'
+    #   ::Irie.extension_include_order << extension_sym
+    # Allowed options are `:include`, `:after`, and `:before`. Some examples:
+    #   ::Irie.register_extension :boolean_params, '::Example::BooleanParams', include: :last  # the default, so unnecessary
+    #   ::Irie.register_extension :boolean_params, '::Example::BooleanParams', include: :first # includes module after all others registered at this point
+    #   ::Irie.register_extension :boolean_params, '::Example::BooleanParams', after: :nil_params # includes after :nil_params
+    #   ::Irie.register_extension :boolean_params, '::Example::BooleanParams', before: :nil_params # includes after :nil_params
+    def register_extension(extension_sym, extension_class_name, options = {})
+      raise ::Irie::ConfigurationError.new "Irie.register_extension must provide an extension symbol as the first argument" unless extension_sym
+      raise ::Irie::ConfigurationError.new "Irie.register_extension must provide an extension class name (string) as the second argument" unless extension_sym
+      raise ::Irie::ConfigurationError.new "Irie.register_extension can only provide a single option: :include, :after, or :before" if options.size > 1
+      initial_opts = options.dup
+      include_opt, after_opt, before_opt = *[:include, :after, :before].collect{|opt_name| options.delete(opt_name)}
+      include_opt = :last unless include_opt || after_opt || before_opt
+      raise ::Irie::ConfigurationError.new "Irie.register_extension unrecognized options: #{options.inspect}" if options.size > 0
+
+      ::Irie.extension_include_order.delete(extension_sym)
+
+      before_or_after_opt_value = before_opt || after_opt
+      if include_opt == :first
+        ::Irie.extension_include_order.unshift extension_sym
+      elsif include_opt == :last
+        ::Irie.extension_include_order << extension_sym
+      elsif before_or_after_opt_value
+        ind = ::Irie.extension_include_order.index(before_or_after_opt_value)
+        raise ::Irie::ConfigurationError.new "Irie.register_extension cannot insert #{before_opt ? 'before' : 'after'} #{before_or_after_opt_value.inspect}, because #{before_or_after_opt_value.inspect} was not yet registered. A possible workaround for deferred registration may be to require the code that does the prerequisite registration."
+        ::Irie.extension_include_order.insert(ind + (after_opt ? 1 : 0), extension_sym)
+      else
+        raise ::Irie::ConfigurationError.new "Irie.register_extension unsupported options: #{initial_opts.inspect}"
+      end
+
+      ::Irie.available_extensions[extension_sym] = extension_class_name
+    end
+  end
+
+end
+
+::Irie.configure do
+  
+  # Default for :using in can_filter_by.
+  self.can_filter_by_default_using = [:eq]
+
+  # Use one or more alternate request parameter names for functions, e.g.
+  # `self.function_param_names = {distinct: :very_distinct, limit: [:limit, :limita]}`
+  self.function_param_names = {}
+  
+  # Delimiter for ARel predicate in the request parameter name.
+  self.predicate_prefix = '.'
+
+  # You'd set this to false if id is used for something else other than primary key.
+  self.id_is_primary_key_param = true
+
+  # Used when paging is enabled.
+  self.number_of_records_in_a_page = 15
+
+  # When you include the defined action module, it includes the associated modules.
+  # If value or value array contains symbol it will look up symbol in 
+  # ::Irie.available_extensions in the controller (which is defaulted to 
+  # `::Irie.available_extensions`). If value is String will assume String is the
+  # fully-qualified module name to include, e.g. `index: '::My::Module'`, If constant,
+  # it will just include constant (module), e.g. `index: ::My::Module`.
+  self.autoincludes = {
+    create: [:smart_layout, :query_includes],
+    destroy: [:smart_layout, :query_includes],
+    edit: [:smart_layout, :query_includes],
+    index: [:smart_layout, :index_query, :order, :param_filters, :params_to_joins, :query_filter, :query_includes],
+    new: [:smart_layout],
+    show: [:smart_layout, :query_includes],
+    update: [:smart_layout, :query_includes]
+  }
+
+  # This ensures the correct order of includes via the extensions method. It bears no
+  # relevance on whether the include is included or not. Since many includes call
+  # super in their methods, the order may seem partially reversed, but this is the actual
+  # include order. If extensions are not listed here, they will not be included by
+  # the extensions method.
+  self.extension_include_order = [
+    :smart_layout,
+    :autorender_page_count,
+    :autorender_count,
+    :count,
+    :paging,
+    :order,
+    :offset,
+    :limit,
+    :param_filters,
+    :query_filter,
+    :params_to_joins,
+    :query_includes,
+    :index_query,
+    :nil_params
+  ]
+
+  # By default, it sets the instance variable, but does not return entity if request
+  # update, e.g. in JSON format.
+  self.update_should_return_entity = false
+
+  # Extensions to actions that you can implement in the controller via
+  # `include_extensions`, e.g. `include_extensions :count, :paging`
+  # Each is added as each file is required when the gem is loaded, so for a full list,
+  # check `::Irie.available_extensions` in rails console.
+  # You shouldn't have to worry about configuring this typically.
+  self.available_extensions = {}
+
+  # If true, will logger.debug in instance methods to help with execution tracing at
+  # runtime.
+  self.debug = false
+end

data/lib/irie/configuration_error.rb

@@ -0,0 +1,4 @@
+module Irie
+  class ConfigurationError < ::StandardError
+  end
+end

data/lib/irie/extensions/autorender_count.rb

@@ -0,0 +1,17 @@
+module Irie
+  module Extensions
+    # Standard rendering of index page count in all formats except html so you don't need views for them.
+    module AutorenderCount
+      extend ::ActiveSupport::Concern
+      ::Irie.available_extensions[:autorender_count] = '::' + AutorenderCount.name
+
+      protected
+      
+      def autorender_count(options={}, &block)
+        logger.debug("Irie::Extensions::AutorenderCount.autorender_count") if ::Irie.debug?
+        render request.format.symbol => { count: @count }, status: 200, layout: false
+      end
+      
+    end
+  end
+end

data/lib/irie/extensions/conversion/nil_params.rb

@@ -0,0 +1,27 @@
+module Irie
+  module Extensions
+    module Conversion
+      # Converts the following filter request param values to nil: 'NULL', 'null', 'nil'
+      module NilParams
+        extend ::ActiveSupport::Concern
+        ::Irie.available_extensions[:nil_params] = '::' + NilParams.name
+
+        NILS = ['NULL'.freeze, 'null'.freeze, 'nil'.freeze].to_set
+
+        protected
+
+        # Converts request param value(s) 'NULL', 'null', and 'nil' to nil.
+        def convert_param(param_name, param_value_or_values)
+          logger.debug("Irie::Extensions::Conversion::NilParams.convert_param(#{param_name.inspect}, #{param_value_or_values.inspect})") if ::Irie.debug?
+          param_value_or_values = super if defined?(super)
+          if param_value_or_values.is_a? Array
+            param_value_or_values.map{|v| v && NILS.include?(v) ? nil : v }
+          else
+            param_value_or_values && NILS.include?(param_value_or_values) ? nil : param_value_or_values
+          end
+        end
+      
+      end
+    end
+  end
+end

data/lib/irie/extensions/count.rb

@@ -0,0 +1,21 @@
+module Irie
+  module Extensions
+    # Allowing setting `@count` with the count of the records in the index query.
+    module Count
+      extend ::ActiveSupport::Concern
+      ::Irie.available_extensions[:count] = '::' + Count.name
+
+      included do
+        include ::Irie::ParamAliases
+      end
+      
+      def index(options={}, &block)
+        logger.debug("Irie::Extensions::Count.index") if ::Irie.debug?
+        return super(options, &block) unless aliased_param_present?(:count)
+        @count = collection.count
+        return respond_to?(:autorender_count, true) ? autorender_count(options, &block) : super(options, &block)
+      end
+
+    end
+  end
+end

data/lib/irie/extensions/index_query.rb

@@ -0,0 +1,48 @@
+module Irie
+  module Extensions
+    # Allows use of a lambda for the index query.
+    module IndexQuery
+      extend ::ActiveSupport::Concern
+      ::Irie.available_extensions[:index_query] = '::' + IndexQuery.name
+
+      included do
+        include ::Irie::ParamAliases
+
+        class_attribute(:custom_index_query, instance_writer: true) unless self.respond_to? :custom_index_query
+
+        self.custom_index_query ||= nil
+      end
+
+      module ClassMethods
+
+        protected
+        
+        # Specify a custom query/additional filtering of the collection, e.g.
+        #   index_query ->(q) { q.where(:status_code => 'green') }
+        # You could also completely overwrite the collection which would lead
+        # to certain peril, as you would need to then ensure all filters
+        # are included in the correct order to be executed after the query.
+        def index_query(query)
+          self.custom_index_query = query
+        end
+      end
+
+      protected
+
+      def collection
+        logger.debug("Irie::Extensions::IndexQuery.collection") if ::Irie.debug?
+        object = super
+        if self.custom_index_query
+          # convert to relation if model class because proc expects a relation
+          object = object.all unless object.is_a?(ActiveRecord::Relation)
+          a = object.to_s
+          object = self.custom_index_query.call(object)
+        end
+
+        logger.debug("Irie::Extensions::IndexQuery.collection: relation.to_sql so far: #{object.to_sql}") if ::Irie.debug? && object.respond_to?(:to_sql)
+
+        set_collection_ivar object
+      end
+    end
+  end
+end

data/lib/irie/extensions/limit.rb

@@ -0,0 +1,25 @@
+module Irie
+  module Extensions
+    # Allows limiting of the number of records returned by the index query.
+    module Limit
+      extend ::ActiveSupport::Concern
+      ::Irie.available_extensions[:limit] = '::' + Limit.name
+
+      included do
+        include ::Irie::ParamAliases
+      end
+
+      protected
+
+      def collection
+        logger.debug("Irie::Extensions::Limit.collection") if ::Irie.debug?
+        object = super
+        aliased_params(:limit).each {|param_value| object = object.limit(param_value)}
+
+        logger.debug("Irie::Extensions::Limit.collection: relation.to_sql so far: #{object.to_sql}") if ::Irie.debug? && object.respond_to?(:to_sql)
+
+        set_collection_ivar object
+      end
+    end
+  end
+end

data/lib/irie/extensions/offset.rb

@@ -0,0 +1,25 @@
+module Irie
+  module Extensions
+    # Allowing offsetting (skipping) records that would be returned by the index query.
+    module Offset
+      extend ::ActiveSupport::Concern
+      ::Irie.available_extensions[:offset] = '::' + Offset.name
+
+      included do
+        include ::Irie::ParamAliases
+      end
+
+      protected
+
+      def collection
+        logger.debug("Irie::Extensions::Offset.collection") if ::Irie.debug?
+        object = super
+        aliased_params(:offset).each {|param_value| object = object.offset(param_value)}
+
+        logger.debug("Irie::Extensions::Offset.collection: relation.to_sql so far: #{object.to_sql}") if ::Irie.debug? && object.respond_to?(:to_sql)
+
+        set_collection_ivar object
+      end
+    end
+  end
+end

data/lib/irie/extensions/order.rb

@@ -0,0 +1,153 @@
+module Irie
+  module Extensions
+    # Allows setting of attributes that can be used for ordering, and allows default ordering to be set.
+    module Order
+      extend ::ActiveSupport::Concern
+      ::Irie.available_extensions[:order] = '::' + Order.name
+
+      included do
+        include ::Irie::ParamAliases
+
+        class_attribute(:can_be_ordered_by, instance_writer: true) unless self.respond_to? :can_be_ordered_by
+        class_attribute(:default_ordered_by, instance_writer: true) unless self.respond_to? :default_ordered_by
+        
+        self.can_be_ordered_by ||= []
+        self.default_ordered_by ||= {}
+      end
+
+      module ClassMethods
+
+        protected
+        
+        # A whitelist of orderable attributes.
+        #
+        # If no options are provided or the :using option is provided, defines attributes that are orderable through the operation(s) already defined in can_filter_by_default_using, or can specify attributes:
+        #   can_order_by :attr_name_1, :attr_name_2
+        # So that you could call: http://.../foobars?order=attr_name_1,-attr_name_2
+        # to order by attr_name_1 asc then attr_name_2 desc.
+        #
+        # When :through is specified, it will take the array supplied to through as 0 to many model names following by an attribute name. It will follow through
+        # each association until it gets to the attribute to filter by that via ARel joins, e.g. if the model Foobar has an association to :foo, and on the Foo model there is an assocation
+        # to :bar, and you want to order by bar.name (foobar.foo.bar.name):
+        #  can_order_by :my_param_name, through: {foo: {bar: :name}}
+        def can_order_by(*args)
+          options = args.extract_options!
+
+          opt_through = options.delete(:through)
+          raise ::Irie::ConfigurationError.new "options #{options.inspect} not supported by can_order_by" if options.present?
+
+          self.can_be_ordered_by = self.can_be_ordered_by.deep_dup
+
+          args.each do |arg|
+            # store as strings because we have to do a string comparison later to avoid req param symbol attack
+            self.can_be_ordered_by << arg.to_s unless self.can_be_ordered_by.include?(arg.to_s)
+          end
+
+          if opt_through
+            raise ::Irie::ConfigurationError.new "Must use extension :params_to_joins to use can_order_by :through" unless ancestors.include?(::Irie::Extensions::ParamsToJoins)
+            args.each do |through_key|
+              # note: handles cloning, etc.
+              self.define_params(through_key => opt_through)
+            end
+          end
+        end
+
+        # Takes an string, symbol, array, hash to indicate order. If not a hash, assumes is ascending. Is cumulative and order defines order of sorting, e.g:
+        #   #would order by foo_color attribute ascending
+        #   default_order_by :foo_color
+        # or
+        #   default_order_by foo_date: :asc, bar_date: :desc
+        # or you could be completely insane and do:
+        #   default_order_by {foo_date: :asc}, :foo_color, 'foo_name', another_date: :asc, bar_date: :desc
+        def default_order_by(*args)
+          options = args.extract_options!
+
+          self.default_ordered_by = self.default_ordered_by.deep_dup
+
+          # hash is ordered in recent versions of Ruby we support
+          args.flatten.each do |item|
+            case item
+            when Hash
+              # merge hash converting keys to string
+              item.each {|param_name, direction| self.default_ordered_by[param_name.to_s] = direction}
+            when String, Symbol
+              self.default_ordered_by[item.to_s] = :asc
+            else
+              raise ::Irie::ConfigurationError.new "Can't default_order_by #{item}"
+            end
+          end
+
+          # merge hash converting keys to string
+          options.each {|param_name, direction| self.default_ordered_by[param_name.to_s] = direction}
+        end
+      end
+
+      protected
+
+      def collection
+        logger.debug("Irie::Extensions::Order.collection") if ::Irie.debug?
+        object = super
+
+        already_ordered_by = []
+        aliased_params(:order).collect{|p| p.split(',')}.flatten.collect(&:strip).each do |split_param_name|
+
+          # not using convert_param here.
+          # (these should be attribute names, not attribute values.)
+
+          # remove optional preceding - or + to act as directional
+          direction = :asc
+          if split_param_name[0] == '-'
+            direction = :desc
+            split_param_name = split_param_name.reverse.chomp('-').reverse
+          elsif split_param_name[0] == '+'
+            split_param_name = split_param_name.reverse.chomp('+').reverse
+          end
+
+          # support for named_params/:through renaming of param name
+          attr_sym = attr_sym_for_param(split_param_name)
+
+          # order of logic here is important:
+          # do not to_sym the partial param value until passes whitelist to avoid symbol attack.
+          # be sure to pass in the same param name as the default param it is trying to override,
+          # if there is one.
+          if self.can_be_ordered_by.include?(split_param_name) && !already_ordered_by.include?(attr_sym)
+            join_to_apply = join_for_param(split_param_name)
+            object = object.joins(join_to_apply) if join_to_apply
+            arel_table_column = get_arel_table(split_param_name)[attr_sym]
+            raise ::Irie::ConfigurationError.new "can_order_by/define_params config problem: could not find arel table/column for param name #{split_param_name.inspect} and/or attr_sym #{attr_sym.inspect}" unless arel_table_column
+            #TODO: is there a better way? not sure how else to order on joined table columns- no example
+            sql_fragment = "#{arel_table_column.relation.name}.#{arel_table_column.name}#{direction == :desc ? ' DESC' : ''}"
+            # Important note! the behavior of multiple `order`'s' got reversed between Rails 4.0.0 and 4.0.1:
+            # http://weblog.rubyonrails.org/2013/11/1/Rails-4-0-1-has-been-released/
+            object = object.order(sql_fragment)
+            already_ordered_by << attr_sym
+          end
+
+          set_collection_ivar object
+
+          object
+        end
+
+        self.default_ordered_by.each do |split_param_name, direction|
+          unless already_ordered_by.include?(split_param_name)
+            attr_sym = attr_sym_for_param(split_param_name)
+            join_to_apply = join_for_param(split_param_name)
+            object = object.joins(join_to_apply) if join_to_apply
+            arel_table_column = get_arel_table(split_param_name)[attr_sym]
+            raise ::Irie::ConfigurationError.new "default_order_by/define_params config problem: could not find arel table/column for param name #{split_param_name.inspect} and/or attr_sym #{attr_sym.inspect}" unless arel_table_column
+            #TODO: is there a better way? not sure how else to order on joined table columns- no example
+            sql_fragment = "#{arel_table_column.relation.name}.#{arel_table_column.name}#{direction == :desc ? ' DESC' : ''}"            
+            object = object.order(sql_fragment)
+            already_ordered_by << attr_sym
+          end
+        end
+
+        logger.debug("Irie::Extensions::Order.collection: relation.to_sql so far: #{object.to_sql}") if ::Irie.debug? && object.respond_to?(:to_sql)
+
+        set_collection_ivar object
+      end
+    end
+  end
+end
+
+