= Blacklight Browse Nearby

This is a gem that will provide a small bit of HTML to provide on a record's show view as well as a larger browse view which will render the appropriate document partials as a search result.

This gem has several configuration options that will need to match your solr configuration and some very specific solr field formatting necessary to work properly. Continue reading below to get more information on how to properly configure both solr and the application and how to format these special fields.

== Installation

$ gem install blacklight_browse_nearby $ rails g blacklight_browse_nearby

In order to display the small browse nearby UI you must insert the render_nearby_items helper method into a view. This view must be under the show action of a controller that has included the BlacklightBrowseNearby::Controller (CatalogController by default).

<%= render_nearby_items %>

== Basic Usage

Simply giving an object ID will return the configured number of documents before and after (including the center document) the given ID (555).

BlacklightBrowseNearby.new("555").documents

Passing a number (without a page) will return the requested number of documents before and after (including the center document) the given ID (555).

BlacklightBrowseNearby.new("555", :number => 11).documents

Passing a page will return the configured number of documents before or after the given ID (555). Negative page numbers return documents before and positive numbers return documents after. (the number parameter will work as expected)

BlacklightBrowseNearby.new("555", :page => -3).documents # documents before BlacklightBrowseNearby.new("555", :page => 3).documents # documents after

== Configurations

The solr field name of the human readable value that we're sorting on. (default: "value_display")

BlacklightBrowseNearby::Engine.config.value_field

The solr field name of the sortable values that will be used by the solr terms component. (default: "shelfkey")

BlacklightBrowseNearby::Engine.config.sortkey_field

The solr field name of the reverse sortable values that will be used by the solr terms component. (default: "reverse_shelfkey")

BlacklightBrowseNearby::Engine.config.reverse_sortkey_field

The solr field name of the combined keys that will be used to handle switching between values in multi-valued fields. (default: "combined_shelfkey")

BlacklightBrowseNearby::Engine.config.combined_key_field

The string used to delimit values in the combined key field. (default: "-|-")

BlacklightBrowseNearby::Engine.config.key_delimiter

The pattern of combined key field. It is not recommended that you change this unless you absolutely have to. You should be able to cover most use cases by changing other configuration options.

BlacklightBrowseNearby::Engine.config.combined_key_pattern

The request handler for the for the solr terms component. (default: "/alphaTerms")

BlacklightBrowseNearby::Engine.config.request_handler

The default number of records to retrieve in the smaller nearby view. This should be an odd number because we want to get an even number before and after the center document. (default: "5")

BlacklightBrowseNearby::Engine.config.default_hits

The default number of records to retrieve in the larger browse view. This should be an odd number because we want to get an even number before and after the center document. (default: "11")

BlacklightBrowseNearby::Engine.config.full_view_default_hits

The fields that the default nearby_item partial will attempt to display. You will most likely want to override the nearby_item partial. (default: The value of BlacklightBrowseNearby::Engine.config.value_field)

BlacklightBrowseNearby::Engine.config.nearby_fields

The field that the default nearby_item partial will attempt to use as a title and link. You will most likely want to override the nearby_item partial. (default: "title_display")

BlacklightBrowseNearby::Engine.config.link_field

You can set these configuration options from somewhere in your application (e.g. an initializer)

== Necessary Fields in Solr

There are 4 configurable solr fields necessary for this gem to function properly. value_field, sortkey_field, reverse_sortkey_field, and combined_key_field. These should all be multi-valued fields.

=== Combined Key

The combined key field is necessary to handle documents with multiple values to browse from (e.g. multiple callnumbers). This key should consist of a combination of the 3 other necessary fields in solr delimited by a special configurable string.

A combined key field that matched the default configuration would look something like:

["AAAA -|- aaaa -|- zzzz", "BBBB -|- bbbb -|- yyyy"]

This gem will be able to handle the pattern change when you update the configured solr field names or delimiter. However; if you drastically change the pattern of this field you will need to update the combined_key_pattern configuration to match the new pattern.

=== More information about sort keys and solr configurations

For a more detailed explanation of the solr configurations and how we generated the sort keys for various data types see: https://github.com/projectblacklight/blacklight_browse_nearby/blob/master/SOLR_README.rdoc

== Necessary Solr Request Handler

You need to make sure there is a terms component setup.