blacklight_range_limit 1.0.0pre1

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 [name of plugin creator]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,141 @@
+BlacklightRangeLimit:  integer range limiting and profiling for Blacklight applications
+
+= Description
+
+The BlacklightRangeLimit plugin provides a 'facet' or limit for integer fields, that lets the user enter range limits with a text box or a slider, and also provides area charts giving a sense of the distribution of values (with drill down). 
+
+The primary use case of this plugin is for 'year' data, but it should work for any integer field. It may not work right for negative numbers, however. 
+
+Decimal numbers and Dates are NOT supported; they theoretically could be in the future, although it gets tricky. 
+
+
+= Requirements
+
+A Rails app using the Blacklight plugin (post version 2.5. Either git checkout from master, or wait until whatever version comes after 2.5). If you've modified and over-ridden Blacklight a lot, things might get tricky. 
+
+A Solr integer field. Depending on your data, it may or may not be advantageous to use a tint (trie with non-zero precision) type field. 
+
+==Note on solr field types== 
+
+If all your integers are the same number of digits, you can use just about any solr type, including string/type, and all will be well. But if your integers vary in digits, strings won't sort correctly, making your numbers behave oddly in partitions and limits. This is also true if you use a pre-1.4 "integer"/pint/solr.IntField  field -- these are not "sortable". 
+
+You need to use a "sortable" numeric-type field. In Solr 1.4, the standard "int"/solr.TrieIntField should work fine and is probably prefered. For some distributions of data, it may be more efficient to use "tint" (solr.TrieIntField with non-zero precision). 
+
+The pre Solr 1.4 now deprecated sint or slong types should work fine too. 
+
+= Installation
+
+This is a plugin, not a gem. Sadly, I was not able to make this a gem, Rails2 engines plugins don't work as gems, particularly the assets. A couple different ways to get the source into your vendor/plugins directory. 
+
+Go into your application directory, and run: 
+
+./script/plugin install git://github.com/projectblacklight/blacklight_range_limit.git
+
+Later you can run ./script/plugin update blacklight_range_limit if you like. 
+
+Requires git installed on your system. There are other ways to get the plugin in there too.
+
+OR
+cd $your_app/vendor/plugins
+git clone git://github.com/projectblacklight/blacklight_range_limit.git
+
+= Configuration
+
+You have at least one solr field you want to display as a range limit, that's why you've installed this plugin. In your config/initializers/blacklight_config.rb, that field needs to be listed in config[:facet][:field_names], and you also need to create a config[:facet][:range]["your_field] => true key. 
+
+  config[:facet][:field_names] << "my_field"
+  config[:facet][:range]["my_field"] = true. 
+  
+You should now get range limit display. More complicated configuration is available if desired, see Range Facet Configuration below. 
+
+Note that the plugin will be default inject links to the Flot JQuery plugin, and a couple dependencies. The weird way it has to do this may fail in weird configurations.  You can turn this off and instead include Flot and its dependencies manually in your application, see Injection below. 
+
+You can also configure the look and feel of the Flot chart using the jQuery .data() method. On the `.facet_limit` container you want to configure, add a Flot options associative array (documented at http://people.iola.dk/olau/flot/API.txt) as the `plot-config` key. The `plot-config` key to set the `plot-config` key on the appropriate `.facet_limit` container. In order to customize the plot colors, for example, you could use this code:
+
+  $('.blacklight-year_i').data('plot-config', { 
+    selection: { color: '#C0FF83' }, 
+    colors: ['#ffffff'], 
+    series: { lines: { fillColor: 'rgba(255,255,255, 0.5)' }}, 
+    grid: { color: '#aaaaaa', tickColor: '#aaaaaa', borderWidth: 0 }  
+  });
+
+You can add this configuration in public/javascripts/application.js, or anywhere else loaded before the blacklight range limit javascript.
+
+== A note on AJAX use
+
+In order to calculate distribution segment ranges, we need to first know the min and max boundaries. But we don't really know that until we've fetched the result set (we use the Solr Stats component to get min and max with a result set). 
+
+So, ordinarily, after we've gotten the result set, only then can we calculate the segment ranges, and then we need to do another Solr request to actually fetch the segment range counts. 
+
+The plugin uses an AJAX request on the result page to do this. This means that for every application results display that includes any values at all in your range field, your application will get a second AJAX http request, and make a second solr request. 
+
+If you'd like to avoid this, you can turn off segment display altogether with the :segment option below; or you can set :assumed_boundaries below to use fixed boundaries for not-yet-limited segments instead of taking boundaries from the result set. 
+
+Note that a drill-down will never require the second request, because boundaries on a drill-down are always taken from the specified limits.
+
+ 
+== Range Facet Configuration
+
+Instead of simply passing "true", you can pass a hash with additional configuration. Here's an example with all the available keys, you don't need to use them all, just the ones you want to set to non-default values. 
+
+  config[:facet][:range]["my_field"] = { 
+    :num_segments => 6,
+    :assumed_boundaries => [1100, Time.now.year + 2],
+    :slider_js => false,
+    :chart_js => false,
+    :segments => false    
+  }
+  
+[num_segments]
+   Default 10. Approximately how many segments to divide the range into for segment facets, which become segments on the chart. Actual segments are calculated to be 'nice' values, so may not exactly match your setting.  
+[assumed_boundaries]
+   Default null. For a result set that has not yet been limited, instead of taking boundaries from results and making a second AJAX request to fetch segments, just assume these given boundaries. If you'd like to avoid this second AJAX Solr call, you can set :assumed_boundaries to a two-element array of integers instead, and the assumed boundaries will always be used. Note this is live ruby code, you can put calculations in there like Time.now.year + 2. 
+[:slider_js]
+   Default true. If set to false, then the slider javascript behavior will not be loaded.  Without this behavior, you will see a div with textual min and max values. You can hide that with CSS if you like. 
+[:chart_js]
+   Default true. If set to false, then the Flot area-chart is not loaded. You will instead get textual facet values for each of the segment ranges. Note that this still often will result in a second AJAX request to fetch ranges, you haven't disabled AJAX by setting :chart_js=>true.  If you'd like to turn off segment ranges altogether, see :segments.  If you'd like to prevent the ajax but keep segments, see :assumed_boundaries. 
+[:segments]
+   Default true. If set to false, then distribution segment facets will not be loaded at all.  
+
+== Injection
+
+The plugin assumes it is in a Blacklight Rails app, and uses Blacklight methods, Rails methods, and standard ruby module includes to inject it's behaviors into the app.  
+
+You can turn off this injection if you like, although it will make the plugin less (or non-) functional unless you manually do similar injection. See lib/blacklight_range_limit.rb#inject! to see exactly what's going on. 
+
+In any initializer, you can set:
+
+  BlacklightRangeLimit.omit_inject = true
+  
+to turn off all injection. The plugin will be completely non-functional if you do this, of course. But perhaps you could try to re-use some of it's classes in a non-Blacklight, highly hacked Blacklight, or even non-Rails application this way. 
+
+You can also turn off injection of individual components, which could be more useful:
+   
+  BlacklightRangeLimit.omit_inject = {
+    :css => false,
+    :js => false,
+    :flot => false,
+    :view_helpers => false,
+    :controller_mixin => false
+  }
+
+[:css]
+  set to false and the plugin will not insert it's own CSS. 
+[:js]
+  set to false and the plugin will not insert it's own JS, which means none of your range limits will get sliders or charts. Perhaps you don't like JS, or don't like ours. 
+[:flot]
+  Normally the plugin will insert <script> links to the Flot plugin, the Flot Selection plugin, and the IE canvas emulator Flot needs on IE.  Perhaps you are already including these files, or would like to include them yourself. Set to false. 
+[:view_helpers]
+  Set to false and the plugin will not insert it's own rails view helpers into the app. It will raise lots of errors if you do this, you probably don't want to. 
+[:controller_mixin]
+  The plugin mixes some methods into CatalogController, both over-riding Blacklight methods, and providing a new action of it's own. Set to false, and the plugin won't. You've basically disabled the plugin if you do this. 
+  
+= Tests
+
+There are none. This is bad I know, sorry. 
+
+= Possible future To Do
+* StatsComponent replacement. We use StatsComponent to get min/max of result set, as well as missing count. StatsComponent is included on every non-drilldown request, so ranges and slider can be displayed. However, StatsComponent really can slow down the solr response with a large result set. So replace StatsComponent with other strategies. No ideal ones, we can use facet.missing to get missing count instead, but RSolr makes it harder than it should be to grab this info. We can use seperate solr queries to get min/max (sort on our field, asc and desc), but this is more complicated, more solr queries, and possibly requires redesign of AJAXy stuff, so even a lone slider can have min/max. 
+* tests
+* In cases where an AJAX request is needed to fetch more results, don't trigger the AJAX until the range facet has actually been opened/shown. Currently it's done on page load. 
+* If :assumed_boundaries ends up popular, we could provide a method to fetch min and max values from entire corpus on app startup or in a rake task, and automatically use these as :assumed_boundaries. 

data/Rakefile

@@ -0,0 +1,5 @@
+require 'rake'
+
+
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/VERSION

@@ -0,0 +1 @@
+1.0.0pre1

data/app/helpers/range_limit_helper.rb

@@ -0,0 +1,89 @@
+# Additional helper methods used by view templates inside this plugin. 
+module RangeLimitHelper
+
+  # type is 'begin' or 'end'
+  def render_range_input(solr_field, type)
+    type = type.to_s
+    
+    default = params["range"][solr_field][type] if params["range"] && params["range"][solr_field] && params["range"][solr_field][type]
+    
+    text_field_tag("range[#{solr_field}][#{type}]", default, :maxlength=>4, :class => "range_#{type}")
+  end
+
+  # type is 'min' or 'max'
+  # Returns smallest and largest value in current result set, if available
+  # from stats component response. 
+  def range_results_endpoint(solr_field, type)
+    stats = stats_for_field(solr_field)
+        
+    return nil unless stats
+    # StatsComponent returns weird min/max when there are in
+    # fact no values
+    return nil if @response.total == stats["missing"]
+
+    return stats[type].to_s.gsub(/\.0+/, '')
+  end
+
+  def range_display(solr_field, my_params = params)
+    return "" unless my_params[:range] && my_params[:range][solr_field]
+
+    hash = my_params[:range][solr_field]
+    
+    if hash["missing"]
+      return BlacklightRangeLimit.labels[:missing]
+    elsif hash["begin"] || hash["end"]
+      if hash["begin"] == hash["end"]
+        return "<span class='single'>#{h(hash["begin"])}</span>".html_safe
+      else
+        return "<span class='from'>#{h(hash['begin'])}</span> to <span class='to'>#{h(hash['end'])}</span>".html_safe
+      end
+    end
+
+    return ""
+  end
+
+  # Show the limit area if:
+  # 1) we have a limit already set
+  # OR
+  # 2) stats show max > min, OR
+  # 3) count > 0 if no stats available. 
+  def should_show_limit(solr_field)
+    stats = stats_for_field(solr_field)
+    
+    (params["range"] && params["range"][solr_field]) ||
+    (  stats &&
+      stats["max"] > stats["min"]) ||
+    ( !stats  && @response.total > 0 )
+  end
+
+  def stats_for_field(solr_field)
+    @response["stats"]["stats_fields"][solr_field] if @response["stats"] && @response["stats"]["stats_fields"]
+  end
+
+  def add_range_missing(solr_field, my_params = params)
+    my_params = my_params.dup
+    my_params["range"] ||= {}
+    my_params["range"][solr_field] ||= {}
+    my_params["range"][solr_field]["missing"] = "true"
+
+    # Need to ensure there's a search_field to trick Blacklight
+    # into displaying results, not placeholder page. Kind of hacky,
+    # but works for now.
+    my_params["search_field"] ||= "dummy_range"
+
+    my_params
+  end
+
+  def add_range(solr_field, from, to, my_params = params)
+    my_params = my_params.dup
+    my_params["range"] ||= {}
+    my_params["range"][solr_field] ||= {}
+
+    my_params["range"][solr_field]["begin"] = from
+    my_params["range"][solr_field]["end"] = to
+    my_params["range"][solr_field].delete("missing")
+    
+    return my_params
+  end
+  
+end

data/app/views/blacklight_range_limit/_range_limit_panel.html.erb

@@ -0,0 +1,74 @@
+<%- # requires solr_config local passed in
+
+  field_config = range_config(solr_field)
+-%>
+
+<h3><%= facet_field_labels[solr_field] -%></h3>
+<div class="limit_content range_limit">  
+  <% if  params["range"] &&
+         params["range"][solr_field] &&
+       ( params["range"][solr_field]["begin"] ||
+         params["range"][solr_field]["end"] ||
+         params["range"][solr_field]["missing"]) %>
+    <div class="current">
+      <span class="selected"><%= range_display(solr_field) %></span> <span class="count">(<%= format_num(@response.total) %>)</span> <%= link_to "[remove]", remove_range_param(solr_field), :class=>"remove" %>
+    </div>
+         
+  <% end %>
+
+  <% unless params["range"] && params["range"][solr_field] && params["range"][solr_field]["missing"] %>  
+    <% form_tag catalog_index_path, :method => :get, :class=>"range_limit subsection range_#{solr_field}" do %>
+      <%= search_as_hidden_fields %>
+      
+      <!-- we need to include a dummy search_field parameter if none exists,
+           to trick blacklight into displaying actual search results instead
+           of home page. Not a great solution, but easiest for now. -->
+      <% unless params.has_key?(:search_field) %>
+        <%= hidden_field_tag("search_field", "dummy_range") %>
+      <% end %>
+      
+      <%= render_range_input(solr_field, :begin) %> - <%= render_range_input(solr_field, :end) %>
+      <%= submit_tag 'Limit', :class=>'submit ui-state-default ui-corner-all' %>
+    
+    <% end %>
+  <% end %>
+    
+  <!-- no results profile if missing is selected -->
+  <% unless params["range"] && params["range"][solr_field] && params["range"][solr_field]["missing"] %>
+    <!-- you can hide this if you want, but it has to be on page if you want
+         JS slider and calculated facets to show up, JS sniffs it. -->
+    <div class="profile">
+    
+        <% if (min = range_results_endpoint(solr_field, :min)) &&
+              (max = range_results_endpoint(solr_field, :max)) %>
+          <div class="range subsection <%= "slider_js" unless field_config[:slider_js] == false  %>">
+            Current results range from <span class="min"><%= range_results_endpoint(solr_field, :min) %></span> to <span class="max"><%= range_results_endpoint(solr_field, :max) %></span>
+          </div>
+          
+          <% if field_config[:segments] != false %>
+            <div class="distribution subsection <%= 'chart_js' unless field_config[:chart_js] == false %>">
+              <!-- if  we already fetched segments from solr, display them
+                   here. Otherwise, display a link to fetch them, which JS
+                   will AJAX fetch.  -->
+              <% if solr_range_queries_to_a(solr_field).length > 0 %>
+                    
+                 <%= render(:partial => "blacklight_range_limit/range_segments", :locals => {:solr_field => solr_field}) %>
+                 
+              <% else %> 
+                <%= link_to('View distribution', params.merge(:action => 'range_limit', :range_field => solr_field, :range_start => min, :range_end => max), :class => "load_distribution") %>
+              <% end %>
+            </div>
+          <% end %>  
+        <% end %>
+        
+        
+        
+        <% if (stats = stats_for_field(solr_field)) && stats["missing"] > 0 %>
+          <div class="missing subsection">
+            <%= link_to BlacklightRangeLimit.labels[:missing], add_range_missing(solr_field) %> <%= render_facet_count(stats["missing"]) %>
+          </div>
+        <% end %>
+    </div>
+  <% end %>
+</div>
+ 

data/app/views/blacklight_range_limit/_range_segments.html.erb

@@ -0,0 +1,14 @@
+<% # must pass in local variable :solr_field
+%>
+
+<ul>
+  <% solr_range_queries_to_a(solr_field).each do |hash| %>
+    <li><%= link_to(
+      content_tag("span", hash[:from], :class => "from") + 
+        " to " + 
+        content_tag("span", hash[:to], :class => "to"), 
+        add_range(solr_field, hash[:from], hash[:to]).merge(:action => "index"),
+        :class => "facet_select"
+      ) %> (<%= content_tag("span", hash[:count], :class=>"count")%>)</li>
+  <% end %>
+</ul>

data/blacklight_range_limit.gemspec

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+require "lib/blacklight_range_limit/version"
+
+Gem::Specification.new do |s|
+  s.name = "blacklight_range_limit"
+  s.version = BlacklightRangeLimit::VERSION
+  s.platform = Gem::Platform::RUBY
+  s.authors = ["Jonathan Rochkind"]
+  s.email = ["blacklight-development@googlegroups.com"]
+  s.homepage    = "http://projectblacklight.org/"
+  s.summary = "Blacklight Range Limit plugin"
+
+  s.rubyforge_project = "blacklight"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+
+  s.add_dependency "rails", "~> 3.0"
+  s.add_dependency "blacklight"
+end

data/config/routes.rb

@@ -0,0 +1,6 @@
+# We want to add a new collection action to Catalog, without over-writing
+# what's already there. This SEEMS to do it. 
+Rails.application.routes.draw do 
+#  match "catalog/range_limit" => "catalog#range_limit"
+end
+

data/lib/blacklight_range_limit.rb

@@ -0,0 +1,55 @@
+# BlacklightRangeLimit
+
+module BlacklightRangeLimit
+  autoload :ControllerOverride, 'blacklight_range_limit/controller_override'
+  autoload :ViewHelperOverride, 'blacklight_range_limit/view_helper_override'
+  autoload :RouteSets, 'blacklight_range_limit/route_sets'
+
+  require 'blacklight_range_limit/version'
+  require 'blacklight_range_limit/engine'
+
+  mattr_accessor :labels
+  self.labels = {
+    :missing => "Unknown"
+  }
+
+  
+  @omit_inject = {}
+  def self.omit_inject=(value)
+    value = Hash.new(true) if value == true
+    @omit_inject = value      
+  end
+  def self.omit_inject ; @omit_inject ; end
+  
+  def self.inject!
+    unless omit_inject[:controller_mixin]
+        CatalogController.send(:include, BlacklightRangeLimit::ControllerOverride) unless Blacklight::Catalog.include?(BlacklightRangeLimit::ControllerOverride)
+      end
+
+      unless omit_inject[:view_helpers]
+        SearchHistoryController.send(:helper, 
+          BlacklightRangeLimit::ViewHelperOverride
+        ) unless
+          SearchHistoryController.helpers.is_a?( 
+            BlacklightRangeLimit::ViewHelperOverride
+          )
+         
+        SearchHistoryController.send(:helper, 
+          RangeLimitHelper
+        ) unless
+          SearchHistoryController.helpers.is_a?( 
+            RangeLimitHelper
+          )
+      end
+      
+      unless BlacklightRangeLimit.omit_inject[:routes]
+        Blacklight::Routes.send(:include, BlacklightRangeLimit::RouteSets)
+      end
+  end
+
+  # Add element to array only if it's not already there
+  def self.safe_arr_add(array, element)
+    array << element unless array.include?(element)
+  end
+  
+end