Merge pull request #751 from projectblacklight/helpers-cleanup

Helpers cleanup

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 @@ def page_entries_info(collection, options = {})
     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 @@ def render_thumbnail_tag document, image_options = {}, url_options = {}
     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

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