blacklight-hierarchy 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+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.md

@@ -0,0 +1,65 @@
+# Blacklight::Hierarchy
+
+This plugin provides hierarchical facets for [Blacklight](https://github.com/projectblacklight/blacklight).
+
+## Usage
+
+Add the plugin to your Blacklight app's Gemfile
+
+    gem 'blacklight-hierarchy', :git => 'git@github.com:sul-dlss/blacklight-hierarchy.git'
+        
+Index your hierarchies in colon-separated list. For example, items in a "processing" queue with a "copy" action, might be indexed as
+
+    <doc>
+      <field name="id">foo</field>
+      <field name="queue_status_facet">processing</field>
+      <field name="queue_status_facet">processing:copy</field>
+      <field name="queue_status_facet">processing:copy:waiting</field>
+    </doc>
+    <doc>
+      <field name="id">bar</field>
+      <field name="queue_status_facet">processing</field>
+      <field name="queue_status_facet">processing:copy</field>
+      <field name="queue_status_facet">processing:copy:completed</field>
+    </doc>
+        
+That would cause the facet count to appear at all three levels
+
+- [processing](#) (2)
+    - [copy](#) (2)
+        - [completed](#) (1)
+        - [waiting](#) (1)
+
+You can skip as many levels as you'd like, as long as the "leaf" values are indexed. For example, if you didn't index the "processing" part alone, it will simply be a container, not a clickable/countable facet:
+
+- processing
+    - [copy](#) (2)
+        - [completed](#) (1)
+        - [waiting](#) (1)
+
+(**Note**: If you use Solr's built-in [PathHierarchyTokenizerFactory](http://wiki.apache.org/solr/AnalyzersTokenizersTokenFilters#solr.PathHierarchyTokenizerFactory), you can index the entire depth by supplying only the leaf nodes.)
+
+In your Blacklight controller configuration (usually `CatalogController`), tell Blacklight to render the facet using the hierarchy partial
+
+    config.add_facet_field 'queue_status_facet', :label => 'Queue Status', 
+        :partial => 'blacklight/hierarchy/facet_hierarchy'
+    
+Add the hierarchy-specific options to the controller configuration 
+
+    config.facet_display = {
+      :hierarchy => {
+        'tag' => [nil]
+      }
+    }
+
+(The `[nil]` value is present in support of rotatable facet hierarchies, which I don't have time to document right now.)
+
+## Caveats
+
+This code was ripped out of another project, and is still quite immature as a standalone project. Every effort has been made to make it as plug-and-play as possible, but it may stomp on Blacklight in unintended ways (e.g., ways that made sense in context of its former host app, but which aren't compatible with generic Blacklight). Proceed with caution, and report issues.
+
+## TODO
+
+- WRITE TESTS
+- Switch internal facet management from hack-y Hash to `Blacklight::Hierarchy::FacetGroup` class (already implemented, but not plumbed up)
+- Add configuration support for hierarchy delimiters other than `/\s*:\s*/` (baked into `Blacklight::Hierarchy::FacetGroup`, but again, requiring additional plumbing)

data/Rakefile

@@ -0,0 +1,41 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+Bundler::GemHelper.install_tasks
+
+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    = 'Blacklight::Hierarchy'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/assets/javascripts/blacklight/hierarchy/hierarchy.js

@@ -0,0 +1,34 @@
+$(document).ready(function() {
+  Blacklight.do_hierarchical_facet_expand_contract_behavior();
+});
+
+(function($) {
+  Blacklight.do_hierarchical_facet_expand_contract_behavior = function() {
+    $( Blacklight.do_hierarchical_facet_expand_contract_behavior.selector ).each (
+        Blacklight.hierarchical_facet_expand_contract
+     );
+  }
+  Blacklight.do_hierarchical_facet_expand_contract_behavior.selector = 'li.h-node';
+
+  Blacklight.hierarchical_facet_expand_contract = function() {
+    var li = $(this);
+    
+    $('ul', this).each(function() {
+      li.addClass('twiddle');
+      if($('span.selected', this).length == 0){
+        $(this).hide();
+      } else {
+        li.addClass('twiddle-open');
+      }
+    });
+
+    // attach the toggle behavior to the li tag
+    li.click(function(e){
+      if (e.target == this) {
+        // toggle the content
+        $(this).toggleClass('twiddle-open');
+        $(this).children('ul').slideToggle();
+      }
+    });
+  };
+})(jQuery);

data/app/assets/stylesheets/blacklight/hierarchy/hierarchy.css.scss

@@ -0,0 +1,13 @@
+#facets {
+  ul.facet-hierarchy {
+    margin-left: 8px;
+    ul {
+      margin-left: 0;
+      border-bottom: none;
+      padding-bottom: 0;
+      li {
+        margin-left: 8px; } }
+    li.h-node {
+      list-style-image: asset_data_url("blacklight/hierarchy/collapsed.png"); }
+    li.h-node.twiddle-open {
+      list-style-image: asset_data_url("blacklight/hierarchy/expanded.png"); } } }

data/app/helpers/blacklight/hierarchy_helper.rb

@@ -0,0 +1,135 @@
+module Blacklight::HierarchyHelper
+
+def is_hierarchical?(field_name)
+  (prefix,order,suffix) = field_name.split(/_/)
+  list = blacklight_config.facet_display[:hierarchy][prefix] and list.include?(order)
+end
+    
+def facet_order(prefix)
+  param_name = "#{prefix}_facet_order".to_sym
+  params[param_name] || blacklight_config.facet_display[:hierarchy][prefix].first
+end
+
+def facet_after(prefix, order)
+  orders = blacklight_config.facet_display[:hierarchy][prefix]
+  orders[orders.index(order)+1] || orders.first
+end
+
+def hide_facet?(field_name)
+  if is_hierarchical?(field_name)
+    prefix = field_name.split(/_/).first
+    field_name != "#{prefix}_#{facet_order(prefix)}_facet"
+  else
+    false
+  end
+end
+
+def rotate_facet_value(val, from, to)
+  components = Hash[from.split(//).zip(val.split(/:/))]
+  new_values = components.values_at(*(to.split(//)))
+  while new_values.last.nil?
+    new_values.pop
+  end
+  if new_values.include?(nil)
+    nil
+  else
+    new_values.compact.join(':')
+  end
+end
+
+def rotate_facet_params(prefix, from, to, p=params.dup)
+  return p if from == to
+  from_field = "#{prefix}_#{from}_facet"
+  to_field = "#{prefix}_#{to}_facet"
+  p[:f] = (p[:f] || {}).dup # the command above is not deep in rails3, !@#$!@#$
+  p[:f][from_field] = (p[:f][from_field] || []).dup
+  p[:f][to_field] = (p[:f][to_field] || []).dup
+  p[:f][from_field].reject! { |v| p[:f][to_field] << rotate_facet_value(v, from, to); true }
+  p[:f].delete(from_field)
+  p[:f][to_field].compact!
+  p[:f].delete(to_field) if p[:f][to_field].empty?
+  p
+end
+
+def render_facet_rotate(field_name)
+  if is_hierarchical?(field_name)
+    (prefix,order,suffix) = field_name.split(/_/)
+    new_order = facet_after(prefix,order)
+    new_params = rotate_facet_params(prefix,order,new_order)
+    new_params["#{prefix}_facet_order"] = new_order
+    link_to image_tag('icons/rotate.png', :title => new_order.upcase).html_safe, new_params, :class => 'no-underline'
+  end
+end
+
+# Putting bare HTML strings in a helper sucks. But in this case, with a 
+# lot of recursive tree-walking going on, it's an order of magnitude faster
+# than either render(:partial) or content_tag
+def render_facet_hierarchy_item(field_name, data, key)
+  item = data[:_]
+  subset = data.reject { |k,v| ! k.is_a?(String) }
+  
+  li_class = subset.empty? ? 'h-leaf' : 'h-node'
+  li = ul = ''
+  
+  if item.nil?
+    li = key
+  elsif facet_in_params?(field_name, item.qvalue)
+    li = render_selected_qfacet_value(field_name, item)
+  else
+    li = render_qfacet_value(field_name, item)
+  end
+  
+  unless subset.empty?
+    subul = subset.keys.sort.collect do |subkey| 
+      render_facet_hierarchy_item(field_name, subset[subkey], subkey) 
+    end.join('')
+    ul = "<ul>#{subul}</ul>".html_safe
+  end
+  
+  %{<li class="#{li_class}">#{li.html_safe}#{ul.html_safe}</li>}.html_safe
+end
+
+def render_hierarchy(field)
+  prefix = field.field.split(/_/).first
+  tree = facet_tree(prefix)[field.field]
+  tree.keys.sort.collect do |key|
+    render_facet_hierarchy_item(field.field, tree[key], key)
+  end.join("\n").html_safe
+end
+
+def render_qfacet_value(facet_solr_field, item, options ={})    
+  (link_to_unless(options[:suppress_link], item.value, add_facet_params(facet_solr_field, item.qvalue), :class=>"facet_select label") + " " + render_facet_count(item.hits)).html_safe
+end
+
+# Standard display of a SELECTED facet value, no link, special span
+# with class, and 'remove' button.
+def render_selected_qfacet_value(facet_solr_field, item)
+  content_tag(:span, render_qfacet_value(facet_solr_field, item, :suppress_link => true), :class => "selected label") +
+    link_to("[remove]", remove_facet_params(facet_solr_field, item.qvalue, params), :class=>"remove")
+  end
+
+HierarchicalFacetItem = Struct.new :qvalue, :value, :hits
+def facet_tree(prefix)
+  @facet_tree ||= {}
+  if @facet_tree[prefix].nil?
+    @facet_tree[prefix] = {}
+    blacklight_config.facet_display[:hierarchy][prefix].each { |key|
+      facet_field = [prefix,key,'facet'].compact.join('_')
+      @facet_tree[prefix][facet_field] ||= {}
+      data = @response.facet_by_field_name(facet_field)
+      next if data.nil?
+
+      data.items.each { |facet_item|
+        path = facet_item.value.split(/\s*:\s*/)
+        loc = @facet_tree[prefix][facet_field]
+        while path.length > 0
+          loc = loc[path.shift] ||= {}
+        end
+        loc[:_] = HierarchicalFacetItem.new(facet_item.value, facet_item.value.split(/\s*:\s*/).last, facet_item.hits)
+      }
+    }
+  end
+  @facet_tree[prefix]
+end
+
+end

data/app/views/blacklight/hierarchy/_facet_hierarchy.html.erb

@@ -0,0 +1,3 @@
+<ul class="facet-hierarchy">
+  <%= render_hierarchy(facet_field) %>
+</ul>

data/app/views/blacklight/hierarchy/_facet_hierarchy_item.html.erb

@@ -0,0 +1,25 @@
+<% 
+  item = data[:_]
+  subset = data.reject { |k,v| ! k.is_a?(String) }
+%>
+
+<li class="<%= subset.empty? ? 'h-leaf' : 'h-node'  %>">
+  <% if item.nil? %>
+    <%= key %>              
+  <% else %>
+    <% if facet_in_params?(field_name, item.qvalue) %>
+      <%= render_selected_qfacet_value( field_name, item )%>
+    <% else %>
+      <%= render_qfacet_value(field_name, item) %>              
+    <% end %>
+  <% end %>
+  <% unless subset.empty? %>
+  <ul>
+    <%=
+      raw(subset.keys.sort.collect { |subkey| 
+        render :partial => 'facet_hierarchy_item', :locals => { :field_name => field_name, :data => subset[subkey], :key => subkey } 
+      })
+    %>
+  </ul>
+  <% end %>
+</li>

data/lib/blacklight-hierarchy.rb

@@ -0,0 +1 @@
+require 'blacklight/hierarchy'

data/lib/blacklight/hierarchy.rb

@@ -0,0 +1,6 @@
+require 'blacklight/hierarchy/engine'
+
+module Blacklight
+  module Hierarchy
+  end
+end

data/lib/blacklight/hierarchy/engine.rb

@@ -0,0 +1,6 @@
+module Blacklight
+  module Hierarchy
+    class Engine < Rails::Engine
+    end
+  end
+end

data/lib/blacklight/hierarchy/hierarchical_facet.rb

@@ -0,0 +1,75 @@
+module Blacklight
+  module Hierarchy
+    class FacetItem
+      attr_reader :qname, :hits
+  
+      def initialize(qname, hits, facet)
+        @qname = qname
+        @hits = hits
+        @facet = facet
+      end
+  
+      def [](value)
+        @facet.facets([qname,value].select(&:present?).join(@facet.delimiter))
+      end
+
+      def each_pair
+        keys.each { |k| yield k, self[k] }
+      end
+  
+      def keys
+        @facet.keys(qname)
+      end
+
+      def path
+        @qname.split(@facet.delimiter)[0..-2]
+      end
+  
+      def name
+        @qname.split(@facet.delimiter).last
+      end
+  
+      def inspect
+        "#<#{self.class.name}:#{name}=>#{hits.inspect} (#{keys.join ', '})>"
+      end
+    end
+
+    class FacetGroup
+      attr_reader :facet_data, :qname, :hits, :delimiter
+      include Enumerable
+  
+      def initialize(facet_data, delimiter=":")
+        @facet_data = Hash[*facet_data]
+        @delimiter = delimiter
+      end
+  
+      def each &block
+        facets.each &block
+      end
+  
+      def each_pair
+        facets.each { |f| yield f.name, f }
+      end
+  
+      def keys(prefix=nil)
+        if prefix.nil?
+          facet_data.collect { |k,v| k.split(delimiter).first }.uniq
+        else
+          path = prefix.to_s.split(delimiter)
+          facet_data.collect do |k,v|
+            facet_path = k.split(delimiter)
+            facet_path[0..path.length-1] == path ? facet_path[path.length] : nil
+          end.compact.uniq
+        end
+      end
+  
+      def facets(prefix=nil)
+        FacetItem.new(prefix.to_s,facet_data[prefix],self)
+      end
+  
+      def [](value)
+        facets(value)
+      end
+    end
+  end
+end