blacklight 3.0pre1

data/lib/blacklight/search_fields.rb

@@ -0,0 +1,107 @@
+##
+# Module to deal with accessing (and setting some defaults) in an array of
+# hashes that describe Blacklight search fields.  Requires the base class this
+# module is added to implements a #config method that returns a hash, where
+# config[:search_fields] will be an array of hashes describing search fields.
+#
+# = Search Field Configuration Hash =
+# [:key]
+#   "title", required, unique key used in search URLs to specify search_field 
+# [:display_label]
+#   "Title",  # user-displayable label, optional, if not supplied :key.titlecase will be used
+# [:qt]
+#   "search", # Solr qt param, request handler, usually can be left blank; defaults to Blacklight.config[:default_solr_params][:qt] if not specified. 
+# [:solr_parameters]
+#   {:qf => "something"} # optional hash of additional parameters to pass to solr for searches on this field.
+# [:solr_local_parameters]
+#   {:qf => "$something"} # optional hash of additional parameters that will be passed using Solr LocalParams syntax, that can use dollar sign to reference other solr variables.
+# [:include_in_simple_select]
+#   false.  Defaults to true, but you can set to false to have a search field defined for deep-links or BL extensions, but not actually included in the HTML select for simple search choice.
+# 
+# Optionally you can supply a :key, which is what Blacklight will use
+# to identify this search field in HTTP query params. If no :key is
+# supplied, one will be computed from the :display_label. If that will
+# result in a collision of keys, you should supply one explicitly. 
+#
+##
+module Blacklight::SearchFields
+  extend ActiveSupport::Memoizable
+
+  # Looks up search field config list from config[:search_fields], and
+  # 'normalizes' all field config hashes using normalize_config method. 
+  # Memoized for efficiency of normalization. 
+  def search_field_list
+    normalized = config[:search_fields].collect {|obj| normalize_config(obj)}
+
+    if (duplicates = normalized.collect{|h| h[:key]}.uniq!)
+      raise "Duplicate keys found in search_field config: #{duplicates.inspect}"
+    end
+    
+    normalized
+  end
+  memoize :search_field_list
+
+  # Returns suitable argument to options_for_select method, to create
+  # an html select based on #search_field_list. Skips search_fields
+  # marked :include_in_simple_select => false
+  def search_field_options_for_select
+    search_field_list.collect do |field_def|
+      [field_def[:display_label],  field_def[:key]] unless field_def[:include_in_simple_select] == false
+    end.compact
+  end
+
+  # Looks up a search field config hash from search_field_list having
+  # a certain supplied :key. 
+  def search_field_def_for_key(key)
+    return nil if key.blank?
+    search_field_list.find {|c| c[:key] == key}
+  end
+
+  # Returns default search field, used for simpler display in history, etc.
+  # if not set in config, defaults to first field listed in #search_field_list
+  def default_search_field
+    config[:default_search_field] || search_field_list[0]
+  end
+  memoize :default_search_field
+
+  # Shortcut for commonly needed operation, look up display
+  # label for the key specified. Returns "Keyword" if a label
+  # can't be found. 
+  def label_for_search_field(key)
+    field_def = search_field_def_for_key(key)
+    if field_def && field_def[:display_label]
+       field_def[:display_label]
+    else
+       "Keyword"
+    end            
+  end
+
+  protected
+  # Fill in missing default values in a search_field config hash.
+  def normalize_config(field_hash)
+
+
+    # Accept legacy two-element array, if it's not a Hash, assume it's legacy.
+    # No great way to 'duck type' here. 
+    unless ( field_hash.kind_of?(Hash))      
+      # Consistent with legacy behavior where two fields can have the same label,
+      # as long as they have different qt's, we base the unique :key on :qt. 
+      field_hash = {:display_label => field_hash[0], :key => field_hash[1], :qt => field_hash[1]}
+    else
+      # Make a copy of passed in Hash so we don't alter original. 
+      field_hash = field_hash.clone
+    end        
+
+    raise Exception.new("Search field config is missing ':key' => #{field_hash.inspect}") unless field_hash[:key]
+    
+    # If no display_label was provided, turn the :key into one.      
+    field_hash[:display_label] ||= field_hash[:key].titlecase
+
+    # If no :qt was provided, take from config default
+    field_hash[:qt] ||= config[:default_solr_params][:qt] if config[:default_solr_params]
+  
+    field_hash
+  end
+  
+  
+end

data/lib/blacklight/solr.rb

@@ -0,0 +1,7 @@
+module Blacklight::Solr
+  
+  autoload :Facets, 'blacklight/solr/facets'
+  autoload :FacetPaginator, 'blacklight/solr/facet_paginator'
+  autoload :Document, 'blacklight/solr/document'
+  
+end

data/lib/blacklight/solr/document.rb

@@ -0,0 +1,239 @@
+require 'rsolr'
+require 'rsolr-ext'
+##
+##
+# = Introduction
+# Blacklight::Solr::Document is the module with logic for a class representing
+# an individual document returned from Solr results.  It can be added in to any
+# local class you want, but in default Blacklight a SolrDocument class is
+# provided for you which is pretty much a blank class "include"ing
+# Blacklight::Solr::Document.
+#
+# Blacklight::Solr::Document mixes in Rsolr::Ext::Model to the calling class.
+# It also provides some DefaultFinders.
+#
+# It also provides support for Document Extensions, which advertise supported
+# transformation formats.
+#
+# = Document Extensions
+# An Blacklight::Solr::Document extension is simply a ruby module which is mixed
+# in to individual Document instances.  The intended use case is for documents
+# containing some particular format of source material, such as Marc. An
+# extension can be registered with your document class, along with a block
+# containing custom logic for which documents to apply the extension to.
+#
+# SolrDocument.use_extension(MyExtension) {|document| my_logic_on_document(document}
+#
+# MyExtension will be mixed-in (using ruby 'extend') only to those documents
+# where the block results in true.
+#
+# == Transformation conventions
+# The main use case for extensions is for transforming a Document to another
+# format. Either to another type of Ruby object, or to an exportable string in
+# a certain format. 
+#
+# The convention for methods contained in extensions that transform to a ruby
+# object is "to_*".  For instance, "to_marc" would return a Ruby Marc object.
+#
+# The convention for methods contained in extensions that transform to an
+# exportable file of some kind is "export_as_*".  For instance,
+# "export_as_marc21" would return a String object containing valid marc21, and
+# "export_as_marcxml" would return a String object containing valid marcxml.
+#
+# The tokens used after "export_as" should normally be the format names as
+# registered with Rails Mime::Type.
+#
+# == Advertising export formats
+#
+# If an extension advertises what export formats it can provide, than those
+# formats will automatically be delivered by the Blacklight catalog/show
+# controller, and potentially automatically advertised in various places
+# that advertise available formats. (UnAPI; HTML link rel=alternate; Atom 
+# link rel=alterate; etc).
+#
+# Export formats are 'registered' by calling the #will_export_as method
+# on a Document instance. An extension would usually do this in a
+# self.extended method, so it can be called on Documents that have
+# the given extension added to them. For instance:
+#
+#   module DemoMarcExtension
+#     def self.extended(document)
+#       document.will_export_as(:marc21, "application/marc")
+#       document.will_export_as(:marcxml, "application/marcxml+xml")
+#     end
+#
+#     def export_as_marc21 ; something ; end
+#     def export_as_marcxml ; something ; end
+#   end
+#
+# == Extension Parameters
+# Every class that includes Blacklight::Solr::Document gets a
+# #extension_parameters method for saving arbitrary parameters on class-wide
+# level that can be retrieved by extensions. These are arbitrary, just
+# conventions with a given extension. For instance:
+# SolrDocument.extension_parameters[:marc_source_field] = "solr_stored_field_name"
+#
+module Blacklight::Solr::Document
+  autoload :Marc, 'blacklight/solr/document/marc'
+  autoload :MarcExport, 'blacklight/solr/document/marc_export'
+  autoload :DublinCore, 'blacklight/solr/document/dublin_core'
+  autoload :Email, 'blacklight/solr/document/email'
+  autoload :Sms, 'blacklight/solr/document/sms'
+  
+  def self.included(base)      
+    base.send :include, RSolr::Ext::Model
+    base.send :extend,  ClassMethods
+   
+    # after_initialize hook comes from RSolr::Ext::Model, I think.
+    # We need to make sure all extensions get applied.
+    base.after_initialize do 
+       apply_extensions 
+    end
+  end    
+    
+
+    # Needs to be called in initializer of class including this module, to
+    # apply all registered extensions on a per-document basis
+    def apply_extensions
+      self.class.registered_extensions.each do | registration|
+        self.extend( registration[:module_obj] ) if registration[:condition_proc].nil? || registration[:condition_proc].call( self )
+      end
+    end
+    
+    ##  
+    # Register exportable formats supported by the individual document.
+    # Usually called by an extension in it's self.extended method, to
+    # register the formats that extension can export. 
+    # 
+    # some_document.will_export_as(:some_format, "application/type") means
+    # that the document (usually via an extension) has a method
+    # "export_as_some_format" which returns a String of content that
+    # is described by the mime content_type given. 
+    # 
+    # The format name should ideally _already_ be registered with
+    # Rails Mime::Type, in your application initializer, representing
+    # the content type given.  However, this method will attempt to
+    # register it using Mime::Type.register_alias if it's not previously
+    # registered. This is a bit sketchy though. 
+    def will_export_as(short_name, content_type = nil)
+      #Lookup in Rails Mime::Type, register if needed, otherwise take
+      # content-type from registration if needed. This uses
+      # some 'api' to Mime::Type that may or may not be entirely
+      # public, the fact that a Mime::CONST is registered for every
+      # type. But that's the only way to do the kind of check we need, sorry.
+      begin      
+        mime_type = "Mime::#{short_name.to_s.upcase}".constantize
+        content_type = mime_type.to_s unless content_type      
+      rescue NameError
+        # not registered, we need to register. Use register_alias to be least
+        # likely to interfere with host app. 
+        Mime::Type.register_alias(content_type, short_name)
+      end
+      
+      # if content_type is nil, look it up from Rails Mime::Type
+      if content_type.nil?
+        # Accurate lookup in Rails Mime::Type is kind of pain, it doesn't
+        # really provide the right API.
+        if defined?(type_const_name)
+          content_type = type_const_name.constantize.to_s
+        end    
+      end    
+      export_formats[short_name] =  {:content_type => content_type}
+    end
+    
+    # Collects formats that this doc can export as.
+    # Returns a hash, keys are format short-names that can
+    # be exported. Hash includes:
+    #  :content-type => mime-content-type
+    #  maybe more later
+    # To see if a given export format is supported by this document,
+    # simply call document.export_formats.keys.include?(:my_format)
+    # Then call #export_as! to do the export. 
+    def export_formats
+      @export_formats ||= {}
+    end
+    
+    # Call with a format shortname, export_as(:marc), simply returns
+    # #export_as_marc . Later we may expand the design to allow you
+    # to register an arbitrary method name instead of insisting
+    # on the convention, so clients should call this method so
+    # they'll still keep working if we do that. 
+    def export_as(short_name)
+      send("export_as_#{short_name.to_s}")
+    end
+    
+    # Returns a hash keyed by semantic tokens (see ExtendableClassMethods#semantic_fields), value is an array of
+    # strings. (Array to handle multi-value fields). If no value(s)
+    # available, empty array is returned. 
+    #
+    # Default implementation here uses ExtendableClassMethods#semantic_fields
+    # to just take values from Solr stored fields. 
+    # Extensions can over-ride this method to provide better/different lookup,
+    # but extensions should call super and modify hash returned, to avoid
+    # unintentionally erasing values provided by other extensions. 
+    def to_semantic_values
+      unless @semantic_value_hash
+        @semantic_value_hash = Hash.new([]) # default to empty array   
+        self.class.field_semantics.each_pair do |key, solr_field|
+          value = self[solr_field]
+          # Make single and multi-values all arrays, so clients
+          # don't have to know.
+          unless value.nil?
+            value = [value] unless value.kind_of?(Array)      
+            @semantic_value_hash[key] = value
+          end
+        end
+      end
+      return @semantic_value_hash
+    end
+  
+    
+  # Certain class-level methods needed for the document-specific
+  # extendability architecture
+  module ClassMethods
+    attr_writer :registered_extensions
+    
+    # Returns array of hashes of registered extensions. Each hash
+    # has a :module_obj key and a :condition_proc key. Usually this
+    # method is only used internally in #apply_extensions, but if you
+    # want to zero out all previously registered extensions you can call:
+    # SolrDocument.registered_extensions = nil
+    def registered_extensions
+      @registered_extensions ||= []
+    end
+
+    def extension_parameters
+      @extension_parameters ||= {}
+    end      
+        
+    # Register an extension module with the class. A block taking one
+    # parameter can be supplied; the block will be passed an instance of 
+    # a Document, and the extension will be applied only if the block
+    # evaluates as true. If no condition is given, the extension will
+    # be applied to every instance of the class.
+    #
+    # SolrDocument.use_extension( SomeExtensionModule ) { | document | should_apply_some_extension?(document) }
+    # SolrDocument.use_extension( SomeExtensionModule) # will be applied to all docs
+    def use_extension( module_obj, &condition )
+      registered_extensions << {:module_obj => module_obj, :condition_proc => condition}    
+    end
+
+    # Class-level method for accessing/setting semantic mappings
+    # for solr stored fields. Can be set by local app, key is
+    # a symbol for a semantic, value is a solr _stored_ field.
+    #
+    # Stored field can be single or multi-value. In some cases
+    # clients may only use the first value from a multi-value field.
+    #
+    # Currently documented semantic tokens, not all may be
+    # used by core BL, but some may be used by plugins present
+    # or future. 
+    # :title, :author, :year, :language => User-presentable strings. 
+    def field_semantics
+      @field_semantics ||= {}
+    end    
+  end
+  
+ 
+  
+end

data/lib/blacklight/solr/document/dublin_core.rb

@@ -0,0 +1,40 @@
+require 'builder'
+
+# This module provide Dublin Core export based on the document's semantic values
+module Blacklight::Solr::Document::DublinCore
+  def self.extended(document)
+    # Register our exportable formats
+    Blacklight::Solr::Document::DublinCore.register_export_formats( document )
+  end
+
+  def self.register_export_formats(document)
+    document.will_export_as(:xml)
+    document.will_export_as(:dc_xml, "text/xml")
+    document.will_export_as(:oai_dc_xml, "text/xml")
+  end
+
+  def dublin_core_field_names
+    [:contributor, :coverage, :creator, :date, :description, :format, :identifier, :language, :publisher, :relation, :rights, :source, :subject, :title, :type]
+  end
+
+  # dublin core elements are mapped against the #dublin_core_field_names whitelist.
+  def export_as_oai_dc_xml
+    xml = Builder::XmlMarkup.new
+    xml.tag!("oai_dc:dc",
+             'xmlns:oai_dc' => "http://www.openarchives.org/OAI/2.0/oai_dc/",
+             'xmlns:dc' => "http://purl.org/dc/elements/1.1/",
+             'xmlns:xsi' => "http://www.w3.org/2001/XMLSchema-instance",
+             'xsi:schemaLocation' => %{http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc.xsd}) do
+       self.to_semantic_values.select { |field, values| dublin_core_field_names.include? field.to_sym }.each do |field,values|
+         values.each do |v|
+           xml.tag! 'dc:' + field.to_s, v
+         end
+       end
+     end
+    xml.target!
+  end
+
+  alias_method :export_as_xml, :export_as_oai_dc_xml
+  alias_method :export_as_dc_xml, :export_as_oai_dc_xml
+
+end

data/lib/blacklight/solr/document/email.rb

@@ -0,0 +1,15 @@
+# This module provides the body of an email export based on the document's semantic values
+module Blacklight::Solr::Document::Email
+
+  # Return a text string that will be the body of the email
+  def to_email_text
+    semantics = self.to_semantic_values
+    body = ""
+    body << "Title: #{semantics[:title].join(" ")}\n" unless semantics[:title].blank?
+    body << "Author: #{semantics[:author].join(" ")}\n" unless semantics[:author].blank?
+    body << "Format: #{semantics[:format].join(" ")}\n" unless semantics[:format].blank?
+    body << "Language: #{semantics[:language].join(" ")}" unless semantics[:language].blank?
+    return body unless body.blank?
+  end
+
+end

data/lib/blacklight/solr/document/marc.rb

@@ -0,0 +1,84 @@
+
+# This is a document extension meant to be mixed into a
+# Blacklight::Solr::Document class, such as SolrDocument. It provides support
+# for restoration of MARC data (xml or binary) from a Solr stored field, and
+# then provides various transformations/exports of that Marc via the included
+# Blacklight::Solr::Document::MarcExport module.
+#
+# This extension would normally be registered using 
+# Blacklight::Solr::Document#use_extension.  eg:
+#
+# SolrDocument.use_extension( Blacklight::Solr::Document::Marc ) { |document| my_logic_for_document_has_marc?( document ) }
+#
+# This extension also expects a :marc_source_field and :marc_format_type to
+# be registered with the hosting classes extension_parameters. In an initializer
+# or other startup code:
+# SolrDocument.extension_paramters[:marc_source_field] = "name_of_solr_stored_field"
+# SolrDocument.extension_parameters[:marc_format_type] = :marc21 # or :marcxml
+module Blacklight::Solr::Document::Marc
+
+  include Blacklight::Solr::Document::MarcExport # All our export_as stuff based on to_marc. 
+  
+  class UnsupportedMarcFormatType < RuntimeError; end
+    
+  def self.extended(document)
+    # Register our exportable formats, we inherit these from MarcExport    
+    Blacklight::Solr::Document::MarcExport.register_export_formats( document )
+  end
+
+  # DEPRECATED. Here for legacy purposes, but use to_marc instead. Or
+  # internally, use the protected _marc_helper method to get the
+  # (somewhat confusingly named)  Blacklight::Marc::Document helper object.
+  #
+  # This method gets attached to a SolrDocument.
+  # it uses the marc_source_field and marc_format_type
+  # class attributes to create the Blacklight::Marc::Document instance.
+  # Only returns a Blacklight::Marc::Document instance if
+  # the self.class.marc_source_field key exists.
+  def marc
+    warn "[DEPRECATION] aDocument.marc is deprecated.  Please use aDocument.respond_to?(:to_marc) / aDocument.respond_to?(:marc),  or aDocument.exports_as.keys.include?(:some_format) / aDocument.export_as(:some_format) instead."
+
+    _marc_helper
+  end  
+
+  # ruby-marc object
+  def to_marc
+    @_ruby_marc_obj ||= load_marc
+  end
+
+
+  protected
+  def marc_source
+    @_marc_source ||= fetch(_marc_source_field)
+  end
+
+  def load_marc
+    case _marc_format_type.to_s
+    when 'marcxml'
+      records = MARC::XMLReader.new(StringIO.new( fetch(_marc_source_field) )).to_a
+      return records[0]
+    when 'marc21'
+      return MARC::Record.new_from_marc( fetch(_marc_source_field) )          
+    else
+
+      raise UnsupportedMarcFormatType.new("Only marcxml and marc21 are supported, this documents format is #{_marc_format_type} and the current extension parameters are #{self.class.extension_parameters.inspect}")
+    end      
+  end
+  
+  
+  
+  def _marc_helper
+    @_marc_helper ||= (
+      Blacklight::Marc::Document.new fetch(_marc_source_field), _marc_format_type )
+  end
+
+  def _marc_source_field    
+    self.class.extension_parameters[:marc_source_field]
+  end
+
+  def _marc_format_type
+        #TODO: Raise if not present
+    self.class.extension_parameters[:marc_format_type]    
+  end
+  
+end