RubyGems - blacklight - Versions diffs - 5.0.0.pre4 → 5.0.0 - Mend

blacklight 5.0.0.pre4 → 5.0.0

Files changed (22) hide show

checksums.yaml +4 -4
data/VERSION +1 -1
data/app/helpers/blacklight/blacklight_helper_behavior.rb +225 -123
data/app/helpers/blacklight/catalog_helper_behavior.rb +87 -14
data/app/helpers/blacklight/configuration_helper_behavior.rb +61 -0
data/app/helpers/blacklight/facets_helper_behavior.rb +67 -22
data/app/helpers/blacklight/hash_as_hidden_fields_helper_behavior.rb +4 -1
data/app/helpers/blacklight/render_constraints_helper_behavior.rb +33 -10
data/app/helpers/blacklight/search_history_constraints_helper_behavior.rb +8 -0
data/app/helpers/blacklight/url_helper_behavior.rb +7 -0
data/app/helpers/blacklight_configuration_helper.rb +3 -0
data/app/views/catalog/_constraints_element.html.erb +4 -6
data/lib/blacklight/solr/document.rb +1 -1
data/lib/blacklight/utils.rb +1 -1
data/lib/generators/blacklight/install_generator.rb +4 -0
data/lib/generators/blacklight/templates/blacklight.en.yml +3 -0
data/solr/sample_solr_documents.yml +2120 -70
data/spec/helpers/configuration_helper_spec.rb +61 -0
data/spec/helpers/url_helper_spec.rb +7 -0
data/spec/lib/blacklight/solr/document_spec.rb +8 -0
data/spec/views/catalog/_constraints_element.html.erb_spec.rb +1 -1
metadata +9 -4

checksums.yaml CHANGED

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bf405f02c6be2140ca50f003ba8f9b39f7a0db26
-  data.tar.gz: c8bf97338f9612b578826b97cea817a7c8e9f5ab
+  metadata.gz: 7c8f10c08ef2255599634c398a2e28201f7bbbf6
+  data.tar.gz: 1275af21c316d9b9c4f723eaecac370298e0b10a
 SHA512:
-  metadata.gz: 576d597de0b7541de63349e3f99e46a0c9a84fa9425108a0e33c91b91a7f00dac8693635430ffc11df7deb1990bc353536de33808baa9fc6cbd4d8eeeaf4dee1
-  data.tar.gz: 56a327ccf26e7d3eade183580e1d75d85e3aaf4d6840e98fa8eaa4839bd2659098ef3e04840cf6e80692bbf3cad480f2454429967f7e7e1e728883562555ae81
+  metadata.gz: 204052b9659c971b75293272467b192a7026d7284a74ee91a971f4e0147fcce6144d5d831caca2e62f61c4a3611612e24119c73b6ecb126f2e7b16950eb737b1
+  data.tar.gz: e91a0333a881eab6272d99c151d469cf9ee2c88098a83e488c58217a71e9d9ada6fab25c813926f9d3d3e0ab313d9900a5e7d07ba332ae5732237965681bae10

data/VERSION CHANGED

	@@ -1 +1 @@
1	- 5.0.0~~.pre4~~
1	+ 5.0.0

data/app/helpers/blacklight/blacklight_helper_behavior.rb CHANGED

@@ -5,25 +5,35 @@
 #
 module Blacklight::BlacklightHelperBehavior
   include BlacklightUrlHelper
+  include BlacklightConfigurationHelper
   include HashAsHiddenFieldsHelper
   include RenderConstraintsHelper
   include FacetsHelper
+  ##
+  # Get the name of this application, from either:
+  #  - the Rails configuration
+  #  - an i18n string (key: blacklight.application_name; preferred)
+  #
+  # @return [String] the application named
   def application_name
     return Rails.application.config.application_name if Rails.application.config.respond_to? :application_name
     t('blacklight.application_name')
   end
+  ##
   # Create <link rel="alternate"> links from a documents dynamically
   # provided export formats. Currently not used by standard BL layouts,
   # but available for your custom layouts to provide link rel alternates.
   #
   # Returns empty string if no links available.
   #
-  # :unique => true, will ensure only one link is output for every
-  # content type, as required eg in atom. Which one 'wins' is arbitrary.
-  # :exclude => array of format shortnames, formats to not include at all.
+  # @params [SolrDocument] document
+  # @params [Hash] options
+  # @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
   def render_link_rel_alternates(document=@document, options = {})
     options = {:unique => false, :exclude => []}.merge(options)
@@ -44,28 +54,43 @@ module Blacklight::BlacklightHelperBehavior
     return html.html_safe
   end
+  ##
+  # Render OpenSearch headers for this search
+  # @return [String]
   def render_opensearch_response_metadata
     render :partial => 'catalog/opensearch_response_metadata'
   end
+  ##
+  # Render classes for the <body> element
+  # @return [String]
   def render_body_class
     extra_body_classes.join " "
   end
-  def render_search_bar
-    render :partial=>'catalog/search_form'
-  end
+  ##
+  # List of classes to be applied to the <body> element
+  # @see render_body_class
+  # @return [Array<String>]
   def extra_body_classes
     @extra_body_classes ||= ['blacklight-' + controller.controller_name, 'blacklight-' + [controller.controller_name, controller.action_name].join('-')]
   end
-  def render_document_list_partial options={}
-    render :partial=>'catalog/document_list'
+  ##
+  # Render the search navbar
+  # @return [String]
+  def render_search_bar
+    render :partial=>'catalog/search_form'
   end
-  # Save function area for search results 'index' view, normally
-  # renders next to title.
+  ##
+  # Render "docuemnt actions" area for search results view
+  # (normally renders next to title in the list view)
+  #
+  # @param [SolrDocument] document
+  # @param [Hash] options
+  # @option options [String] :wrapping_class
+  # @return [String]
   def render_index_doc_actions(document, options={})
     wrapping_class = options.delete(:wrapping_class) || "index-document-functions"
@@ -75,12 +100,18 @@ module Blacklight::BlacklightHelperBehavior
     content_tag("div", safe_join(content, "\n"), :class=> wrapping_class)
   end
-  # Save function area for item detail 'show' view, normally
-  # renders next to title. By default includes 'Bookmarks'
+  ##
+  # Render "docuemnt actions" for the item detail 'show' view.
+  # (this normally renders next to title)
+  #
+  # By default includes 'Bookmarks'
+  #
+  # @param [SolrDocument] document
+  # @param [Hash] options
+  # @option options [String] :wrapping_class
+  # @return [String]
   def render_show_doc_actions(document=@document, options={})
-    # I'm not sure why this key is documentFunctions and #render_index_doc_actions uses wrapping_class.
-    # TODO: remove documentFunctions key in Blacklight 5.x
-    wrapping_class = options.delete(:documentFunctions) || options.delete(:wrapping_class) || "documentFunctions"
+    wrapping_class = options.delete(:wrapping_class) || "documentFunctions"
     content = []
     content << render(:partial => 'catalog/bookmark_control', :locals => {:document=> document}.merge(options)) if render_bookmarks_control?
@@ -89,17 +120,34 @@ module Blacklight::BlacklightHelperBehavior
   end
   ##
-  # Index fields to display for a type of document
-  def index_fields document=nil
-    blacklight_config.index_fields
+  # Determine whether to render a given field in the index view.
+  #
+  # @param [SolrDocument] document
+  # @param [Blacklight::Solr::Configuration::SolrField] solr_field
+  # @return [Boolean]
+  def should_render_index_field? document, solr_field
+    document.has?(solr_field.field) ||
+      (document.has_highlight_field? solr_field.field if solr_field.highlight) ||
+      solr_field.accessor
   end
-  def should_render_index_field? document, solr_field
+  ##
+  # Determine whether to render a given field in the show view
+  #
+  # @param [SolrDocument] document
+  # @param [Blacklight::Solr::Configuration::SolrField] solr_field
+  # @return [Boolean]
+  def should_render_show_field? document, solr_field
     document.has?(solr_field.field) ||
       (document.has_highlight_field? solr_field.field if solr_field.highlight) ||
       solr_field.accessor
   end
+  ##
+  # Determine whether to display spellcheck suggestions
+  #
+  # @param [Blacklight::SolrResponse] response
+  # @return [Boolean]
   def should_show_spellcheck_suggestions? response
     response.total <= spell_check_max and response.spelling.words.size > 0
   end
@@ -156,69 +204,9 @@ module Blacklight::BlacklightHelperBehavior
     field_config = index_fields(document)[field]
     value = options[:value] || get_field_values(document, field, field_config, options)
     render_field_value value, field_config
   end
-  # Used in the show view for displaying the main solr document heading
-  def document_heading document=nil
-    document ||= @document
-    render_field_value document[blacklight_config.view_config(:show).title_field] || document.id
-  end
-  # Used in the show view for setting the main html document title
-  def document_show_html_title document=nil
-    document ||= @document
-    if blacklight_config.view_config(:show).html_title_field
-      render_field_value(document[blacklight_config.view_config(:show).html_title_field])
-    else
-      document_heading document
-    end
-  end
-  ##
-  # Render the document "heading" (title) in a content tag
-  # @overload render_document_heading(tag)
-  # @overload render_document_heading(document, options)
-  #   @params [SolrDocument] document
-  #   @params [Hash] options
-  #   @options options [Symbol] :tag
-  def render_document_heading(*args)
-    options = args.extract_options!
-    if args.first.is_a? SolrDocument
-      document = args.shift
-      tag = options[:tag]
-    else
-      document = nil
-      tag = args.first || options[:tag]
-    end
-    tag ||= :h4
-    content_tag(tag, render_field_value(document_heading(document)), :itemprop => "name")
-  end
-  # Used in the document_list partial (search view) for building a select element
-  def sort_fields
-    blacklight_config.sort_fields.map { |key, x| [x.label, x.key] }
-  end
-  # Used in the document list partial (search view) for creating a link to the document show action
-  def document_show_link_field document=nil
-    blacklight_config.view_config(document_index_view_type).title_field.to_sym
-  end
-  # Used in the search form partial for building a select tag
-  def search_fields
-    search_field_options_for_select
-  end
-  # used in the catalog/_show/_default partial
-  def document_show_fields document=nil
-    blacklight_config.show_fields
-  end
   ##
   # Render the show field label for a document
   #
@@ -265,7 +253,6 @@ module Blacklight::BlacklightHelperBehavior
   #   @param [Hash] opts
   #   @options opts [String] :value
   def render_document_show_field_value *args
     options = args.extract_options!
     document = args.shift || options[:document]
@@ -276,6 +263,56 @@ module Blacklight::BlacklightHelperBehavior
     render_field_value value, field_config
   end
+  ##
+  # Get the value of the document's "title" field, or a placeholder
+  # value (if empty)
+  #
+  # @param [SolrDocument] document
+  # @return [String]
+  def document_heading document=nil
+    document ||= @document
+    render_field_value(document[blacklight_config.view_config(:show).title_field] || document.id)
+  end
+  ##
+  # Get the document's "title" to display in the <title> element.
+  # (by default, use the #document_heading)
+  #
+  # @see #document_heading
+  # @param [SolrDocument] document
+  # @return [String]
+  def document_show_html_title document=nil
+    document ||= @document
+    if blacklight_config.view_config(:show).html_title_field
+      render_field_value(document[blacklight_config.view_config(:show).html_title_field])
+    else
+      document_heading document
+    end
+  end
+  ##
+  # Render the document "heading" (title) in a content tag
+  # @overload render_document_heading(tag)
+  # @overload render_document_heading(document, options)
+  #   @params [SolrDocument] document
+  #   @params [Hash] options
+  #   @options options [Symbol] :tag
+  def render_document_heading(*args)
+    options = args.extract_options!
+    if args.first.is_a? SolrDocument
+      document = args.shift
+      tag = options[:tag]
+    else
+      document = nil
+      tag = args.first || options[:tag]
+    end
+    tag ||= :h4
+    content_tag(tag, render_field_value(document_heading(document)), :itemprop => "name")
+  end
   ##
   # Get the value for a document's field, and prepare to render it.
   # - highlight_field
@@ -287,8 +324,12 @@ module Blacklight::BlacklightHelperBehavior
   #   - link_to_search
   # TODO : maybe this should be merged with render_field_value, and the ugly signature
   # simplified by pushing some of this logic into the "model"
+  # @param [SolrDocument] document
+  # @param [String] field name
+  # @param [Blacklight::Solr::Configuration::SolrField] solr field configuration
+  # @param [Hash] options additional options to pass to the rendering helpers
   def get_field_values document, field, field_config, options = {}
-    # valuyes
+    # retrieving values
     value = case
       when (field_config and field_config.highlight)
         # retrieve the document value from the highlighting response
@@ -311,7 +352,7 @@ module Blacklight::BlacklightHelperBehavior
         document.get(field, :sep => nil) if field
     end
-    # rendering
+    # rendering values
     case
       when (field_config and field_config.helper_method)
         send(field_config.helper_method, options.merge(:document => document, :field => field, :value => value))
@@ -330,12 +371,12 @@ module Blacklight::BlacklightHelperBehavior
       end
   end
-  def should_render_show_field? document, solr_field
-    document.has?(solr_field.field) ||
-      (document.has_highlight_field? solr_field.field if solr_field.highlight) ||
-      solr_field.accessor
-  end
+  ##
+  # Render a value (or array of values) from a field
+  #
+  # @param [String] value or list of values to display
+  # @param [Blacklight::Solr::Configuration::SolrField] solr field configuration
+  # @return [String]
   def render_field_value value=nil, field_config=nil
     safe_values = Array(value).collect { |x| x.respond_to?(:force_encoding) ? x.force_encoding("UTF-8") : x }
@@ -346,10 +387,19 @@ module Blacklight::BlacklightHelperBehavior
     safe_join(safe_values, (field_config.separator if field_config) || field_value_separator)
   end
+  ##
+  # Default separator to use in #render_field_value
+  #
+  # @return [String]
   def field_value_separator
     ', '
   end
+  ##
+  # Get the current "view type" (and ensure it is a valid type)
+  #
+  # @param [Hash] the query parameters to check
+  # @return [Symbol]
   def document_index_view_type query_params=params
     if query_params[:view] and blacklight_config.view.keys.include? query_params[:view].to_sym
       query_params[:view].to_sym
@@ -358,21 +408,42 @@ module Blacklight::BlacklightHelperBehavior
     end
   end
-  def default_document_index_view_type
-    blacklight_config.view.keys.first
-  end
+  ##
+  # Render the document index view
+  #
+  # @param [Array<SolrDocument>] list of documents to render
+  # @param [Hash] locals to pass to the render call
+  # @return [String]
   def render_document_index documents = nil, locals = {}
     documents ||= @document_list
     render_document_index_with_view(document_index_view_type, documents)
   end
+  ##
+  # Render the document index for a grouped response
+  def render_grouped_document_index
+    render :partial => 'catalog/group_default'
+  end
+  ##
+  # Render the document index for the given view type with the
+  # list of documents.
+  #
+  # This method will interpolate the list of templates with
+  # the current view, and gracefully handles missing templates.
+  #
+  # @see #document_index_path_templates
+  #
+  # @param [String] view type
+  # @param [Array<SolrDocument>] list of documents to render
+  # @param [Hash] locals to pass to the render call
+  # @return [String]
   def render_document_index_with_view view, documents, locals = {}
     document_index_path_templates.each do |str|
       # XXX rather than handling this logic through exceptions, maybe there's a Rails internals method
       # for determining if a partial template exists..
       begin
-        return render(:partial => (str % { :index_view_type => view }), :locals => { :documents => documents })
+        return render(:partial => (str % { :index_view_type => view }), :locals => locals.merge(:documents => documents) )
       rescue ActionView::MissingTemplate
         nil
       end
@@ -381,7 +452,11 @@ module Blacklight::BlacklightHelperBehavior
     return ""
   end
-  # a list of document partial templates to try to render for #render_document_index
+  ##
+  # A list of document partial templates to attempt to render
+  #
+  # @see #render_document_index_with_view
+  # @return [Array<String>]
   def document_index_path_templates
     # first, the legacy template names for backwards compatbility
     # followed by the new, inheritable style
@@ -389,37 +464,53 @@ module Blacklight::BlacklightHelperBehavior
     @document_index_path_templates ||= ["document_%{index_view_type}", "catalog/document_%{index_view_type}", "catalog/document_list"]
   end
-  # Return a normalized partial name that can be used to contruct view partial path
+  ##
+  # Return a normalized partial name for rendering a single document
+  #
+  # @param [SolrDocument]
+  # @return [String]
   def document_partial_name(document)
-    # .to_s is necessary otherwise the default return value is not always a string
-    # using "_" as sep. to more closely follow the views file naming conventions
-    # parameterize uses "-" as the default sep. which throws errors
     display_type = document[blacklight_config.view_config(:show).display_type_field]
     return 'default' unless display_type
     display_type = display_type.join(" ") if display_type.respond_to?(:join)
+    # .to_s is necessary otherwise the default return value is not always a string
+    # using "_" as sep. to more closely follow the views file naming conventions
+    # parameterize uses "-" as the default sep. which throws errors
     "#{display_type.gsub("-"," ")}".parameterize("_").to_s
   end
-  def render_document_partials(doc, actions = [], locals ={})
-    safe_join(actions.map do |action_name|
+  ##
+  # Return the list of partials for a given solr document
+  # @param [SolrDocument]
+  # @return [String]
+  def render_document_partials(doc, partials = [], locals ={})
+    safe_join(partials.map do |action_name|
       render_document_partial(doc, action_name, locals)
     end, "\n")
   end
-  # given a doc and action_name, this method attempts to render a partial template
-  # based on the value of doc[:format]
-  # if this value is blank (nil/empty) the "default" is used
-  # if the partial is not found, the "default" partial is rendered instead
-  def render_document_partial(doc, action_name, locals = {})
+  ##
+  # Given a doc and a base name for a partial, this method will attempt to render
+  # an appropriate partial based on the document format and view type.
+  #
+  # If a partial that matches the document format is not found,
+  # render a default partial for the base name.
+  #
+  # @see #document_partial_path_templates
+  #
+  # @param [SolrDocument] doc
+  # @param [String] base name for the partial
+  # @param [Hash] locales to pass through to the partials
+  def render_document_partial(doc, base_name, locals = {})
     format = document_partial_name(doc)
     document_partial_path_templates.each do |str|
       # XXX rather than handling this logic through exceptions, maybe there's a Rails internals method
       # for determining if a partial template exists..
       begin
-        return render :partial => (str % { :action_name => action_name, :format => format, :index_view_type => document_index_view_type }), :locals=>locals.merge({:document=>doc})
+        return render :partial => (str % { :action_name => base_name, :format => format, :index_view_type => document_index_view_type }), :locals=>locals.merge(:document=>doc)
       rescue ActionView::MissingTemplate
         nil
       end
@@ -428,7 +519,15 @@ module Blacklight::BlacklightHelperBehavior
     return ''
   end
-  # a list of document partial templates to try to render for #render_document_partial
+  ##
+  # A list of document partial templates to try to render for a document
+  #
+  # The partial names will be interpolated with the following variables:
+  #   - action_name: (e.g. index, show)
+  #   - index_view_type: (the current view type, e.g. list, gallery)
+  #   - format: the document's format (e.g. book)
+  #
+  # @see #render_document_partial
   def document_partial_path_templates
     # first, the legacy template names for backwards compatbility
     # followed by the new, inheritable style
@@ -436,9 +535,15 @@ module Blacklight::BlacklightHelperBehavior
     @partial_path_templates ||= ["%{action_name}_%{index_view_type}_%{format}", "%{action_name}_%{index_view_type}_default", "%{action_name}_%{format}", "%{action_name}_default", "catalog/%{action_name}_%{format}", "catalog/_%{action_name}_partials/%{format}", "catalog/_%{action_name}_partials/default"]
   end
-  def render_document_index_label doc, opts
+  ##
+  # Render the document index heading
+  #
+  # @param [SolrDocument] doc
+  # @param [Hash] opts
+  # @option opts [Symbol] :label Render the given field from the document
+  # @option opts [Proc] :label Evaluate the given proc
+  # @option opts [String] :label Render the given string
+  def render_document_index_label doc, opts = {}
     label = nil
     label ||= doc.get(opts[:label], :sep => nil) if opts[:label].instance_of? Symbol
     label ||= opts[:label].call(doc, opts) if opts[:label].instance_of? Proc
@@ -447,10 +552,15 @@ module Blacklight::BlacklightHelperBehavior
     render_field_value label
   end
-  # Use case, you want to render an html partial from an XML (say, atom)
-  # template. Rails API kind of lets us down, we need to hack Rails internals
-  # a bit. code taken from:
+  ##
+  # Render a partial of an arbitrary format inside a
+  # template of a different format. (e.g. render an HTML
+  # partial from an XML template)
+  # code taken from:
   # http://stackoverflow.com/questions/339130/how-do-i-render-a-partial-of-a-different-format-in-rails (zgchurch)
+  #
+  # @param [String] format suffix
+  # @yield
   def with_format(format, &block)
     old_formats = formats
     self.formats = [format]
@@ -467,17 +577,9 @@ module Blacklight::BlacklightHelperBehavior
   end
   ##
-  # Render the grouped response
-  def render_grouped_document_index grouped_key = nil
-    render :partial => 'catalog/group_default'
-  end
+  # Determine whether to render the bookmarks control
   def render_bookmarks_control?
     has_user_authentication_provider? and current_or_guest_user.present?
   end
-  def spell_check_max
-    blacklight_config.spell_max
-  end
 end