blacklight 5.0.0.pre4 → 5.0.0

data/app/helpers/blacklight/catalog_helper_behavior.rb

@@ -1,10 +1,13 @@
 # -*- encoding : utf-8 -*-
 module Blacklight::CatalogHelperBehavior
 
+  ##
   # Override the Kaminari page_entries_info helper with our own, blacklight-aware
-  # implementation
+  # implementation.
+  # Displays the "showing X through Y of N" message.
   #
-  # Pass in an RSolr::Response. Displays the "showing X through Y of N" message.
+  # @param [RSolr::Resource] (or other Kaminari-compatible objects)
+  # @return [String]
   def page_entries_info(collection, options = {})
     entry_name = if options[:entry_name]
       options[:entry_name]
@@ -40,68 +43,122 @@ module Blacklight::CatalogHelperBehavior
     end
   end
 
+  ##
+  # Get the offset counter for a document
+  #
+  # @param [Integer] document index
+  # @return [Integer]
   def document_counter_with_offset idx 
     unless render_grouped_response? 
       idx + 1 + @response.params[:start].to_i
     end
   end
 
-  # Like  #page_entries_info above, but for an individual
-  # item show page. Displays "showing X of Y items" message. Actually takes
-  # data from session though (not a great design).
-  # Code should call this method rather than interrogating session directly,
-  # because implementation of where this data is stored/retrieved may change.
+  ##
+  # Like #page_entries_info above, but for an individual
+  # item show page. Displays "showing X of Y items" message.
+  # 
+  # @see #page_entries_info
+  # @return [String]
   def item_page_entry_info
     t('blacklight.search.entry_pagination_info.other', :current => number_with_delimiter(search_session[:counter]), :total => number_with_delimiter(search_session[:total]), :count => search_session[:total].to_i).html_safe
   end
 
+  ##
   # Look up search field user-displayable label
   # based on params[:qt] and blacklight_configuration.
   def search_field_label(params)
     h( label_for_search_field(params[:search_field]) )
   end
 
+  ##
+  # Look up the current sort field, or provide the default if none is set
+  #
+  # @return [Blacklight::Configuration::SortField]
   def current_sort_field
-    blacklight_config.sort_fields[params[:sort]] || (blacklight_config.sort_fields.first ? blacklight_config.sort_fields.first.last : nil )
+    blacklight_config.sort_fields[params[:sort]] || default_sort_field
   end
 
+  ##
+  # Look up the current per page value, or the default if none if set
+  # 
+  # @return [Integer]
   def current_per_page
-    (@response.rows if @response and @response.rows > 0) || params.fetch(:per_page, (blacklight_config.per_page.first unless blacklight_config.per_page.blank?)).to_i
+    (@response.rows if @response and @response.rows > 0) || params.fetch(:per_page, default_per_page).to_i
   end
 
-  # Export to Refworks URL, called in _show_tools
+  ##
+  # Export to Refworks URL
+  # 
+  # @param [SolrDocument]
+  # @return [String]
   def refworks_export_url(document = @document)
     "http://www.refworks.com/express/expressimport.asp?vendor=#{CGI.escape(application_name)}&filter=MARC%20Format&encoding=65001&url=#{CGI.escape(polymorphic_path(document, :format => 'refworks_marc_txt', :only_path => false))}"
   end
 
+  ##
+  # Get the classes to add to a document's div
+  # 
+  # @return [String]
   def render_document_class(document = @document)
     'blacklight-' + document.get(blacklight_config.view_config(document_index_view_type_field).display_type_field).parameterize rescue nil
   end
 
+  ##
+  # Render the sidebar partial for a document
+  #
+  # @param [SolrDocument]
+  # @return [String]
   def render_document_sidebar_partial(document = @document)
     render :partial => 'show_sidebar'
   end
 
+  ##
+  # Check if any search parameters have been set
+  # @return [Boolean] 
   def has_search_parameters?
     !params[:q].blank? or !params[:f].blank? or !params[:search_field].blank?
   end
 
+  ##
+  # Should we display the sort and per page widget?
+  # 
+  # @param [Blacklight::SolrResponse]
+  # @return [Boolean]
   def show_sort_and_per_page? response = nil
     response ||= @response
     !response.empty?
   end
 
+  ##
+  # If no search parameters have been given, we should
+  # auto-focus the user's cursor into the searchbox
+  # 
+  # @return [Boolean]
   def should_autofocus_on_search_box?
     controller.is_a? Blacklight::Catalog and
       action_name == "index" and
       !has_search_parameters?
   end
 
+  ##
+  # Does the document have a thumbnail to render?
+  # 
+  # @param [SolrDocument]
+  # @return [Boolean]
   def has_thumbnail? document
     blacklight_config.view_config(document_index_view_type).thumbnail_method or
       blacklight_config.view_config(document_index_view_type).thumbnail_field && document.has?(blacklight_config.view_config(document_index_view_type).thumbnail_field)
   end
 
+  ##
+  # Render the thumbnail, if available, for a document and
+  # link it to the document record.
+  # 
+  # @param [SolrDocument]
+  # @param [Hash] 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 = {}
     value = if blacklight_config.view_config(document_index_view_type).thumbnail_method
       send(blacklight_config.view_config(document_index_view_type).thumbnail_method, document, image_options)
@@ -114,24 +171,40 @@ module Blacklight::CatalogHelperBehavior
     end
   end
 
+  ##
+  # Get the URL to a document's thumbnail image
+  # 
+  # @param [SolrDocument]
+  # @return [String]
   def thumbnail_url document
     if document.has? blacklight_config.view_config(document_index_view_type).thumbnail_field
       document.first(blacklight_config.view_config(document_index_view_type).thumbnail_field)
     end
   end
 
+  ##
+  # Get url parameters to a search within a grouped result set
+  # 
+  # @param [Blacklight::SolrResponse::Group]
+  # @return [Hash]
   def add_group_facet_params_and_redirect group
     add_facet_params_and_redirect(group.field, group.key)
   end
 
-  def has_alternative_views?
-    blacklight_config.view.keys.length > 1
-  end
-
+  ##
+  # Render the view type icon for the results view picker
+  # 
+  # @param [String]
+  # @return [String]
   def render_view_type_group_icon view
     content_tag :span, '', class: "glyphicon #{blacklight_config.view[view].icon_class || default_view_type_group_icon_classes(view) }"
   end
 
+  ##
+  # Get the default view type classes for a view in the results view picker
+  #
+  # @param [String]
+  # @return [String]
   def default_view_type_group_icon_classes view
     "glyphicon-#{view.to_s.parameterize } view-icon-#{view.to_s.parameterize}"
   end

data/app/helpers/blacklight/configuration_helper_behavior.rb

@@ -0,0 +1,61 @@
+module Blacklight::ConfigurationHelperBehavior
+
+  ##
+  # Index fields to display for a type of document
+  # 
+  # @param [SolrDocument] document
+  # @return [Array<Blacklight::Solr::Configuration::SolrField>] 
+  def index_fields document=nil
+    blacklight_config.index_fields
+  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 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
+
+  ##
+  # Get the default index view type
+  def default_document_index_view_type
+    blacklight_config.view.keys.first
+  end
+
+  ##
+  # Check if there are alternative views configuration
+  def has_alternative_views?
+    blacklight_config.view.keys.length > 1
+  end
+
+  ##
+  #  Maximum number of results for spell checking
+  def spell_check_max
+    blacklight_config.spell_max
+  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
+
+  ##
+  # Default sort field
+  def default_sort_field
+    blacklight_config.sort_fields.first.last if blacklight_config.sort_fields.first
+  end
+
+  ##
+  # The default value for search results per page
+  def default_per_page
+    blacklight_config.per_page.first unless blacklight_config.per_page.blank?
+  end
+end

data/app/helpers/blacklight/facets_helper_behavior.rb

@@ -2,11 +2,23 @@ module Blacklight::FacetsHelperBehavior
 
   include Blacklight::Facet
 
+  ##
+  # Check if any of the given fields have values
+  #
+  # @param [Array<String>]
+  # @param [Hash] options
+  # @return [Boolean]
   def has_facet_values? fields = facet_field_names, options = {}
     facets_from_request(fields).any? { |display_facet| !display_facet.items.empty? }
   end
 
-  # Render a collection of facet fields
+  ##
+  # Render a collection of facet fields.
+  # @see #render_facet_limit 
+  # 
+  # @param [Array<String>]
+  # @param [Hash] options
+  # @return String
   def render_facet_partials fields = facet_field_names, options = {}
     safe_join(facets_from_request(fields).map do |display_facet|
       render_facet_limit(display_facet, options)
@@ -14,14 +26,17 @@ module Blacklight::FacetsHelperBehavior
   end
 
 
-  # used in the catalog/_facets partial and elsewhere
+  ##
   # Renders a single section for facet limit with a specified
   # solr field used for faceting. Can be over-ridden for custom
   # display on a per-facet basis. 
   #
   # @param [Blacklight::SolrResponse::Facets::FacetField] display_facet 
   # @param [Hash] options parameters to use for rendering the facet limit partial
-  #
+  # @option options [String] :partial partial to render
+  # @option options [String] :layout partial layout to render
+  # @option options [Hash] :locals locals to pass to the partial
+  # @return [String] 
   def render_facet_limit(display_facet, options = {})
     return if not should_render_facet?(display_facet)
     options = options.dup
@@ -39,7 +54,9 @@ module Blacklight::FacetsHelperBehavior
   # Determine if Blacklight should render the display_facet or not
   #
   # By default, only render facets with items.
-  # @param [Blacklight::SolrResponse::Facets::FacetField] display_facet 
+  #
+  # @param [Blacklight::SolrResponse::Facets::FacetField] display_facet
+  # @return [Boolean] 
   def should_render_facet? display_facet
     # display when show is nil or true
     facet_config = facet_configuration_for_field(display_facet.name)
@@ -63,15 +80,21 @@ module Blacklight::FacetsHelperBehavior
   end
 
   ##
-  # if the facet is 'active', don't collapse
-  # if the facet is configured to collapse (the default), collapse
-  # if the facet is configured not to collapse, don't collapse
+  # Determine whether a facet should be rendered as collapsed or not.
+  #   - if the facet is 'active', don't collapse
+  #   - if the facet is configured to collapse (the default), collapse
+  #   - if the facet is configured not to collapse, don't collapse
+  # 
+  # @param [Blacklight::Configuration::FacetField]
+  # @return [Boolean]
   def should_collapse_facet? facet_field
     !facet_field_in_params?(facet_field.field) && facet_field.collapse
   end
 
-  # the name of the partial to use to render a facet field. Can be over-ridden for custom
-  # display on a per-facet basis. 
+  ##
+  # the name of the partial to use to render a facet field.
+  #
+  # @return [String]
   def facet_partial_name(display_facet = nil)
     config = facet_configuration_for_field(display_facet.name)
     name = config.try(:partial)
@@ -79,17 +102,17 @@ module Blacklight::FacetsHelperBehavior
     name ||= "facet_limit"
   end
  
-  #
-  # facet param helpers ->
-  #
-
+  ##
   # Standard display of a facet value in a list. Used in both _facets sidebar
   # partial and catalog/facet expanded list. Will output facet value name as
-  # a link to add that to your restrictions, with count in parens. 
-  # first arg item is a facet value item from rsolr-ext.
-  # options consist of:
-  # :suppress_link => true # do not make it a link
-  # :route_set => my_engine # call link_to on engine routes.
+  # a link to add that to your restrictions, with count in parens.
+  #
+  # @param [Blacklight::SolrResponse::Facets::FacetField]
+  # @param [String] facet item
+  # @param [Hash] options
+  # @option options [Boolean] :suppress_link display the facet, but don't link to it
+  # @option options [Rails::Engine] :route_set route set to use to render the link
+  # @return [String]
   def render_facet_value(facet_solr_field, item, options ={})    
     scope = options.delete(:route_set) || self
     path = scope.url_for(add_facet_params_and_redirect(facet_solr_field, item).merge(only_path: true))
@@ -98,8 +121,9 @@ module Blacklight::FacetsHelperBehavior
     end + render_facet_count(item.hits)
   end
 
-  # Standard display of a SELECTED facet value, no link, special span
-  # with class, and 'remove' button.
+  ##
+  # Standard display of a SELECTED facet value (e.g. without a link and with a remove button)
+  # @params (see #render_facet_value)
   def render_selected_facet_value(facet_solr_field, item)
     content_tag(:span, :class => "facet-label") do
       content_tag(:span, facet_display_value(facet_solr_field, item), :class => "selected") +
@@ -108,20 +132,35 @@ module Blacklight::FacetsHelperBehavior
     end + render_facet_count(item.hits, :classes => ["selected"])
   end
 
+  ##
   # Renders a count value for facet limits. Can be over-ridden locally
   # to change style. And can be called by plugins to get consistent display. 
   #
-  # option :class takes an array of classes to add to count span.
+  # @param [Integer] number of facet results
+  # @param [Hash] options
+  # @option options [Array<String>]  an array of classes to add to count span.
+  # @return [String]
   def render_facet_count(num, options = {})
     classes = (options[:classes] || []) << "facet-count"
     content_tag("span", t('blacklight.search.facets.count', :number => num), :class => classes)
   end
   
+  ##
+  # Are any facet restrictions for a field in the query parameters?
+  # 
+  # @param [String] facet field
+  # @return [Boolean]
   def facet_field_in_params? field
     params[:f] and params[:f][field]
   end
   
-  # true or false, depending on whether the field and value is in params[:f]
+  ##
+  # Check if the query parameters have the given facet field with the 
+  # given value.
+  # 
+  # @param [Object] facet field
+  # @param [Object] facet value
+  # @return [Boolean]
   def facet_in_params?(field, item)
     if item and item.respond_to? :field
       field = item.field
@@ -132,6 +171,12 @@ module Blacklight::FacetsHelperBehavior
     facet_field_in_params?(field) and params[:f][field].include?(value)
   end
 
+  ##
+  # Get the displayable version of a facet's value
+  # 
+  # @param [Object] field
+  # @param [String] item value
+  # @return [String] 
   def facet_display_value field, item
     facet_config = facet_configuration_for_field(field)
     

data/app/helpers/blacklight/hash_as_hidden_fields_helper_behavior.rb

@@ -11,9 +11,12 @@
 # to form fields used for sort and change per-page
 module Blacklight::HashAsHiddenFieldsHelperBehavior
 
+  ##
   # Writes out zero or more <input type="hidden"> elements, completely
   # representing a hash passed in using Rails-style request parameters
-  # for hashes nested with arrays and other hashes. 
+  # for hashes nested with arrays and other hashes.
+  # @param [Hash]
+  # @return [String] 
   def render_hash_as_hidden_fields(hash)
     
     hidden_fields = []

data/app/helpers/blacklight/render_constraints_helper_behavior.rb

@@ -7,16 +7,30 @@
 # search results page (render_constraints(_*))
 module Blacklight::RenderConstraintsHelperBehavior
 
+  ##
+  # Check if the query has any constraints defined (a query, facet, etc)
+  # 
+  # @param [Hash] query parameters
+  # @return [Boolean]
   def query_has_constraints?(localized_params = params)
     !(localized_params[:q].blank? and localized_params[:f].blank?)
   end
 
-  # Render actual constraints, not including header or footer
+  ##
+  # Render the actual constraints, not including header or footer
   # info. 
+  # 
+  # @param [Hash] query parameters
+  # @return [String]
   def render_constraints(localized_params = params)
     render_constraints_query(localized_params) + render_constraints_filters(localized_params)
   end
   
+  ##
+  # Render the query constraints
+  # 
+  # @param [Hash] query parameters
+  # @return [String]
   def render_constraints_query(localized_params = params)
     # So simple don't need a view template, we can just do it here.
     if (!localized_params[:q].blank?)
@@ -36,6 +50,11 @@ module Blacklight::RenderConstraintsHelperBehavior
     end
   end
 
+  ##
+  # Render the facet constraints
+  # 
+  # @param [Hash] query parameters
+  # @return [String]
   def render_constraints_filters(localized_params = params)
      return "".html_safe unless localized_params[:f]
      content = []
@@ -46,6 +65,13 @@ module Blacklight::RenderConstraintsHelperBehavior
      safe_join(content.flatten, "\n")    
   end
 
+  ##
+  # Render a single facet's constraint
+  # 
+  # @param [String] facet field
+  # @param [Array<String>] selected facet values
+  # @param [Hash] query parameters
+  # @return [String]
   def render_filter_element(facet, values, localized_params)
     facet_config = facet_configuration_for_field(facet)
 
@@ -66,15 +92,12 @@ module Blacklight::RenderConstraintsHelperBehavior
   #
   # Can pass in nil label if desired.
   #
-  # options:
-  # [:remove]
-  #    url to execute for a 'remove' action  
-  # [:classes] 
-  #    can be an array of classes to add to container span for constraint.
-  # [:escape_label]
-  #    default true, HTML escape.
-  # [:escape_value]
-  #    default true, HTML escape. 
+  # @param [String] label to display
+  # @param [String] value to display
+  # @param [Hash] options
+  # @option options [String] :remove url to execute for a 'remove' action
+  # @option options [Array<String>] :classes an array of classes to add to container span for constraint.
+  # @return [String]
   def render_constraint_element(label, value, options = {})
     render(:partial => "catalog/constraints_element", :locals => {:label => label, :value => value, :options => options})    
   end