filterameter 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b14f3434137044896e6273279573a9ec00bbb9ef6b1fbe03c99a01851df5a4d3
-  data.tar.gz: d2afe0937ee82dea9c8ec4933c39bb13a083c6183772ecb847ef7a28d582afbd
+  metadata.gz: a250b39d9c80245166bcfe14a7133cd5ec83f9746989d7e461fa0c121358f57a
+  data.tar.gz: 5d7c64cb79fd73ee94e4e94316b0b5964fac440b14fb0bc58c0c1d805d0f9d60
 SHA512:
-  metadata.gz: 2ebdc7ca579a967fc95e3843df78e6137291a1136e60fe9636306d5899327f4a456e581e70251c4ad1203e253d82f24090f85cefe699476c8d928c2f22f2796e
-  data.tar.gz: d5bb0bf69b24912dcd22b21f41abb5655bb225cf77316c20e7c753ca2dd060a47815cd6af66b4cc229ca33bfcf94010bbcfc84f5abcdfbf1fd6faee1dda6d8a1
+  metadata.gz: d170eb98f80c24173fa92d0251aa68af7d5f3d002d4c3ff473e086aba8d16f07fd05422af6dced018331e883431c93292b4d0b7e5bf3476587b40df8dbeab8d3
+  data.tar.gz: e2342236255b79da8ee96aa7eec0e33c6e9f0131473eaadffd31f833c7212d01d2123eeb6a70cdff8d619ff8678f4d6aafc8d9b52151de9dc6583983f3accd92

data/lib/filterameter/declarative_filters.rb

@@ -6,17 +6,129 @@ module Filterameter
   # Mixin DeclarativeFilters should be included in controllers to enable the filter DSL.
   module DeclarativeFilters
     extend ActiveSupport::Concern
-    include Filterameter::Filterable
-    include Filterameter::Sortable
 
     class_methods do
       delegate :declarations_validator, to: :filter_coordinator
 
+      # Declares a filter that can be read from the parameters and applied to the
+      # ActiveRecord query. The `name` identifies the name of the parameter and is the
+      # default value to determine the criteria to be applied. The name can be either
+      # an attribute or a scope.
+      #
+      # ## Options
+      #
+      # The declaration can also include an `options` hash to specialize the behavior of the filter.
+      #
+      # * **name**: Specify the attribute or scope name if the parameter name is not the same. The default value is the
+      #   parameter name, so if the two match this can be left out.
+      #
+      # * **association**: Specify the name of the association if the attribute or scope is nested. Use an array if the
+      #   asociation is more than one level.
+      #
+      # * **validates**: Specify a validation if the parameter value should be validated. This uses ActiveModel
+      #   validations; please review those for types of validations and usage.
+      #
+      # * **partial**: Specify the partial option if the filter should do a partial search (SQL's `LIKE`). The partial
+      #   option accepts a hash to specify the search behavior.
+      #
+      #   Here are the available options:
+      #   *   match: `:anywhere` (default), `:from_start`, `:dynamic`
+      #   *   case_sensitive: `true`, `false` (default)
+      #
+      #   There are two shortcuts: the partial option can be declared with `true`,
+      #   which just uses the defaults; or the partial option can be declared with
+      #   the match option directly, such as `partial: :from_start`.
+      #
+      # * **range**: Specify a range option if the filter also allows ranges to be searched. The range option accepts
+      #   the following options:
+      #     *   true: enables two additional parameters with attribute name plus
+      #         suffixes `_min` and `_max`
+      #     *   min_only: enables additional parameter with attribute name plus
+      #         suffix `_min`
+      #     *   max_only: enables additional parameter with attribute name plus
+      #         suffix `_max`
+      #
+      # * **sortable**: By default most filters are sortable. To prevent an attribute filter from being sortable, set
+      #   the option to `false`.
+      #
+      # Options examples:
+      #
+      #     filter :status, name: :current_status
+      #     filter :manager_id, association: :department
+      #     filter :business_unit_name, name: :name, association: [:department, :business_unit]
+      #     filter :size, validates: { inclusion: { in: %w[Small Medium Large], allow_multiple_values: true } }
+      #     filter :description, partial: true
+      #     filter :department_name, partial: :from_start
+      #     filter :reason, partial: { match: :dynamic, case_sensitive: true }
+      #     filter :price, range: true
+      def filter(name, options = {})
+        filter_coordinator.add_filter(name, options)
+      end
+
+      # Declares a list of filters without options. Filters that require options must be declared with `filter`.
+      def filters(*names)
+        names.each { |name| filter(name) }
+      end
+
+      # Declares a sort that can be read from the parameters and applied to the
+      # ActiveRecord query. The `parameter_name` identifies the name of the parameter
+      # and is the default value for the attribute name when none is specified in the
+      # options.
+      #
+      # ## Options
+      #
+      # The declaration can also include an `options` hash to specialize the behavior of the sort.
+      #
+      # * **name**: Specify the attribute or scope name if the parameter name is not the same. The default value is the
+      #   parameter name, so if the two match this can be left out.
+      #
+      # * **association**: Specify the name of the association if the attribute or scope is nested.
+      #
+      # Options example:
+      #
+      #     sort :project_created_at, name: :created_at, association: :project
+      def sort(parameter_name, options = {})
+        filter_coordinator.add_sort(parameter_name, options)
+      end
+
+      # Declares a list of sorts without options. Sorts that require options must be declared with `sort`.
+      def sorts(*parameter_names)
+        parameter_names.each { |parameter_name| filter(parameter_name) }
+      end
+
+      def default_sort(sort_and_direction_pairs)
+        filter_coordinator.default_sort = sort_and_direction_pairs
+      end
+
+      # Rails conventions are used to determine the controller's model. For example, the PhotosController builds a query
+      # against the Photo model. If a controller is namespaced, the model will first be looked up without the namespace,
+      # then with the namespace.
+      #
+      # **If the conventions do not provide the correct model**, the model can be named explicitly with the following:
+      #
+      # ```ruby
+      # filter_model 'Picture'
+      # ```
+      #
+      # An optional second parameter can be used to specify the variable name. Both the model and the variable name can
+      # be specified with this short-cut. For example, to use the Picture model and store the results as `@data`, use
+      # the following:
+      #
+      #     filter_model 'Picture', :data
+      #
+      # **Important:** If the `filter_model` declaration is used, it must be before any filter or sort declarations.
       def filter_model(model_class, query_var_name = nil)
         filter_coordinator.model_class = model_class
         filter_query_var_name(query_var_name) if query_var_name.present?
       end
 
+      # When using the before action callback `build_filtered_query`, the query is assigned to an instance variable with
+      # the name of the model pluralized. For example, the Photo model will use the variable `@photos`.
+      #
+      # To use a different variable name with the callback, assign it with `filter_query_var_name`. For example, if the
+      # query is stored as `@data`, use the following:
+      #
+      #     filter_query_var_name :data
       def filter_query_var_name(query_variable_name)
         filter_coordinator.query_variable_name = query_variable_name
       end

data/lib/filterameter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Filterameter
-  VERSION = '1.0.0'
+  VERSION = '1.0.1'
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: filterameter
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Todd Kummer
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-19 00:00:00.000000000 Z
+date: 2025-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -100,14 +99,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -156,14 +155,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.3
+        version: 3.2.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.3
+        version: 3.2.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec_rails
   requirement: !ruby/object:Gem::Requirement
@@ -223,7 +222,6 @@ files:
 - lib/filterameter/filter_coordinator.rb
 - lib/filterameter/filter_declaration.rb
 - lib/filterameter/filter_factory.rb
-- lib/filterameter/filterable.rb
 - lib/filterameter/filters/arel_filter.rb
 - lib/filterameter/filters/attribute_filter.rb
 - lib/filterameter/filters/attribute_validator.rb
@@ -247,7 +245,6 @@ files:
 - lib/filterameter/registries/sub_registry.rb
 - lib/filterameter/sort_declaration.rb
 - lib/filterameter/sort_factory.rb
-- lib/filterameter/sortable.rb
 - lib/filterameter/sorts/attribute_sort.rb
 - lib/filterameter/sorts/scope_sort.rb
 - lib/filterameter/validators/inclusion_validator.rb
@@ -256,7 +253,6 @@ homepage: https://github.com/RockSolt/filterameter
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -271,8 +267,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Declarative Filter Parameters
 test_files: []

data/lib/filterameter/filterable.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-module Filterameter
-  # # Filterable
-  #
-  # Mixin Filterable provides class methods `filter` and `filters`.
-  module Filterable
-    extend ActiveSupport::Concern
-
-    class_methods do
-      # Declares a filter that can be read from the parameters and applied to the
-      # ActiveRecord query. The `name` identifies the name of the parameter and is the
-      # default value to determine the criteria to be applied. The name can be either
-      # an attribute or a scope.
-      #
-      # ### Options
-      #
-      # :name
-      # :   Specify the attribute or scope name if the parameter name is not the same.
-      #     The default value is the parameter name, so if the two match this can be
-      #     left out.
-      #
-      #
-      # :association
-      # :   Specify the name of the association if the attribute or scope is nested.
-      #
-      #
-      # :validates
-      # :   Specify a validation if the parameter value should be validated. This uses
-      #     ActiveModel validations; please review those for types of validations and
-      #     usage.
-      #
-      #
-      # :partial
-      # :   Specify the partial option if the filter should do a partial search (SQL's
-      #     `LIKE`). The partial option accepts a hash to specify the search behavior.
-      #
-      #     Here are the available options:
-      #     *   match: anywhere (default), from_start, dynamic
-      #     *   case_sensitive: true, false (default)
-      #
-      #     There are two shortcuts: : the partial option can be declared with `true`,
-      #     which just uses the defaults; or the partial option can be declared with
-      #     the match option directly, such as `partial: :from_start`.
-      #
-      #
-      # :range
-      # :   Specify a range option if the filter also allows ranges to be searched.
-      #     The range option accepts the following options:
-      #     *   true: enables two additional parameters with attribute name plus
-      #         suffixes `_min` and `_max`
-      #     *   :min_only: enables additional parameter with attribute name plus
-      #         suffix `_min`
-      #     *   :max_only: enables additional parameter with attribute name plus
-      #         suffix `_max`
-      #
-      def filter(name, options = {})
-        filter_coordinator.add_filter(name, options)
-      end
-
-      # Declares a list of filters that can be read from the parameters and applied to
-      # the query. The name can be either an attribute or a scope. Declare filters
-      # individually with `filter` if more options are required.
-      def filters(*names)
-        names.each { |name| filter(name) }
-      end
-    end
-  end
-end

data/lib/filterameter/sortable.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Filterameter
-  # # Sortable
-  #
-  # Mixin Sortable provides class methods `sort` and `sorts`.
-  module Sortable
-    extend ActiveSupport::Concern
-
-    class_methods do
-      # Declares a sort that can be read from the parameters and applied to the
-      # ActiveRecord query. The `parameter_name` identifies the name of the parameter
-      # and is the default value for the attribute name when none is specified in the
-      # options.
-      #
-      # The including class must implement `filter_coordinator`
-      #
-      # ### Options
-      #
-      # :name
-      # :   Specify the attribute or scope name if the parameter name is not the same.
-      #     The default value is the parameter name, so if the two match this can be
-      #     left out.
-      #
-      #
-      # :association
-      # :   Specify the name of the association if the attribute or scope is nested.
-      #
-      def sort(parameter_name, options = {})
-        filter_coordinator.add_sort(parameter_name, options)
-      end
-
-      # Declares a list of filters that can be read from the parameters and applied to
-      # the query. The name can be either an attribute or a scope. Declare filters
-      # individually with `filter` if more options are required.
-      def sorts(*parameter_names)
-        parameter_names.each { |parameter_name| filter(parameter_name) }
-      end
-
-      def default_sort(sort_and_direction_pairs)
-        filter_coordinator.default_sort = sort_and_direction_pairs
-      end
-    end
-  end
-end