blacklight_browse_nearby 0.0.1

data/LICENSE

@@ -0,0 +1,14 @@
+#############################################################################################################
+# Copyright (c) 2012 by The Board of Trustees of the Leland Stanford Junior University.  All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

data/README.rdoc

@@ -0,0 +1,118 @@
+= 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.
+
+  <searchComponent name="termsComp" class="solr.TermsComponent"/>
+
+Then a request handler needs to be setup using that search component.  This request handler matches what is in the default configuration.
+
+  <requestHandler name="/alphaTerms" class="solr.SearchHandler">
+    <lst name="defaults">
+      <str name="echoParams">explicit</str>
+      <bool name="terms">true</bool>
+      <bool name="terms.lower.incl">false</bool>
+      <str name="terms.sort">index</str>
+    </lst>
+    <arr name="components">
+      <str>termsComp</str>
+    </arr>
+  </requestHandler>

data/Rakefile

@@ -0,0 +1,23 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'BlacklightBrowseNearby'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks

data/SOLR_README.rdoc

@@ -0,0 +1,144 @@
+= Solr for Browse Nearby
+
+=== Assumptions
+* The Solr documents have a sensible linear sort, and the sort values will be stored in a Solr field.
+* A single Solr document may have more than one sort value. 
+  * examples
+    * Solr document is from a Marc record for multiple items with different call numbers
+    * Solr document has an English title and a title in original script
+    * Solr document has multiple dates
+* Documents without values in the sort field will not appear in browse nearby.
+* A single sort value may pertain to more than one Solr document.  (e.g.  there are multiple books with the same title)
+* We have a starting value.
+* We need to look backwards as well as forwards.
+* Sort values may be sparsely distributed
+* Sort values may be clumpy
+* We will know how many documents we want ahead or behind of our starting point, but we won't know the *values* for the sort keys. 
+  * range queries for large numbers of documents under these circumstances have terrible performance.
+
+
+=== Objectives: 
+* Given a starting sort value, we want to get some number of documents ahead and behind the starting value.
+* We want fast Solr response times.
+
+
+== Sort key
+
+For each Solr document, you need an INDEXED Solr field (can be multivalued) for which each value is a SINGLE TOKEN with the NORMALIZED value.  
+
+Generally, values need to be normalized so they will sort correctly:
+
+dates:
+
+ March 3, 2012 --> 20120303
+ 3/4/2012      --> 20120304
+ 03/05/2012    --> 20120305
+ 13/5/2011     --> 20110513
+ 5/14/2011     --> 20110514
+ 2010/08/22    --> 20100822
+
+titles:
+
+ Rose      --> rose
+ The Rose  --> rose, the
+ A rose    --> rose, a
+
+Call numbers:
+
+ HC337 .F5 .F512                 --> lc+hc++0337.000000+f0.500000+f0.512000
+ TR692 .P37                      --> lc+tr++0692.000000+p0.370000+
+ M5 .L3 .V2 OP.7:NO.6 1880       --> (I don't want to think about it)
+ M5 .L3 K2 .Q2 MD:CRAP0*DMA 1981 --> (I don't want to think about it)
+
+Call number parsing can get really nasty.  Call number sorting is often no picnic either.
+
+There is java code in the SolrMarc project to normalize LC and Dewey call numbers for this purpose:
+
+See getLCShelfkey(), getDeweyShelfkey() methods in:
+
+https://github.com/solrmarc/stanford-solr-marc/blob/master/core/src/org/solrmarc/tools/CallNumUtils.java or http://code.google.com/p/solrmarc/source/browse/trunk/lib/solrmarc/src/org/solrmarc/tools/CallNumUtils.java
+
+Other references:
+* http://code4lib.org/conference/2010/dushay_keck2
+* http://archive.org/details/HowToImplementAVirtualBookshelfWithSolr-NaomiDushayAndJessieKeck
+ 
+
+Note that the user facing value for the sort key is generally NOT normalized.
+
+== Reverse sort key
+
+Solr provides the solr.TermsComponent (http://wiki.apache.org/solr/TermsComponent) which allows us to see the ordered values for a Solr indexed field.  However, this only words in the *forward* direction.
+
+In order to get the documents before a given sort value, we need a way to use the TermsComponent for values in the reverse order.  We can accomplish this by having a field that Solr will sort in the reverse order of the sort key:  we call this the reverse sort key.
+
+An easy algorithm to get from a sort key to a reverse sort key for alphanum characters:
+
+ 1. create a map where
+  '0' --> 'Z'
+  ...
+  '9' --> 'Q'
+  'A' --> 'P'
+  ...
+  'P' --> 'A'
+  'Q' --> '9'
+  ...
+  'Z' --> '0'
+
+ 2.  create a default reverse sort key of some max length where each character is '~'
+ 3.  for each alphanum character in your sort key, replace the corresponding character in the reverse sort key with the mapped character.
+
+There is java code in the SolrMarc project to produce reversed value strings:
+
+See getReverseShelfkey() methods in: 
+
+https://github.com/solrmarc/stanford-solr-marc/blob/master/core/src/org/solrmarc/tools/CallNumUtils.java or http://code.google.com/p/solrmarc/source/browse/trunk/lib/solrmarc/src/org/solrmarc/tools/CallNumUtils.java
+
+Other references:
+* http://code4lib.org/conference/2010/dushay_keck2
+* http://archive.org/details/HowToImplementAVirtualBookshelfWithSolr-NaomiDushayAndJessieKeck
+
+
+== Term lookups for sort keys
+
+* Your solrconfig must have the solr.TermsComponent (http://wiki.apache.org/solr/TermsComponent) as a searchComponent
+* Your solrconfig must have a requestHandler that uses that searchComponent
+
+ <searchComponent name="termsComp" class="solr.TermsComponent"/>
+ 
+ <!-- used to get consecutive terms for browsing -->
+ <requestHandler name="/alphaTerms" class="solr.SearchHandler">
+   <lst name="defaults">
+     <str name="echoParams">explicit</str>
+     <bool name="terms">true</bool>
+     <bool name="terms.lower.incl">true</bool>
+   </lst>
+   <arr name="components">
+     <str>termsComp</str>
+   </arr>
+ </requestHandler>
+
+This will be used to get the next VALUES for the sort key field and the next VALUES for the reverse sort key field.
+
+See http://www.stanford.edu/people/~ndushay/code4lib2010/stanford_virtual_shelf.pdf starting on page 21 for more details.
+
+Note that the blacklight_browse_nearby Gem will make the Solr requests -- you just need to have the requestHandler in your Solr config, and configure the gem properly.
+ 
+
+== Document lookups given sort_key or reverse_sort_key
+
+Now that we have the VALUES for our sort keys (and reverse sort keys), we need to get the Solr DOCUMENTS that correspond to these values, as it is the Documents we want to show in our application's UI.  This is easily accomplished with a fielded query for the sort key values in the sort key field, and a fielded query for the reverse sort key values in the reverse sort key field.
+
+
+== Getting a Start Value
+
+=== from a given Solr document with a single sort key value
+
+If you are looking at a single Solr document with a single value for the sort key, this is easy -- use the sort key value!   
+
+=== from a given Solr document with multiple sort key values
+
+If there are multiple values in that Solr document for the sort key, you will need to choose one.  If you want your users to decide, you will need to be sure you can get the sort key that corresponds to the value displayed to the user.  For example, we do not display our shelf keys, but instead our call numbers -- so our Solr documents have a repeatable field containing a call number and its corresponding shelfkey.
+
+=== from a user entered string
+
+You will need to normalize the string in the same way you normalized the sort key values before you can use it for term lookups.

data/app/assets/javascripts/blacklight_browse_nearby/blacklight_browse_nearby.js

@@ -0,0 +1,12 @@
+$(document).ready(function(){
+	$("#blacklight_nearby_items_controls .navigation").live("click",function(){
+		$.ajax({url: $(this).attr("href") + "&format=js"});
+		return false;
+	});
+	$("#browse_value_select button").toggle();
+	$("#browse_value_select select").live("change", function(){
+	  $.ajax({url: $("#browse_value_select").attr("action") + "&format=js&preferred_value=" + $(this).val()}).done(function(){
+		  $("#blacklight_nearby_items_controls .ful_browse").attr("href", $("#blacklight_nearby_items_controls .ful_browse").attr("href") + "&preferred_value=" + $(this).val())
+		});
+	});
+});

data/app/assets/stylesheets/blacklight_browse_nearby/blacklight_browse_nearby.css.scss

@@ -0,0 +1,11 @@
+#blacklight_nearby_items_container {
+	margin-bottom: 10px;
+  #blacklight_nearby_items_controls {
+		text-align: center;
+	}
+	#blacklight_nearby_items .item {
+		padding:2px;
+		margin: 2px 0;
+		border:1px solid #CCCCCC;
+	}
+}

data/app/controllers/blacklight_browse_nearby_controller.rb

@@ -0,0 +1,25 @@
+class BlacklightBrowseNearbyController < ApplicationController
+  include Blacklight::Catalog
+  
+  before_filter :append_blacklight_catalog_view_context
+  
+  def index
+    options = {}
+    options[:page] = params[:page] if params[:page]
+    options[:number] = params[:per_page] if params[:per_page]
+    options[:preferred_value] = params[:preferred_value] if params[:preferred_value]
+    @nearby = BlacklightBrowseNearby.new(params[:start], options)
+    @document_list = @nearby.documents
+    respond_to do |format|
+      format.html{ save_current_search_params }
+      format.js
+    end
+
+  end
+  
+  protected
+  
+  def append_blacklight_catalog_view_context
+    self.view_context.lookup_context.prefixes << "catalog"
+  end
+end

data/app/helpers/blacklight_browse_nearby_helper.rb

@@ -0,0 +1,7 @@
+module BlacklightBrowseNearbyHelper
+  
+  def render_nearby_items
+    render "blacklight_browse_nearby/nearby_items"
+  end
+  
+end

data/app/views/blacklight_browse_nearby/_browse_view_pagination.html.erb

@@ -0,0 +1,6 @@
+<div class="pagination">
+  <ul>
+    <li><%= link_to(t('blacklight_browse_nearby.full_view.previous'), nearby_index_path(params.merge(:page => params[:page].to_i-1)))  %></li>
+    <li><%= link_to(t('blacklight_browse_nearby.full_view.next'), nearby_index_path(params.merge(:page => params[:page].to_i+1)))  %></li>
+  </ul>
+</div>

data/app/views/blacklight_browse_nearby/_nearby_controls.html.erb

@@ -0,0 +1,11 @@
+<div id="blacklight_nearby_items_controls" class="row">
+  <div class="span1">
+    <%= link_to(t('blacklight_browse_nearby.short_view.previous'), nearby_index_path(params.merge(:id=>nil, :action=> nil, :controller=>nil, :format => nil, :start=>(params[:id] || params[:start]), :page=>params[:page].to_i-1)), :class=>"navigation") %>
+  </div>
+  <div class="span1">
+    <%= link_to(t('blacklight_browse_nearby.short_view.full_view'), nearby_index_path(:preferred_value=> @nearby.current_value , :start=>(params[:id] || params[:start]), :per_page=>BlacklightBrowseNearby::Engine.config.full_view_default_hits)) %>
+  </div>
+  <div class="span1">
+    <%= link_to(t('blacklight_browse_nearby.short_view.next'), nearby_index_path(params.merge(:id=>nil, :action=> nil, :controller=>nil, :format => nil, :start=>(params[:id] || params[:start]), :page=>params[:page].to_i+1)), :class=>"navigation") %>
+  </div>
+</div>

data/app/views/blacklight_browse_nearby/_nearby_item.html.erb

@@ -0,0 +1,8 @@
+<div class="item">
+  <%= link_to(document[BlacklightBrowseNearby::Engine.config.link_field] ,polymorphic_path(document)) %><br/>
+  <%- BlacklightBrowseNearby::Engine.config.nearby_fields.each do |field| -%>
+    <%- unless document[field].blank? -%>
+      <%= document[field].is_a?(Array) ? document[field].join(", ") : document[field] %><br/>
+    <%- end -%>
+  <%- end -%>
+</div>

data/app/views/blacklight_browse_nearby/_nearby_items.html.erb

@@ -0,0 +1,22 @@
+<%- blacklight_browse_nearby_items ||= @blacklight_browse_nearby_items -%>
+<%- unless blacklight_browse_nearby_items.blank? -%>
+  <div id="blacklight_nearby_items_container">
+    <%= t('blacklight_browse_nearby.short_view.browse_text') %>
+    <%- if @nearby.potential_values.length > 1 -%>
+      <%= form_tag(nearby_index_path(:start=>(params[:id] || params[:start])), :method=>"GET", :id=>"browse_value_select") do %>
+        <%= hidden_field_tag :start, (params[:id] || params[:start]) %>
+        <%= hidden_field_tag :per_page, BlacklightBrowseNearby::Engine.config.full_view_default_hits %>
+        <%= select_tag :preferred_value, options_for_select(@nearby.potential_values, @nearby.current_value), :class=>"span3" %>
+        <%= button_tag :submit %>
+      <%- end -%>
+    <%- else -%>
+      <%= @nearby.current_value %>
+    <%- end -%>
+    <div id="blacklight_nearby_items">
+      <%- blacklight_browse_nearby_items.each do |document| -%>
+        <%= render :partial => "blacklight_browse_nearby/nearby_item", :locals => {:document=>document} %>
+      <%- end -%>
+    </div>
+    <%= render "blacklight_browse_nearby/nearby_controls" %>
+  </div>
+<%- end -%>

data/app/views/blacklight_browse_nearby/index.html.erb

@@ -0,0 +1,3 @@
+<%= render "blacklight_browse_nearby/browse_view_pagination" %>
+<%= render @document_list %>
+<%= render "blacklight_browse_nearby/browse_view_pagination" %>

data/app/views/blacklight_browse_nearby/index.js.erb

@@ -0,0 +1,2 @@
+$("#blacklight_nearby_items_container").replaceWith("<%= escape_javascript(render(:partial => 'blacklight_browse_nearby/nearby_items', :locals=>{:blacklight_browse_nearby_items => @document_list})) %>");
+$("#browse_value_select button").toggle();

data/app/views/catalog/_document_header.html.erb

@@ -0,0 +1,15 @@
+<% # header bar for doc items in index view -%>
+<div class="documentHeader">
+  
+  <% # bookmark/folder functions for items/docs -%>
+  <%= render_index_doc_actions document %>
+  
+  <% # main title container for doc partial view -%>
+  <div class="yui-u">
+    <%- if params[:controller] == "blacklight_browse_nearby" -%>
+      <h3 class="index_title"><%= link_to_document document, :label=>document_show_link_field %></h3>
+    <%- else -%>
+      <h3 class="index_title"><%= t('blacklight.search.documents.counter', :counter => (document_counter + 1 + @response.params[:start].to_i)) %><%= link_to_document document, :label=>document_show_link_field, :counter => (document_counter + 1 + @response.params[:start].to_i) %></h3>
+    <%- end -%>
+  </div>
+</div>

data/config/locales/blacklight_browse_nearby.en.yml

@@ -0,0 +1,11 @@
+en:
+  blacklight_browse_nearby:
+    full_view:
+      previous: '« Previous'
+      next: 'Next »'
+    short_view:
+      browse_text: 'Browsing from:'
+      previous: '« Prev'
+      next: 'Next »'
+      full_view: 'Full View'
+