blacklight 7.11.1 → 7.12.0

data/lib/blacklight/abstract_repository.rb

@@ -1,33 +1,42 @@
 # frozen_string_literal: true
 module Blacklight
+  # Base class for Blacklight repository adapters
   class AbstractRepository
+    # @return [Blacklight::Configuration]
     attr_accessor :blacklight_config
+
+    # Direct writer for the connection
     attr_writer :connection
 
-    # ActiveSupport::Benchmarkable requires a logger method
+    # (Note: ActiveSupport::Benchmarkable requires a logger method)
+    # @return [Logger]
     attr_writer :logger
 
     include ActiveSupport::Benchmarkable
 
+    ##
+    # @param [Blacklight::Configuration] blacklight_config
     def initialize blacklight_config
       @blacklight_config = blacklight_config
     end
 
+    ##
+    # The raw data store connection
     def connection
       @connection ||= build_connection
     end
 
     ##
     # Find a single document result by a known id
-    # @param [String] id document's unique key value
-    # @param [Hash] params additional query parameters
+    # @param [String] _id document's unique key value
+    # @param [Hash] _params additional query parameters
     def find(_id, _params = {})
       raise NotImplementedError
     end
 
     ##
     # Execute a search query against a search index
-    # @param [Hash] params query parameters
+    # @param [Hash] _params query parameters
     def search(_params = {})
       raise NotImplementedError
     end

data/lib/blacklight/configuration.rb

@@ -71,7 +71,7 @@ module Blacklight
             # solr field to use to render a document title
             title_field: nil,
             # solr field to use to render format-specific partials
-            display_type_field: 'format',
+            display_type_field: nil,
             # partials to render for each document(see #render_document_partials)
             partials: [:index_header, :thumbnail, :index],
             document_actions: NestedOpenStructWithHashAccess.new(ToolConfig),
@@ -86,7 +86,7 @@ module Blacklight
             # document presenter class used by helpers and views
             document_presenter_class: nil,
             document_component: nil,
-            display_type_field: 'format',
+            display_type_field: nil,
             # Default route parameters for 'show' requests.
             # Set this to a hash with additional arguments to merge into the route,
             # or set `controller: :current` to route to the current controller.
@@ -256,6 +256,11 @@ module Blacklight
       facet_fields.select { |_facet, opts| group == opts[:group] }.values.map(&:field)
     end
 
+    # @return [Array<String>] a list of facet groups
+    def facet_group_names
+      facet_fields.map { |_facet, opts| opts[:group] }.uniq
+    end
+
     # Add any configured facet fields to the default solr parameters hash
     # @overload add_facet_fields_to_solr_request!
     #    add all facet fields to the solr request
@@ -360,7 +365,7 @@ module Blacklight
     def index_fields_for(document_or_display_types)
       display_types = if document_or_display_types.is_a? Blacklight::Document
                         Deprecation.warn self, "Calling index_fields_for with a #{document_or_display_types.class} is deprecated and will be removed in Blacklight 8. Pass the display type instead."
-                        document_or_display_types[index.display_type_field]
+                        document_or_display_types[index.display_type_field || 'format']
                       else
                         document_or_display_types
                       end
@@ -380,7 +385,7 @@ module Blacklight
     def show_fields_for(document_or_display_types)
       display_types = if document_or_display_types.is_a? Blacklight::Document
                         Deprecation.warn self, "Calling show_fields_for with a #{document_or_display_types.class} is deprecated and will be removed in Blacklight 8. Pass the display type instead."
-                        document_or_display_types[show.display_type_field]
+                        document_or_display_types[show.display_type_field || 'format']
                       else
                         document_or_display_types
                       end
@@ -398,7 +403,8 @@ module Blacklight
 
     def add_action(config_hash, name, opts)
       config = Blacklight::Configuration::ToolConfig.new opts
-      config.name = name
+      config.name ||= name
+      config.key = name
       yield(config) if block_given?
       config_hash[name] = config
     end

data/lib/blacklight/configuration/display_field.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+module Blacklight
+  class Configuration::DisplayField < Blacklight::Configuration::Field
+    ##
+    # The following is a non-exhaustive list of display field config parameters that are used
+    # by Blacklight directly. Application-specific code or plugins may add or replace
+    # the parameters and behaviors specified below.
+    #
+
+    ##
+    # Data parameters:
+    # @!attribute values
+    #  @return [Proc]
+    # @!attribute accessor
+    #  @return [Boolean,Symbol]
+    # @!attribute highlight
+    #  @return [Boolean]
+    # @!attribute default
+    #  @return [Object]
+    # @!attribute solr_params
+    #  @return [Hash]
+    # @!attribute include_in_request
+    #  @return [Boolean]
+
+    ##
+    # Rendering:
+    # @!attribute presenter
+    #   @return [Blacklight::FieldPresenter]
+    # @!attribute component
+    #   @return [Blacklight::MetadataFieldComponent]
+
+    ##
+    # Default rendering pipeline:
+    # @!attribute link_to_facet
+    #   @return [Boolean]
+    # @!attribute link_to_search
+    #   @deprecated use link_to_facet instead.
+    #   @return [Boolean]
+    # @!attribute itemprop
+    #   @return [String]
+    # @!attribute separator_options
+    #   @return [Hash]
+
+    # @param [Blacklight::Configuration] _blacklight_config
+    def normalize! _blacklight_config = nil
+      super
+      self.presenter ||= Blacklight::FieldPresenter
+    end
+  end
+end

data/lib/blacklight/configuration/facet_field.rb

@@ -1,6 +1,63 @@
 # frozen_string_literal: true
 module Blacklight
   class Configuration::FacetField < Blacklight::Configuration::Field
+    ##
+    # The following is a non-exhaustive list of facet config parameters that are used
+    # by Blacklight directly. Application-specific code or plugins may add or replace
+    # the parameters and behaviors specified below.
+    #
+
+    ##
+    # Display parameters:
+    # @!attribute collapse
+    #   @return [Boolean] whether to display the facet in a collapsed state by default
+    # @!attribute show
+    #   @return [Boolean] whether to show the facet to the user or not (very similar to the more generic if/unless)
+    # @!attribute index_range
+    #   @return [Enumerable] a list of facet prefixes (default: A-Z) to allow users to 'jump' to particular values
+    # @!attribute date
+    #   @return [Symbol|Hash] the i18n localization option for a date or time value; used as the second parameter for the I18n.l method
+    # @!attribute link_to_facet
+    #   @return [Boolean]
+    # @!attribute link_to_search
+    #   @deprecated use link_to_facet instead.
+    #   @return [Boolean]
+    # @!attribute helper_method
+    #   @return [Symbol] the name of a helper method used to display the facet's value to the user; it receives the facet value.
+    # @!attribute url_method
+    #   @return [Symbol] The name of a helper to use for getting the url for a facet link; the method will receive the facet field's key and value.
+    # @!attribute collapsing
+    #   @return [Boolean] display pivot facets with an expand / collapse toggle
+    # @!attribute icons
+    #   @return [Hash] Icons to use for pivot facet expand + collapse
+
+    ##
+    # Query parameters:
+    # @!attribute sort
+    #   @return [String] the ordering of the facet field constraints; when using Solr, this is either 'count' or 'index'
+    # @!attribute single
+    #   @return [Boolean] whether the facet values are mutually exclusive; or, for more granular control, see tag + ex
+    # @!attribute tag
+    #   @return [String] See https://lucene.apache.org/solr/guide/8_6/faceting.html#tagging-and-excluding-filters
+    # @!attribute ex
+    #   @return [String] See https://lucene.apache.org/solr/guide/8_6/faceting.html#tagging-and-excluding-filters
+    # @!attribute query
+    #   @return [Hash{String => Hash}] Provides support for facet queries; the keys are mapped to user-facing parameters, and the values
+    #      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 []
+
+    ##
+    # Rendering:
+    # @!attribute presenter
+    #   @return [Blacklight::FacetFieldPresenter]
+    # @!attribute component
+    #   @return [Blacklight::FacetFieldListComponent]
+    # @!attribute item_component
+    #   @return [Blacklight::FacetItemComponent]
+    # @!attribute partial
+    #   @return [String] Rails view partial used to render the facet field
+
     extend Deprecation
 
     def normalize! blacklight_config = nil
@@ -10,7 +67,7 @@ module Blacklight
       self.show = true if show.nil?
       self.if = show if self.if.nil?
       self.index_range = 'A'..'Z' if index_range == true
-      self.presenter = Blacklight::FacetFieldPresenter
+      self.presenter ||= Blacklight::FacetFieldPresenter
 
       if link_to_search
         Deprecation.warn(Blacklight::Configuration::FacetField, '`link_to_search:` is deprecated, use `link_to_facet:` instead')

data/lib/blacklight/configuration/field.rb

@@ -1,6 +1,19 @@
 # frozen_string_literal: true
 module Blacklight
   class Configuration::Field < OpenStructWithHashAccess
+    # @!attribute field
+    #   @return [String] the field name in the search response data from Solr
+    # @!attribute key
+    #   @return [String] the field name as used in the application + user-facing HTML
+    # @!attribute label
+    #   @return [String, Symbol] the label or i18n key to use for labeling data from this field
+    # @!attribute if
+    #   @return [Proc, Symbol] a proc or the symbol name of a helper to test whether the field should be rendered.
+    #     The helper or proc will receive this field configuration object as the first parameter. See Blacklight::Configuration::Context.
+    # @!attribute unless
+    #   @return [Proc, Symbol] a proc or the symbol name of a helper to test whether the field should not be rendered.
+    #     The helper or proc will receive this field configuration object as the first parameter. See Blacklight::Configuration::Context.
+
     def normalize! _blacklight_config = nil
       self.field ||= key
       self.key ||= self.field

data/lib/blacklight/configuration/index_field.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+module Blacklight
+  class Configuration::IndexField < Blacklight::Configuration::DisplayField
+  end
+end

data/lib/blacklight/configuration/search_field.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 module Blacklight
   class Configuration::SearchField < Blacklight::Configuration::Field
+    # @!attribute include_in_simple_select
+    # @!attribute qt
+
     def normalize! blacklight_config = nil
       self.if = include_in_simple_select if self.if.nil?
 

data/lib/blacklight/configuration/show_field.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+module Blacklight
+  class Configuration::ShowField < Blacklight::Configuration::DisplayField
+  end
+end

data/lib/blacklight/configuration/sort_field.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 module Blacklight
   class Configuration::SortField < Blacklight::Configuration::Field
+    # @!attribute sort
+    #   @return [String] the sort specification to use; defaults to the value of field (which is used in the user-facing parameters)
+
     def normalize! blacklight_config = nil
       super
       self.field ||= label.try(:parameterize)

data/lib/blacklight/configuration/tool_config.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 module Blacklight
   class Configuration::ToolConfig < OpenStructWithHashAccess
+    # @!attribute partial
   end
 end

data/lib/blacklight/configuration/view_config.rb

@@ -1,17 +1,42 @@
 # frozen_string_literal: true
 class Blacklight::Configuration
   class ViewConfig < Blacklight::OpenStructWithHashAccess
+    # @!attribute partials
+    #   @return [Array<String>] partials to render for each document(see #render_document_partials)
+    # @!attribute document_presenter_class
+    #   @return [Class] document presenter class used by helpers and views
+    # @!attribute document_component
+    #   @return [Class] component class used to render a document; defaults to Blacklight::DocumentComponent
+    # @!attribute title_field
+    #   @return [String, Symbol] solr field to use to render a document title
+    # @!attribute display_type_field
+    #   @return [String, Symbol] solr field to use to render format-specific partials
+    # @!attribute document_actions
+    #   @return [NestedOpenStructWithHashAccess{Symbol => Blacklight::Configuration::ToolConfig}] 'tools' to render for each document
     def search_bar_presenter_class
       super || Blacklight::SearchBarPresenter
     end
 
     class Show < ViewConfig
+      # @!attribute route
+      #   @return [Hash] Default route parameters for 'show' requests.
+      #     Set this to a hash with additional arguments to merge into the route,
+      #     or set `controller: :current` to route to the current controller.
+
       def document_presenter_class
         super || Blacklight::ShowPresenter
       end
     end
 
     class Index < ViewConfig
+      # @!attribute group
+      #   @return [false, String, Symbol] what field, if any, to use to render grouped results
+      # @!attribute respond_to
+      #   @return [OpenStructWithHashAccess{Symbol => OpenStruct}] additional response formats for search results;
+      #      see Blacklight::Catalog#additional_response_formats for information about the OpenStruct data
+      # @!attribute collection_actions
+      #   @return [String, Symbol]
+
       def document_presenter_class
         super || Blacklight::IndexPresenter
       end

data/lib/blacklight/search_state.rb

@@ -3,6 +3,8 @@ module Blacklight
   # This class encapsulates the search state as represented by the query
   # parameters namely: :f, :q, :page, :per_page and, :sort
   class SearchState
+    extend Deprecation
+
     attr_reader :blacklight_config # Must be called blacklight_config, because Blacklight::Facet calls blacklight_config.
     attr_reader :params
 
@@ -52,13 +54,13 @@ module Blacklight
     alias to_h to_hash
 
     def to_unsafe_h
-      Deprecation.warn(self, 'Use SearchState#to_h instead of SearchState#to_unsafe_h')
+      Deprecation.warn(self.class, 'Use SearchState#to_h instead of SearchState#to_unsafe_h')
       to_hash
     end
 
     def method_missing(method_name, *arguments, &block)
       if @params.respond_to?(method_name)
-        Deprecation.warn(self, "Calling `#{method_name}` on Blacklight::SearchState " \
+        Deprecation.warn(self.class, "Calling `#{method_name}` on Blacklight::SearchState " \
           'is deprecated and will be removed in Blacklight 8. Call #to_h first if you ' \
           ' need to use hash methods (or, preferably, use your own SearchState implementation)')
         @params.public_send(method_name, *arguments, &block)

data/lib/blacklight/solr/repository.rb

@@ -23,7 +23,7 @@ module Blacklight::Solr
       send_and_receive blacklight_config.solr_path, params.reverse_merge(qt: blacklight_config.qt)
     end
 
-    # @param [Hash] params
+    # @param [Hash] request_params
     # @return [Blacklight::Suggest::Response]
     def suggestions(request_params)
       suggest_results = connection.send_and_receive(suggest_handler_path, params: request_params)

data/lib/generators/blacklight/templates/catalog_controller.rb

@@ -182,22 +182,23 @@ class <%= controller_name.classify %>Controller < ApplicationController
     end
 
     # "sort results by" select (pulldown)
-    # label in pulldown is followed by the name of the SOLR field to sort by and
+    # label in pulldown is followed by the name of the Solr field to sort by and
     # whether the sort is ascending or descending (it must be asc or desc
-    # except in the relevancy case).
-    config.add_sort_field 'score desc, pub_date_si desc, title_si asc', label: 'relevance'
-    config.add_sort_field 'pub_date_si desc, title_si asc', label: 'year'
-    config.add_sort_field 'author_si asc, title_si asc', label: 'author'
+    # except in the relevancy case). Add the sort: option to configure a
+    # custom Blacklight url parameter value separate from the Solr sort fields.
+    config.add_sort_field 'relevance', sort: 'score desc, pub_date_si desc, title_si asc', label: 'relevance'
+    config.add_sort_field 'year-desc', sort: 'pub_date_si desc, title_si asc', label: 'year'
+    config.add_sort_field 'author', sort: 'author_si asc, title_si asc', label: 'author'
     config.add_sort_field 'title_si asc, pub_date_si desc', label: 'title'
 
     # If there are more than this many search results, no spelling ("did you
     # mean") suggestion is offered.
     config.spell_max = 5
 
-    # Configuration for autocomplete suggestor
+    # Configuration for autocomplete suggester
     config.autocomplete_enabled = true
     config.autocomplete_path = 'suggest'
-    # if the name of the solr.SuggestComponent provided in your solrcongig.xml is not the
+    # if the name of the solr.SuggestComponent provided in your solrconfig.xml is not the
     # default 'mySuggester', uncomment and provide it below
     # config.autocomplete_suggester = 'mySuggester'
   end

data/spec/components/blacklight/document/action_component_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Blacklight::Document::ActionComponent, type: :component do
+  subject(:component) { described_class.new(document: document, action: action, **attr) }
+
+  let(:action) { Blacklight::Configuration::ToolConfig.new(key: 'some_tool', name: 'some_tool', component: true) }
+  let(:attr) { {} }
+  let(:view_context) { controller.view_context }
+  let(:render) do
+    component.render_in(view_context)
+  end
+
+  let(:rendered) do
+    Capybara::Node::Simple.new(render)
+  end
+
+  let(:document) do
+    SolrDocument.new(
+      id: 'x'
+    )
+  end
+
+  it 'renders an action link' do
+    if Rails.version >= '6'
+      allow(view_context).to receive(:some_tool_solr_document_path).with(document, only_path: true).and_return('/asdf')
+    else
+      allow(view_context).to receive(:some_tool_solr_document_path).with(document).and_return('/asdf')
+    end
+    expect(rendered).to have_link 'Some tool', href: '/asdf'
+  end
+
+  context 'with a partial configured' do
+    let(:action) { Blacklight::Configuration::ToolConfig.new(name: '', partial: '/some/tool') }
+
+    it 'render the partial' do
+      allow(view_context).to receive(:render).with(hash_including(partial: '/some/tool')).and_return('tool')
+
+      expect(rendered).to have_content 'tool'
+    end
+  end
+end

data/spec/components/blacklight/document/group_component_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Blacklight::Document::GroupComponent, type: :component do
+  subject(:component) { described_class.new(group: group, **attr) }
+
+  let(:attr) { {} }
+  let(:view_context) { controller.view_context }
+  let(:render) do
+    component.render_in(view_context)
+  end
+
+  let(:rendered) do
+    Capybara::Node::Simple.new(render)
+  end
+
+  let(:docs) { 10.times.map { double } }
+
+  let(:group) do
+    instance_double(Blacklight::Solr::Response::Group, key: 'group1', field: 'group_field', total: 15, docs: docs)
+  end
+
+  before do
+    allow(view_context).to receive(:render_document_index).with(docs).and_return('results')
+  end
+
+  it 'renders the group with a header' do
+    expect(rendered).to have_selector 'div.group'
+    expect(rendered).to have_selector 'h2', text: 'group1'
+    expect(rendered).not_to have_link 'more'
+  end
+
+  it 'renders the group documents' do
+    expect(rendered).to have_content 'results'
+  end
+
+  context 'with a limit applied' do
+    let(:attr) { { group_limit: 5 } }
+
+    it 'renders a control to see more results' do
+      expect(rendered).to have_link 'more'
+    end
+  end
+end