blacklight 5.9.4 → 5.10.0

data/lib/blacklight/configuration/search_field.rb

@@ -1,14 +1,12 @@
 module Blacklight
-  class Configuration::SearchField < Blacklight::Configuration::SolrField
+  class Configuration::SearchField < Blacklight::Configuration::Field
     def normalize! blacklight_config = nil
-      # Some normalization, calculate display_label from key,
-      # and make sure we have a qt from defaults.             
-      self.key ||= self.field
-      self.field ||= self.key
-      self.label ||= self.key.try(:titlecase)
-      self.qt ||= blacklight_config.default_solr_params[:qt] if blacklight_config && blacklight_config.default_solr_params
-      self.if = self.include_in_simple_select if self.if.nil?
+      self.if ||= self.include_in_simple_select
+
       super
+      self.qt ||= blacklight_config.default_solr_params[:qt] if blacklight_config && blacklight_config.default_solr_params
+
+      self
     end
 
     def validate!

data/lib/blacklight/configuration/solr_field.rb

@@ -1,22 +1,7 @@
 module Blacklight
-  class Configuration::SolrField < OpenStructWithHashAccess
-    def normalize! blacklight_config = nil
-      self.label ||= default_label
-      self.if = true if self.if.nil?
-      self.unless = false if self.unless.nil?
-      self
-    end
-  
-    def validate!
-      raise ArgumentError.new("Must supply a solr field name") if self.field.nil?
-    end
-
-    def default_label
-      if self.field.respond_to?(:titleize)
-        self.field.try(:titleize)
-      else
-        self.field.to_s.titleize
-      end
+  class Configuration::SolrField < Blacklight::Configuration::Field
+    def self.extended *args
+      Deprecation.warn Blacklight::Configuration::SolrField, "Blacklight::Configuration::SolrField is deprecated; use Blacklight::Configuration::Field instead"
     end
   end
 end

data/lib/blacklight/configuration/sort_field.rb

@@ -1,18 +1,17 @@
 module Blacklight
-  class Configuration::SortField < Blacklight::Configuration::SolrField
+  class Configuration::SortField < Blacklight::Configuration::Field
     def normalize! blacklight_config = nil
-      self.sort ||= self.field
-
-      self.field ||= self.key
+      super
       self.field ||= self.label.try(:parameterize)
       self.field ||= self.sort
 
-      self.key ||= self.field
-      super
+      self.sort ||= self.field
+
+      self
     end
 
     def validate!
-      raise ArgumentError.new("Must supply a solr sort string") if self.sort.nil?
+      raise ArgumentError.new("Must supply a sort string") if self.sort.nil?
     end
   end
 end

data/lib/blacklight/document.rb

@@ -0,0 +1,156 @@
+##
+##
+# = Introduction
+# Blacklight::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::Document.
+#
+# Blacklight::Document provides some DefaultFinders.
+#
+# It also provides support for Document Extensions, which advertise supported
+# transformation formats.
+#
+module Blacklight::Document
+  autoload :SchemaOrg, 'blacklight/document/schema_org'
+  autoload :DublinCore, 'blacklight/document/dublin_core'
+  autoload :Email, 'blacklight/document/email'
+  autoload :SemanticFields, 'blacklight/document/semantic_fields'
+  autoload :Sms, 'blacklight/document/sms'
+  autoload :Extensions, 'blacklight/document/extensions'
+  autoload :Export, 'blacklight/document/export'
+
+  extend ActiveSupport::Concern
+  include Blacklight::Document::SchemaOrg
+  include Blacklight::Document::SemanticFields
+  include Blacklight::Document::Export
+
+  included do
+    extend ActiveModel::Naming
+    include Blacklight::Document::Extensions
+  end    
+
+  attr_reader :response
+  alias_method :solr_response, :response
+
+  def initialize(source_doc={}, response=nil)
+    @_source = source_doc.with_indifferent_access
+    @response = response
+    apply_extensions
+  end
+
+  def to_model
+    self
+  end
+
+  def persisted?
+    true
+  end
+
+  # the wrapper method to the @_source object.
+  # If a method is missing, it gets sent to @_source
+  # with all of the original params and block
+  def method_missing(m, *args, &b)
+    @_source.send(m, *args, &b)
+  end
+
+  def [] *args
+    @_source.send :[], *args
+  end
+
+  # Helper method to check if value/multi-values exist for a given key.
+  # The value can be a string, or a RegExp
+  # Multiple "values" can be given; only one needs to match.
+  # 
+  # Example:
+  # doc.has?(:location_facet)
+  # doc.has?(:location_facet, 'Clemons')
+  # doc.has?(:id, 'h009', /^u/i)
+  def has?(k, *values)
+    return true if key?(k) and values.empty?
+    return false if self[k].nil?
+    target = self[k]
+    if target.is_a?(Array)
+      values.each do |val|
+        return target.any?{|tv| val.is_a?(Regexp) ? (tv =~ val) : (tv==val)}
+      end
+    else
+      return values.any? {|val| val.is_a?(Regexp) ? (target =~ val) : (target == val)}
+    end
+  end
+
+  def key? k
+    @_source.key? k
+  end
+
+  # helper
+  # key is the name of the field
+  # opts is a hash with the following valid keys:
+  #  - :sep - a string used for joining multivalued field values
+  #  - :default - a value to return when the key doesn't exist
+  # if :sep is nil and the field is a multivalued field, the array is returned
+  def get(key, opts={:sep=>', ', :default=>nil})
+    if key? key
+      val = self[key]
+      (val.is_a?(Array) and opts[:sep]) ? val.join(opts[:sep]) : val
+    else
+      opts[:default]
+    end
+  end
+
+  def first key
+    Array(self[key]).first
+  end
+
+  def id
+    self[self.class.unique_key]
+  end
+
+  def to_param
+    id.to_s
+  end
+
+  def as_json(options = nil)
+    @_source.as_json(options)
+  end
+
+  def to_partial_path
+    'catalog/document'
+  end
+
+  def destroyed?
+    false
+  end
+  
+  def new_record?
+    false
+  end
+  
+  def has_highlight_field? k
+    false
+  end
+
+  def highlight_field k
+    nil
+  end
+
+
+  # Certain class-level methods needed for the document-specific
+  # extendability architecture
+  module ClassMethods
+
+    attr_writer :unique_key
+    def unique_key
+      @unique_key ||= 'id' 
+    end
+
+    def primary_key
+      unique_key
+    end
+    
+    def base_class
+      self
+    end  
+  end
+end

data/lib/blacklight/document/dublin_core.rb

@@ -0,0 +1,41 @@
+require 'builder'
+
+# This module provide Dublin Core export based on the document's semantic values
+module Blacklight::Document::DublinCore
+
+  def self.extended(document)
+    # Register our exportable formats
+    Blacklight::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/document/email.rb

@@ -0,0 +1,16 @@
+# -*- encoding : utf-8 -*-
+# This module provides the body of an email export based on the document's semantic values
+module Blacklight::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 << I18n.t('blacklight.email.text.title', value: semantics[:title].join(" ")) unless semantics[:title].blank?
+    body << I18n.t('blacklight.email.text.author', value: semantics[:author].join(" ")) unless semantics[:author].blank?
+    body << I18n.t('blacklight.email.text.format', value: semantics[:format].join(" ")) unless semantics[:format].blank?
+    body << I18n.t('blacklight.email.text.language', value: semantics[:language].join(" ")) unless semantics[:language].blank?
+    return body.join("\n") unless body.empty?
+  end
+
+end

data/lib/blacklight/document/export.rb

@@ -0,0 +1,107 @@
+# == 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. (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
+#
+module Blacklight::Document::Export
+
+  ##  
+  # 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.
+    if defined?(Mime) && Mime.const_defined?(short_name.to_s.upcase)      
+      mime_type = "Mime::#{short_name.to_s.upcase}".constantize
+      content_type = mime_type.to_s unless content_type      
+    else
+      # 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
+  
+  def exports_as? short_name
+    respond_to? "export_as_#{short_name.to_s}"
+  end
+end

data/lib/blacklight/document/extensions.rb

@@ -0,0 +1,56 @@
+# = Document Extensions
+# An Blacklight::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.
+#
+# == Extension Parameters
+# Every class that includes Blacklight::Solr::Document::Extensions 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::Document::Extensions
+  extend ActiveSupport::Concern
+
+  # 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
+
+  module ClassMethods
+    attr_writer :registered_extensions
+
+    # 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
+  end
+end