blacklight 7.11.1 → 7.12.0

data/app/controllers/concerns/blacklight/facet.rb

@@ -4,20 +4,27 @@ module Blacklight
   # They are only dependent on `blacklight_config` and `@response`
   #
   module Facet
+    extend Deprecation
     delegate :facet_configuration_for_field, :facet_field_names, to: :blacklight_config
 
+    # @deprecated
+    # @param [Blacklight::Configuration::Facet] field_config
+    # @param [Object] response_data
+    # @return [Blacklight::FacetPaginator]
     def facet_paginator(field_config, response_data)
       blacklight_config.facet_paginator_class.new(
         response_data.items,
         sort: response_data.sort,
         offset: response_data.offset,
         prefix: response_data.prefix,
-        limit: facet_limit_for(field_config.key)
+        limit: Deprecation.silence(Blacklight::Catalog) { facet_limit_for(field_config.key) }
       )
     end
+    deprecation_deprecate facet_paginator: 'Use Blacklight::FacetFieldPresenter#paginator instead'
 
     # @param fields [Array<String>] a list of facet field names
     # @return [Array<Solr::Response::Facets::FacetField>]
+    # @deprecated
     def facets_from_request(fields = facet_field_names, response = nil)
       unless response
         Deprecation.warn(self, 'Calling facets_from_request without passing the ' \
@@ -25,14 +32,20 @@ module Blacklight
           '8.0.0')
         response = @response
       end
-      fields.map { |field| facet_by_field_name(field, response) }.compact
-    end
 
-    def facet_group_names
-      blacklight_config.facet_fields.map { |_facet, opts| opts[:group] }.uniq
+      Deprecation.silence(Blacklight::Facet) do
+        fields.map { |field| facet_by_field_name(field, response) }.compact
+      end
     end
+    deprecation_deprecate facets_from_request: 'Removed without replacement'
+
+    delegate :facet_group_names, to: :blacklight_config
+    deprecation_deprecate facet_group_names: 'Use blacklight_config.facet_group_names instead'
 
     # Get a FacetField object from the @response
+    # @deprecated
+    # @private
+    # @return [Blacklight::Solr::Response::Facets::FacetField]
     def facet_by_field_name(field_or_field_name, response = nil)
       unless response
         Deprecation.warn(self, 'Calling facet_by_field_name without passing the ' \
@@ -51,5 +64,6 @@ module Blacklight
         field_or_field_name
       end
     end
+    deprecation_deprecate facet_by_field_name: 'Removed without replacement'
   end
 end

data/app/controllers/concerns/blacklight/search_fields.rb

@@ -26,15 +26,21 @@
 #
 ##
 module Blacklight::SearchFields
+  extend Deprecation
+
   # Looks up search field config list from blacklight_config[:search_fields], and
   # 'normalizes' all field config hashes using normalize_config method.
+  # @deprecated
   def search_field_list
     blacklight_config.search_fields.values
   end
+  deprecation_deprecate search_field_list: 'Use blacklight_config.search_fields instead'
 
   # Returns default search field, used for simpler display in history, etc.
   # if not set in blacklight_config, defaults to first field listed in #search_field_list
+  # @deprecated
   def default_search_field
-    blacklight_config.default_search_field || search_field_list.first
+    blacklight_config.default_search_field || (Deprecation.silence(Blacklight::SearchFields) { search_field_list.first })
   end
+  deprecation_deprecate default_search_field: 'Use Blacklight::Configuration#default_search_field'
 end

data/app/helpers/blacklight/blacklight_helper_behavior.rb

@@ -8,6 +8,8 @@ module Blacklight::BlacklightHelperBehavior
   include Blacklight::LayoutHelperBehavior
   include Blacklight::IconHelperBehavior
 
+  # @!group Layout helpers
+
   ##
   # Get the name of this application from an i18n string
   # key: blacklight.application_name
@@ -42,14 +44,16 @@ module Blacklight::BlacklightHelperBehavior
   # @option options [Boolean] :unique ensures only one link is output for every
   #     content type, e.g. as required by atom
   # @option options [Array<String>] :exclude array of format shortnames to not include in the output
+  # @return [String]
   def render_link_rel_alternates(document = @document, options = {})
     return if document.nil?
 
-    presenter(document).link_rel_alternates(options)
+    document_presenter(document).link_rel_alternates(options)
   end
 
   ##
   # Render OpenSearch headers for this search
+  # @deprecated
   # @return [String]
   def render_opensearch_response_metadata
     render partial: 'catalog/opensearch_response_metadata', locals: { response: @response }
@@ -78,13 +82,18 @@ module Blacklight::BlacklightHelperBehavior
     search_bar_presenter.render
   end
 
+  # @!group Presenter extension helpers
+  ##
+  # @return [Blacklight::SearchBarPresenter]
   def search_bar_presenter
     @search_bar ||= search_bar_presenter_class.new(controller, blacklight_config)
   end
 
+  # @!group Document helpers
   ##
   # Determine whether to render a given field in the index view.
   #
+  # @deprecated
   # @param [SolrDocument] document
   # @param [Blacklight::Configuration::Field] field_config
   # @return [Boolean]
@@ -96,6 +105,7 @@ module Blacklight::BlacklightHelperBehavior
   ##
   # Determine whether to render a given field in the show view
   #
+  # @deprecated
   # @param [SolrDocument] document
   # @param [Blacklight::Configuration::Field] field_config
   # @return [Boolean]
@@ -106,7 +116,8 @@ module Blacklight::BlacklightHelperBehavior
 
   ##
   # Check if a document has (or, might have, in the case of accessor methods) a value for
-  # the given solr field
+  # the given solr
+  # @deprecated
   # @param [SolrDocument] document
   # @param [Blacklight::Configuration::Field] field_config
   # @return [Boolean]
@@ -117,24 +128,31 @@ module Blacklight::BlacklightHelperBehavior
       field_config.accessor
   end
 
+  # @!group Search result helpers
   ##
   # Determine whether to display spellcheck suggestions
   #
+  # @deprecated
   # @param [Blacklight::Solr::Response] response
   # @return [Boolean]
   def should_show_spellcheck_suggestions? response
-    # The spelling response field may be missing from non solr repositories.
-    response.total <= spell_check_max &&
-      !response.spelling.nil? &&
-      response.spelling.words.any?
+    Deprecation.silence(Blacklight::ConfigurationHelperBehavior) do
+      # The spelling response field may be missing from non solr repositories.
+      response.total <= spell_check_max &&
+        !response.spelling.nil? &&
+        response.spelling.words.any?
+    end
   end
+  deprecation_deprecate should_show_spellcheck_suggestions?: 'moving into a private method of Blacklight::Response::SpellcheckComponent'
 
+  # @!group Document helpers
   ##
   # Render the index field label for a document
   #
   # Translations for index field labels should go under blacklight.search.fields
   # They are picked up from there by a value "%{label}" in blacklight.search.index.label
   #
+  # @deprecated
   # @overload render_index_field_label(options)
   #   Use the default, document-agnostic configuration
   #   @param [Hash] opts
@@ -145,6 +163,7 @@ module Blacklight::BlacklightHelperBehavior
   #   @param [SolrDocument] doc
   #   @param [Hash] opts
   #   @option opts [String] :field
+  # @return [String]
   def render_index_field_label *args
     options = args.extract_options!
     document = args.first
@@ -160,6 +179,7 @@ module Blacklight::BlacklightHelperBehavior
   ##
   # Render the show field label for a document
   #
+  # @deprecated
   # @overload render_document_show_field_label(options)
   #   Use the default, document-agnostic configuration
   #   @param [Hash] opts
@@ -170,6 +190,7 @@ module Blacklight::BlacklightHelperBehavior
   #   @param [SolrDocument] doc
   #   @param [Hash] opts
   #   @option opts [String] :field
+  # @return [String]
   def render_document_show_field_label *args
     options = args.extract_options!
     document = args.first
@@ -187,28 +208,33 @@ module Blacklight::BlacklightHelperBehavior
   # Get the value of the document's "title" field, or a placeholder
   # value (if empty)
   #
+  # @deprecated
   # @param [SolrDocument] document
   # @return [String]
   def document_heading document = nil
     document ||= @document
-    presenter(document).heading
+    document_presenter(document).heading
   end
+  deprecation_deprecate document_heading: 'Use Blacklight::DocumentPresenter#heading instead'
 
   ##
   # Get the document's "title" to display in the <title> element.
   # (by default, use the #document_heading)
   #
+  # @deprecated
   # @see #document_heading
   # @param [SolrDocument] document
   # @return [String]
   def document_show_html_title document = nil
     document ||= @document
 
-    presenter(document).html_title
+    document_presenter(document).html_title
   end
+  deprecation_deprecate document_show_html_title: 'Use Blacklight::DocumentPresenter#html_title instead'
 
   ##
   # Render the document "heading" (title) in a content tag
+  # @deprecated
   # @overload render_document_heading(document, options)
   #   @param [SolrDocument] document
   #   @param [Hash] options
@@ -216,14 +242,16 @@ module Blacklight::BlacklightHelperBehavior
   # @overload render_document_heading(options)
   #   @param [Hash] options
   #   @option options [Symbol] :tag
+  # @return [String]
   def render_document_heading(*args)
     options = args.extract_options!
     document = args.first
     tag = options.fetch(:tag, :h4)
     document ||= @document
 
-    content_tag(tag, presenter(document).heading, itemprop: "name")
+    content_tag(tag, document_presenter(document).heading, itemprop: "name")
   end
+  deprecation_deprecate render_document_heading: 'Removed without replacement'
 
   ##
   # Get the current "view type" (and ensure it is a valid type)
@@ -240,6 +268,7 @@ module Blacklight::BlacklightHelperBehavior
     end
   end
 
+  # @!group Search result helpers
   ##
   # Render a partial of an arbitrary format inside a
   # template of a different format. (e.g. render an HTML
@@ -263,47 +292,128 @@ module Blacklight::BlacklightHelperBehavior
   #
   # Default to false if there's no response object available (sometimes the case
   #   for tests, but might happen in other circumstances too..)
+  # @return [Boolean]
   def render_grouped_response? response = @response
     response&.grouped?
   end
 
+  # @!group Presenter extension helpers
   ##
   # Returns a document presenter for the given document
   # TODO: Move this to the controller. It can just pass a presenter or set of presenters.
+  # @deprecated
+  # @return [Blacklight::DocumentPresenter]
   def presenter(document)
-    case action_name
-    when 'show', 'citation'
-      show_presenter(document)
-    else
-      index_presenter(document)
+    Deprecation.warn(Blacklight::BlacklightHelperBehavior, '#presenter is deprecated; use #document_presenter instead')
+
+    # As long as the presenter methods haven't been overridden, we can use the new behavior
+    if method(:show_presenter).owner == Blacklight::BlacklightHelperBehavior &&
+       method(:index_presenter).owner == Blacklight::BlacklightHelperBehavior
+      return document_presenter_class(document).new(document, self)
+    end
+
+    Deprecation.warn(Blacklight::BlacklightHelperBehavior, '#show_presenter and/or #index_presenter have been overridden; please override #document_presenter instead')
+
+    Deprecation.silence(Blacklight::BlacklightHelperBehavior) do
+      case action_name
+      when 'show', 'citation'
+        show_presenter(document)
+      else
+        index_presenter(document)
+      end
+    end
+  end
+
+  ##
+  # Returns a document presenter for the given document
+  def document_presenter(document)
+    Deprecation.silence(Blacklight::BlacklightHelperBehavior) do
+      presenter(document)
     end
   end
 
+  # @deprecated
+  # @return [Blacklight::ShowPresenter]
   def show_presenter(document)
-    show_presenter_class(document).new(document, self)
+    Deprecation.warn(Blacklight::BlacklightHelperBehavior, '#show_presenter is deprecated; use #document_presenter instead')
+
+    if method(:show_presenter_class).owner != Blacklight::BlacklightHelperBehavior
+      Deprecation.warn(Blacklight::BlacklightHelperBehavior, '#show_presenter_class has been overridden; please override #document_presenter_class instead')
+    end
+
+    Deprecation.silence(Blacklight::BlacklightHelperBehavior) do
+      show_presenter_class(document).new(document, self)
+    end
   end
 
+  # @deprecated
+  # @return [Blacklight::IndexPresenter]
   def index_presenter(document)
-    index_presenter_class(document).new(document, self)
+    Deprecation.warn(Blacklight::BlacklightHelperBehavior, '#index_presenter is deprecated; use #document_presenter instead')
+
+    if method(:index_presenter_class).owner != Blacklight::BlacklightHelperBehavior
+      Deprecation.warn(Blacklight::BlacklightHelperBehavior, '#index_presenter_class has been overridden; please override #document_presenter_class instead')
+    end
+
+    Deprecation.silence(Blacklight::BlacklightHelperBehavior) do
+      index_presenter_class(document).new(document, self)
+    end
+  end
+
+  ##
+  # Override this method if you want to use a differnet presenter for your documents
+  def document_presenter_class(document)
+    Deprecation.silence(Blacklight::BlacklightHelperBehavior) do
+      case action_name
+      when 'show', 'citation'
+        show_presenter_class(document)
+      else
+        index_presenter_class(document)
+      end
+    end
   end
 
   ##
   # Override this method if you want to use a different presenter class
+  # @deprecated
+  # @return [Class]
   def show_presenter_class(_document)
+    Deprecation.warn(Blacklight::BlacklightHelperBehavior, '#show_presenter_class is deprecated; use #document_presenter_class instead')
+
     blacklight_config.show.document_presenter_class
   end
 
+  # @deprecated
+  # @return [Class]
   def index_presenter_class(_document)
-    blacklight_config.index.document_presenter_class
+    Deprecation.warn(Blacklight::BlacklightHelperBehavior, '#index_presenter_class is deprecated; use #document_presenter_class instead')
+
+    (blacklight_config.view.key?(document_index_view_type) && blacklight_config.dig(:view, document_index_view_type, :document_presenter_class)) ||
+      blacklight_config.index.document_presenter_class
   end
 
+  # @return [Class]
   def search_bar_presenter_class
     blacklight_config.index.search_bar_presenter_class
   end
 
+  # @!group Layout helpers
   ##
   # Open Search discovery tag for HTML <head> links
+  # @return [String]
   def opensearch_description_tag title, href
     tag :link, href: href, title: title, type: "application/opensearchdescription+xml", rel: "search"
   end
+
+  # @private
+
+  def self.blacklight_path
+    @blacklight_path ||= Gem.loaded_specs["blacklight"].source.path.to_s
+  end
+
+  def partial_from_blacklight?(partial)
+    path = lookup_context.find_all(partial, lookup_context.prefixes + [""], true).first&.identifier
+
+    path&.starts_with?(Blacklight::BlacklightHelperBehavior.blacklight_path)
+  end
 end

data/app/helpers/blacklight/catalog_helper_behavior.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# Helper methods for catalog-like controllers
 module Blacklight::CatalogHelperBehavior
   extend Deprecation
   self.deprecation_horizon = 'blacklight 8.0'
@@ -13,18 +14,21 @@ module Blacklight::CatalogHelperBehavior
 
   # @param [Hash] options
   # @option options :route_set the route scope to use when constructing the link
+  # @return [String]
   def rss_feed_link_tag(options = {})
     auto_discovery_link_tag(:rss, feed_link_url('rss', options), title: t('blacklight.search.rss_feed'))
   end
 
   # @param [Hash] options
   # @option options :route_set the route scope to use when constructing the link
+  # @return [String]
   def atom_feed_link_tag(options = {})
     auto_discovery_link_tag(:atom, feed_link_url('atom', options), title: t('blacklight.search.atom_feed'))
   end
 
   # @param [Hash] options
   # @option options :route_set the route scope to use when constructing the link
+  # @return [String]
   def json_api_link_tag(options = {})
     auto_discovery_link_tag(:json, feed_link_url('json', options), type: 'application/json')
   end
@@ -96,6 +100,7 @@ module Blacklight::CatalogHelperBehavior
   # Like #page_entries_info above, but for an individual
   # item show page. Displays "showing X of Y items" message.
   #
+  # @deprecated
   # @see #page_entries_info
   # @return [String]
   def item_page_entry_info
@@ -108,6 +113,7 @@ module Blacklight::CatalogHelperBehavior
   ##
   # Look up search field user-displayable label
   # based on params[:qt] and blacklight_configuration.
+  # @return [String]
   def search_field_label(params)
     h(label_for_search_field(params[:search_field]))
   end
@@ -131,9 +137,10 @@ module Blacklight::CatalogHelperBehavior
   ##
   # Get the classes to add to a document's div
   #
+  # @param [Blacklight::Document] document
   # @return [String]
   def render_document_class(document = @document)
-    types = presenter(document).display_type
+    types = document_presenter(document).display_type
     return if types.blank?
 
     Array(types).compact.map do |t|
@@ -141,6 +148,10 @@ module Blacklight::CatalogHelperBehavior
     end.join(' ')
   end
 
+  ##
+  # Return a prefix for the document classes infered from the document
+  # @see #render_document_class
+  # @return [String]
   def document_class_prefix
     'blacklight-'
   end
@@ -162,7 +173,7 @@ module Blacklight::CatalogHelperBehavior
   ##
   # Render the main content partial for a document
   #
-  # @param [SolrDocument] document
+  # @param [SolrDocument] _document
   # @return [String]
   def render_document_main_content_partial(_document = @document)
     render partial: 'show_main_content'
@@ -192,6 +203,7 @@ module Blacklight::CatalogHelperBehavior
   # If no search parameters have been given, we should
   # auto-focus the user's cursor into the searchbox
   #
+  # @deprecated
   # @return [Boolean]
   def should_autofocus_on_search_box?
     controller.is_a?(Blacklight::Catalog) &&
@@ -203,10 +215,11 @@ module Blacklight::CatalogHelperBehavior
   ##
   # Does the document have a thumbnail to render?
   #
+  # @deprecated
   # @param [SolrDocument] document
   # @return [Boolean]
   def has_thumbnail? document
-    index_presenter(document).thumbnail.exists?
+    document_presenter(document).thumbnail.exists?
   end
   deprecation_deprecate has_thumbnail?: "use IndexPresenter#thumbnail.exists?"
 
@@ -214,18 +227,20 @@ module Blacklight::CatalogHelperBehavior
   # Render the thumbnail, if available, for a document and
   # link it to the document record.
   #
+  # @deprecated
   # @param [SolrDocument] document
   # @param [Hash] image_options to pass to the image tag
   # @param [Hash] url_options to pass to #link_to_document
   # @return [String]
   def render_thumbnail_tag document, image_options = {}, url_options = {}
-    index_presenter(document).thumbnail.thumbnail_tag(image_options, url_options)
+    document_presenter(document).thumbnail.thumbnail_tag(image_options, url_options)
   end
   deprecation_deprecate render_thumbnail_tag: "Use IndexPresenter#thumbnail.thumbnail_tag"
 
   ##
   # Get the URL to a document's thumbnail image
   #
+  # @deprecated
   # @param [SolrDocument] document
   # @return [String]
   def thumbnail_url document
@@ -247,6 +262,7 @@ module Blacklight::CatalogHelperBehavior
   ##
   # Get the default view type classes for a view in the results view picker
   #
+  # @deprecated
   # @param [String] view
   # @return [String]
   def default_view_type_group_icon_classes view
@@ -254,6 +270,10 @@ module Blacklight::CatalogHelperBehavior
     "glyphicon-#{view.to_s.parameterize} view-icon-#{view.to_s.parameterize}"
   end
 
+  ##
+  # return the Bookmarks on a set of documents
+  # @param [Enumerable<Blacklight::Document>] documents_or_response
+  # @return [Enumerable<Bookmark>]
   def current_bookmarks documents_or_response = nil
     documents = if documents_or_response.respond_to? :documents
                   Deprecation.warn(Blacklight::CatalogHelperBehavior, "Passing a response to #current_bookmarks is deprecated; pass response.documents instead")
@@ -270,10 +290,18 @@ module Blacklight::CatalogHelperBehavior
 
   ##
   # Check if the document is in the user's bookmarks
+  # @param [Blacklight::Document] document
+  # @return [Boolean]
   def bookmarked? document
     current_bookmarks.any? { |x| x.document_id == document.id && x.document_type == document.class }
   end
 
+  # Render an html <title> appropriate string for a selected facet field and values
+  #
+  # @see #render_search_to_page_title
+  # @param [Symbol] facet the facet field
+  # @param [Array<String>] values the selected facet values
+  # @return [String]
   def render_search_to_page_title_filter(facet, values)
     facet_config = facet_configuration_for_field(facet)
     filter_label = facet_field_label(facet_config.key)
@@ -285,11 +313,14 @@ module Blacklight::CatalogHelperBehavior
     t('blacklight.search.page_title.constraint', label: filter_label, value: filter_value)
   end
 
+  # Render an html <title> appropriate string for a set of search parameters
+  # @param [ActionController::Parameters] params2
+  # @return [String]
   def render_search_to_page_title(params)
     constraints = []
 
     if params['q'].present?
-      q_label = label_for_search_field(params[:search_field]) unless default_search_field && params[:search_field] == default_search_field[:key]
+      q_label = label_for_search_field(params[:search_field]) unless default_search_field?(params[:search_field])
 
       constraints += if q_label.present?
                        [t('blacklight.search.page_title.constraint', label: q_label, value: params['q'])]