blacklight 7.12.0 → 7.14.0

data/lib/blacklight/configuration/facet_field.rb

@@ -46,6 +46,13 @@ module Blacklight
     #      are a hash containing: label (a label to show the user in the facet interface), fq (a string passed into solr as an fq (when selected) or a facet.query)
     # @!attribute pivot
     #   @return []
+    # @!attribute filter_query_builder
+    #   @return [nil, #call] a Proc (or other object responding to #call) that receives as parameters: 1) the search builder, 2) this facet config
+    #     and 3) the solr parameters hash. The Proc returns a string suitable for e.g. Solr's fq parameter, or a 2-element array of the string and a hash of additional
+    #     parameters to include with the query (i.e. for referenced subqueries); note that implementations are responsible for ensuring
+    #     the additional parameter keys are unique.
+    # @!attribute filter_class
+    #  @ return [nil, Blacklight::SearchState::FilterField] a class that implements the `FilterField`'s' API to manage URL parameters for a facet
 
     ##
     # Rendering:

data/lib/blacklight/configuration/fields.rb

@@ -151,7 +151,7 @@ module Blacklight
           repository = repository_class.new(self)
           repository.reflect_fields
         rescue => e
-          Blacklight.logger.warn "Error retrieving field metadata: #{e}"
+          Blacklight.logger&.warn "Error retrieving field metadata: #{e}"
           false
         end
 

data/lib/blacklight/configuration/search_field.rb

@@ -3,6 +3,11 @@ module Blacklight
   class Configuration::SearchField < Blacklight::Configuration::Field
     # @!attribute include_in_simple_select
     # @!attribute qt
+    # @!attribute query_builder
+    #   @return [nil, #call] a Proc (or other object responding to #call) that receives as parameters: 1) the search builder, 2) this search field,
+    #     and 3) the solr_parameters hash.  The Proc returns a string suitable for e.g. Solr's q parameter, or a 2-element array of the
+    #     string and a hash of additional parameters to include with the query (i.e. for referenced subqueries); note that
+    #     implementations are responsible for ensuring the additional parameter keys are unique.
 
     def normalize! blacklight_config = nil
       self.if = include_in_simple_select if self.if.nil?

data/lib/blacklight/configuration/tool_config.rb

@@ -2,5 +2,9 @@
 module Blacklight
   class Configuration::ToolConfig < OpenStructWithHashAccess
     # @!attribute partial
+
+    def name
+      super || key
+    end
   end
 end

data/lib/blacklight/configuration/view_config.rb

@@ -17,6 +17,18 @@ class Blacklight::Configuration
       super || Blacklight::SearchBarPresenter
     end
 
+    def display_label(key)
+      I18n.t(
+        :"blacklight.search.view_title.#{key}",
+        default: [
+          :"blacklight.search.view.#{key}",
+          label,
+          title,
+          key.to_s.humanize
+        ]
+      )
+    end
+
     class Show < ViewConfig
       # @!attribute route
       #   @return [Hash] Default route parameters for 'show' requests.

data/lib/blacklight/nested_open_struct_with_hash_access.rb

@@ -101,7 +101,7 @@ module Blacklight
 
     def set_default_proc!
       self.default_proc = lambda do |hash, key|
-        hash[key] = nested_class.new
+        hash[key] = nested_class.new(key: key)
       end
     end
   end

data/lib/blacklight/search_builder.rb

@@ -8,7 +8,7 @@ module Blacklight
     class_attribute :default_processor_chain
     self.default_processor_chain = []
 
-    attr_reader :processor_chain, :blacklight_params
+    attr_reader :processor_chain, :search_state, :blacklight_params
 
     # @overload initialize(scope)
     #   @param [Object] scope scope the scope where the filter methods reside in.
@@ -27,15 +27,17 @@ module Blacklight
       end
 
       @blacklight_params = {}
+      @search_state = Blacklight::SearchState.new(@blacklight_params, @scope&.blacklight_config, @scope)
       @merged_params = {}
       @reverse_merged_params = {}
     end
 
     ##
     # Set the parameters to pass through the processor chain
-    def with(blacklight_params = {})
+    def with(blacklight_params_or_search_state = {})
       params_will_change!
-      @blacklight_params = blacklight_params.dup
+      @search_state = blacklight_params_or_search_state.is_a?(Blacklight::SearchState) ? blacklight_params_or_search_state : @search_state.reset(blacklight_params_or_search_state)
+      @blacklight_params = @search_state.params.dup
       self
     end
 
@@ -43,7 +45,8 @@ module Blacklight
     # Update the :q (query) parameter
     def where(conditions)
       params_will_change!
-      @blacklight_params[:q] = conditions
+      @search_state = @search_state.reset(@search_state.params.merge(q: conditions))
+      @blacklight_params = @search_state.params.dup
       self
     end
 
@@ -52,7 +55,7 @@ module Blacklight
     def append(*addl_processor_chain)
       params_will_change!
       builder = self.class.new(processor_chain + addl_processor_chain, scope)
-          .with(blacklight_params)
+          .with(search_state)
           .merge(@merged_params)
           .reverse_merge(@reverse_merged_params)
 
@@ -72,7 +75,7 @@ module Blacklight
     # chain are ignored as no-ops, rather than raising.
     def except(*except_processor_chain)
       builder = self.class.new(processor_chain - except_processor_chain, scope)
-          .with(blacklight_params)
+          .with(search_state)
           .merge(@merged_params)
           .reverse_merge(@reverse_merged_params)
 
@@ -175,7 +178,7 @@ module Blacklight
         self.page = value
         return self
       end
-      @page ||= blacklight_params[:page].blank? ? 1 : blacklight_params[:page].to_i
+      @page ||= search_state.page
     end
 
     def rows=(value)
@@ -191,8 +194,7 @@ module Blacklight
       end
       @rows ||= begin
         # user-provided parameters should override any default row
-        r = [:rows, :per_page].map { |k| blacklight_params[k] }.reject(&:blank?).first
-        r ||= blacklight_config.default_per_page
+        r = search_state.per_page
         # ensure we don't excede the max page size
         r.nil? ? nil : [r, blacklight_config.max_per_page].map(&:to_i).min
       end
@@ -220,22 +222,10 @@ module Blacklight
     # configured search values are passed through to the search.
     # @return [String] the field/fields to sort by
     def sort
-      sort_field = if blacklight_params[:sort].blank?
-                     # no sort param provided, use default
-                     blacklight_config.default_sort_field
-                   else
-                     # check for sort field key
-                     blacklight_config.sort_fields[blacklight_params[:sort]]
-                   end
-      return sort_field.sort if sort_field.present?
-
-      Blacklight.logger.warn "Invalid sort field: '#{blacklight_params[:sort]}' was provided."
-      nil
+      search_state.sort_field&.sort
     end
 
-    def search_field
-      blacklight_config.search_fields[blacklight_params[:search_field]]
-    end
+    delegate :search_field, to: :search_state
 
     private
 

data/lib/blacklight/search_state.rb

@@ -1,4 +1,7 @@
 # frozen_string_literal: true
+
+require 'blacklight/search_state/filter_field'
+
 module Blacklight
   # This class encapsulates the search state as represented by the query
   # parameters namely: :f, :q, :page, :per_page and, :sort
@@ -78,7 +81,9 @@ module Blacklight
     deprecation_deprecate :[]
 
     def has_constraints?
-      !(query_param.blank? && filter_params.blank?)
+      Deprecation.silence(Blacklight::SearchState) do
+        !(query_param.blank? && filter_params.blank? && filters.blank?)
+      end
     end
 
     def query_param
@@ -88,11 +93,18 @@ module Blacklight
     def filter_params
       params[:f] || {}
     end
+    deprecation_deprecate filter_params: 'Use #filters instead'
 
+    # @return [Blacklight::SearchState]
     def reset(params = nil)
       self.class.new(params || ActionController::Parameters.new, blacklight_config, controller)
     end
 
+    # @return [Blacklight::SearchState]
+    def reset_search(additional_params = {})
+      reset(reset_search_params.merge(additional_params))
+    end
+
     ##
     # Extension point for downstream applications
     # to provide more interesting routing to
@@ -115,23 +127,30 @@ module Blacklight
       p
     end
 
+    def filters
+      @filters ||= blacklight_config.facet_fields.each_value.map do |value|
+        f = filter(value)
+
+        f if f.any?
+      end.compact
+    end
+
+    def filter(field_key_or_field)
+      field = field_key_or_field if field_key_or_field.is_a? Blacklight::Configuration::Field
+      field ||= blacklight_config.facet_fields[field_key_or_field]
+      field ||= Blacklight::Configuration::NullField.new(key: field_key_or_field)
+
+      (field.filter_class || FilterField).new(field, self)
+    end
+
     # adds the value and/or field to params[:f]
     # Does NOT remove request keys and otherwise ensure that the hash
     # is suitable for a redirect. See
     # add_facet_params_and_redirect
     def add_facet_params(field, item)
-      p = reset_search_params
-
-      add_facet_param(p, field, item)
-
-      if item && item.respond_to?(:fq) && item.fq
-        Array(item.fq).each do |f, v|
-          add_facet_param(p, f, v)
-        end
-      end
-
-      p
+      filter(field).add(item).params
     end
+    deprecation_deprecate add_facet_params: 'Use filter(field).add(item) instead'
 
     # Used in catalog/facet action, facets.rb view, for a click
     # on a facet value. Add on the facet params to existing
@@ -141,7 +160,9 @@ module Blacklight
     # Change the action to 'index' to send them back to
     # catalog/index with their new facet choice.
     def add_facet_params_and_redirect(field, item)
-      new_params = add_facet_params(field, item)
+      new_params = Deprecation.silence(self.class) do
+        add_facet_params(field, item)
+      end
 
       # Delete any request params from facet-specific action, needed
       # to redir to index action properly.
@@ -158,45 +179,18 @@ module Blacklight
     # @param [String] field
     # @param [String] item
     def remove_facet_params(field, item)
-      if item.respond_to? :field
-        field = item.field
-      end
-
-      facet_config = facet_configuration_for_field(field)
-
-      url_field = facet_config.key
-
-      value = facet_value_for_facet_item(item)
-
-      p = reset_search_params
-      # need to dup the facet values too,
-      # if the values aren't dup'd, then the values
-      # from the session will get remove in the show view...
-      p[:f] = (p[:f] || {}).dup
-      p[:f][url_field] = (p[:f][url_field] || []).dup
-
-      collection = p[:f][url_field]
-      # collection should be an array, because we link to ?f[key][]=value,
-      # however, Facebook (and maybe some other PHP tools) tranform that parameters
-      # into ?f[key][0]=value, which Rails interprets as a Hash.
-      if collection.is_a? Hash
-        collection = collection.values
-      end
-      p[:f][url_field] = collection - [value]
-      p[:f].delete(url_field) if p[:f][url_field].empty?
-      p.delete(:f) if p[:f].empty?
-      p
+      filter(field).remove(item).params
     end
+    deprecation_deprecate remove_facet_params: 'Use filter(field).remove(item) instead'
 
     def has_facet?(config, value: nil)
-      facet = params&.dig(:f, config.key)
-
       if value
-        (facet || []).include? value
+        filter(config).include?(value)
       else
-        facet.present?
+        filter(config).any?
       end
     end
+    deprecation_deprecate has_facet?: 'Use filter(field).include?(value) or .any? instead'
 
     # Merge the source params with the params_to_merge hash
     # @param [Hash] params_to_merge to merge into above
@@ -217,44 +211,62 @@ module Blacklight
       Parameters.sanitize(my_params)
     end
 
-    private
+    def page
+      [params[:page].to_i, 1].max
+    end
 
-    ##
-    # Reset any search parameters that store search context
-    # and need to be reset when e.g. constraints change
-    # @return [ActionController::Parameters]
-    def reset_search_params
-      Parameters.sanitize(params).except(:page, :counter)
+    def per_page
+      params[:rows].presence&.to_i ||
+        params[:per_page].presence&.to_i ||
+        blacklight_config.default_per_page
     end
 
-    # TODO: this code is duplicated in Blacklight::FacetsHelperBehavior
-    def facet_value_for_facet_item item
-      if item.respond_to? :value
-        item.value
+    def sort_field
+      if sort_field_key.blank?
+        # no sort param provided, use default
+        blacklight_config.default_sort_field
       else
-        item
+        # check for sort field key
+        blacklight_config.sort_fields[sort_field_key]
       end
     end
 
-    def add_facet_param(p, field, item)
-      if item.respond_to? :field
-        field = item.field
-      end
+    def search_field
+      blacklight_config.search_fields[search_field_key]
+    end
 
-      facet_config = facet_configuration_for_field(field)
+    def facet_page
+      [params[facet_request_keys[:page]].to_i, 1].max
+    end
 
-      url_field = facet_config.key
+    def facet_sort
+      params[facet_request_keys[:sort]]
+    end
 
-      value = facet_value_for_facet_item(item)
+    def facet_prefix
+      params[facet_request_keys[:prefix]]
+    end
 
-      p[:f] = (p[:f] || {}).dup # the command above is not deep in rails3, !@#$!@#$
-      p[:f][url_field] = (p[:f][url_field] || []).dup
+    private
 
-      if facet_config.single && p[:f][url_field].present?
-        p[:f][url_field] = []
-      end
+    def search_field_key
+      params[:search_field]
+    end
+
+    def sort_field_key
+      params[:sort]
+    end
+
+    def facet_request_keys
+      blacklight_config.facet_paginator_class.request_keys
+    end
 
-      p[:f][url_field].push(value)
+    ##
+    # Reset any search parameters that store search context
+    # and need to be reset when e.g. constraints change
+    # @return [ActionController::Parameters]
+    def reset_search_params
+      Parameters.sanitize(params).except(:page, :counter)
     end
   end
 end

data/lib/blacklight/search_state/filter_field.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Blacklight
+  class SearchState
+    # Modeling access to filter query parameters
+    class FilterField
+      # @param [Blacklight::Configuration::FacetField] config
+      attr_reader :config
+
+      # @param [Blacklight::SearchState] search_state
+      attr_reader :search_state
+
+      # @return [String,Symbol]
+      delegate :key, to: :config
+
+      # @param [Blacklight::Configuration::FacetField] config
+      # @param [Blacklight::SearchState] search_state
+      def initialize(config, search_state)
+        @config = config
+        @search_state = search_state
+      end
+
+      # @param [String,#value] a filter item to add to the url
+      # @return [Blacklight::SearchState] new state
+      def add(item)
+        new_state = search_state.reset_search
+
+        if item.respond_to?(:fq)
+          Array(item.fq).each do |f, v|
+            new_state = new_state.filter(f).add(v)
+          end
+        end
+
+        if item.respond_to?(:field) && item.field != key
+          return new_state.filter(item.field).add(item)
+        end
+
+        params = new_state.params
+        value = as_url_parameter(item)
+
+        # value could be a string
+        params[param] = (params[param] || {}).dup
+
+        if config.single
+          params[param][key] = [value]
+        else
+          params[param][key] = Array(params[param][key] || []).dup
+          params[param][key].push(value)
+        end
+
+        new_state.reset(params)
+      end
+
+      # @param [String,#value] a filter to remove from the url
+      # @return [Blacklight::SearchState] new state
+      def remove(item)
+        new_state = search_state.reset_search
+        if item.respond_to?(:field) && item.field != key
+          return new_state.filter(item.field).remove(item)
+        end
+
+        params = new_state.params
+        value = as_url_parameter(item)
+
+        # need to dup the facet values too,
+        # if the values aren't dup'd, then the values
+        # from the session will get remove in the show view...
+        params[param] = (params[param] || {}).dup
+        params[param][key] = (params[param][key] || []).dup
+
+        collection = params[param][key]
+        # collection should be an array, because we link to ?f[key][]=value,
+        # however, Facebook (and maybe some other PHP tools) tranform that parameters
+        # into ?f[key][0]=value, which Rails interprets as a Hash.
+        if collection.is_a? Hash
+          Deprecation.warn(self, 'Normalizing parameters in FilterField#remove is deprecated')
+          collection = collection.values
+        end
+        params[param][key] = collection - Array(value)
+        params[param].delete(key) if params[param][key].empty?
+        params.delete(param) if params[param].empty?
+
+        new_state.reset(params)
+      end
+
+      # @return [Array] an array of applied filters
+      def values
+        params = search_state.params
+        Array(params.dig(param, key)) || []
+      end
+      delegate :any?, to: :values
+
+      # @param [String,#value] a filter to remove from the url
+      # @return [Boolean] whether the provided filter is currently applied/selected
+      def include?(item)
+        if item.respond_to?(:field) && item.field != key
+          return search_state.filter(item.field).selected?(item)
+        end
+
+        value = as_url_parameter(item)
+        params = search_state.params
+
+        (params.dig(param, key) || []).include?(value)
+      end
+
+      private
+
+      def param
+        :f
+      end
+
+      # TODO: this code is duplicated in Blacklight::FacetsHelperBehavior
+      def as_url_parameter(item)
+        if item.respond_to? :value
+          item.value
+        else
+          item
+        end
+      end
+    end
+  end
+end