bento_search 0.0.1

data/app/helpers/bento_search_helper.rb

@@ -0,0 +1,138 @@
+# Rails helper module provided by BentoSearch meant to be included
+# in host app's helpers. 
+module BentoSearchHelper
+  
+  # Renders bento search results on page, or an AJAX loader, etc, as appropriate.
+  # Pass in:
+  #   * BentoSearch::SearchResults => will render
+  #   * an instantiated BentoSearch::SearchEngine => Will do search and render
+  #   * an id that a search engine was registered under with 
+  #     BentoSearch.register_engine => will do search and render. 
+  #
+  #  Second arg options hash includes options for bento_search helper,
+  #  as well as other options pased on to BentoSearch::Engine.search(options)
+  #
+  # == Options
+  #
+  #  load: :ajax_auto, :immediate.  :ajax_auto will put a spinner up there,
+  #        and load actual results via AJAX request. :immediate preloads
+  #        results. 
+  #
+  # == Examples
+  #
+  #     bento_results( results_obj )
+  #     bento_results( engine_obj, :query => "cancer")
+  #     bento_results("google_books", :query => "cancer", :load => :ajax_auto)
+  #  
+  def bento_search(search_arg, options = {})
+    results = search_arg if search_arg.kind_of? BentoSearch::Results
+    
+    load_mode = options.delete(:load) 
+    
+    engine = nil
+    unless results
+      # need to load an engine and do a search, or ajax, etc. 
+      engine = (if search_arg.kind_of? BentoSearch::SearchEngine
+        search_arg
+      else
+        BentoSearch.get_engine(search_arg.to_s)
+      end)
+      
+    end
+
+    if (!results && load_mode == :ajax_auto)
+      raise ArgumentError.new("`:load => :ajax` requires a registered engine with an id") unless engine.configuration.id
+      content_tag(:div, :class => "bento_search_ajax_wait",
+        :"data-bento-ajax-url" => to_bento_search_url( {:engine_id => engine.configuration.id}.merge(options) )) do
+        image_tag("bento_search/large_loader.gif", :alt => I18n.translate("bento_search.ajax_loading")) +
+        content_tag("noscript") do
+          "Can not load results without javascript"
+        end
+      end
+    else
+      results = engine.search(options) unless results
+
+      if results.failed?
+        render :partial => "bento_search/search_error", :locals => {:results => results}
+      elsif results.length > 0      
+        render :partial => "bento_search/std_item", :collection => results
+      else
+        content_tag(:div, :class=> "bento_search_no_results") do
+          I18n.translate("bento_search.no_results")
+        end
+      end
+    end                          
+  end
+    
+  
+  ##
+  # More methods used by bento standard views, namespaced with bento_, sorry
+  # no great way to take logic out of views into helper methods without
+  # namespacey hack. 
+  #
+  # You can use these methods in your own custom views, you also should be
+  # able to over-ride them (including calling super) in local helpers to
+  # change behavior in standard views. 
+  #
+  ##
+  
+  def bento_abstract_truncate(str)
+    # if it's html safe, we can't truncate it, we don't have an HTML-aware
+    # truncation routine right now, that avoids leaving tags open etc. 
+    return str if str.html_safe?
+    
+    truncate(str, :length => 280, :separator => " ")    
+  end
+  
+  # Prepare a title in an H4, with formats in parens in a <small> (for
+  # bootstrap), linked, etc. 
+  def bento_item_title(item)
+    content_tag("h4", :class => "bento_item_title") do
+      safe_join([
+        link_to_unless( item.link.blank?, item.complete_title, item.link ),
+        if item.format.present? || item.format_str.present?
+          content_tag("small", :class => "bento_item_about") do
+            " (" +
+              if item.format_str
+                item.format_str
+              else
+                t(item.format, :scope => [:bento_search, :format], :default => item.format.to_s.titleize)
+              end + ")"
+          end
+        end
+      ], '')
+    end
+  end
+  
+  # first 3 authors, each in a <span>, using item.author_display, seperated by
+  # semi-colons. 
+  def bento_item_authors(item)
+    parts = []
+    
+    first_three = item.authors.slice(0,3) 
+        
+    first_three.each_with_index do |author, index|
+      parts << content_tag("span", :class => "bento_item_author") do
+          item.author_display(author)
+      end
+      if (index + 1) < first_three.length
+        parts << "; "
+      end      
+    end
+    
+    return safe_join(parts, "")
+  end
+  
+  # returns a hash of label => key suitable for passing to rails
+  # options_for_select. (Yes, it works backwards from how you'd expect). 
+  # Label is looked up using I18n, at bento_search.sort_keys.*
+  def bento_sort_hash_for(engine)
+    Hash[ 
+      engine.sort_definitions.keys.collect do |key|
+        [I18n.translate(key, :scope => "bento_search.sort_keys"), key]
+      end        
+    ]    
+  end
+  
+  
+end

data/app/item_decorators/bento_search/only_premade_openurl.rb

@@ -0,0 +1,16 @@
+require 'openurl'
+
+# A Decorator that will make #to_openurl refuse to construct
+# an openurl from individual elements, it'll use the #openurl_kev_co
+# or nothing. 
+module BentoSearch::OnlyPremadeOpenurl
+  
+  def to_openurl
+    if self.openurl_kev_co
+      return OpenURL::ContextObject.new_from_kev( self.openurl_kev_co )
+    else
+      return nil
+    end
+  end
+  
+end

data/app/item_decorators/bento_search/openurl_add_other_link.rb

@@ -0,0 +1,35 @@
+# Example of an Item Decorator that ADDs an 'other link' with an openurl. 
+#
+# This example uses crazy metaprogramming to dynamically create
+# a module configured with your base url etc. You don't need to use
+# crazy method like that; just define your own local decorator doing
+# exactly what you need, it's meant to be simple. 
+#
+#  config.item_decorators = [ BentoSearch::OpenurlAddOtherLink[:base_url => "http://resolve.somewhere.edu/foo", :extra_query => "&foo=bar"] ]
+#
+module BentoSearch::OpenurlAddOtherLink
+  def self.[](options)
+    base_url = options[:base_url]
+    extra_query = options[:extra_query] || ""
+    link_name = options[:link_name] || "Find It"
+    # overwrite: if true, overwrite previously existing other_links, if
+    # false add on to previously existing. 
+    overwrite = options.has_key?(:overwrite) ? options[:overwrite] : false    
+    
+    Module.new do
+      
+      define_method :other_links do
+        start = overwrite ? [] : super()
+        if (ou = to_openurl)
+          start + [BentoSearch::Link.new(:url => "#{base_url}?#{ou.kev}#{extra_query}", :label => link_name)]
+        else
+          start
+        end        
+      end
+      
+    end
+  end
+  
+  
+  
+end

data/app/item_decorators/bento_search/openurl_main_link.rb

@@ -0,0 +1,30 @@
+# Example of an Item Decorator that replaces the main 'link'
+# with an openurl. 
+#
+# This example uses crazy metaprogramming to dynamically create
+# a module configured with your base url etc. You don't need to use
+# crazy method like that; just define your own local decorator doing
+# exactly what you need, it's meant to be simple. 
+#
+#  config.item_decorators = [ BentoSearch::OpenurlMainLink[:base_url => "http://resolve.somewhere.edu/foo", :extra_query => "&foo=bar"] ]
+#
+module BentoSearch::OpenurlMainLink
+  def self.[](options)
+    base_url = options[:base_url]
+    extra_query = options[:extra_query] || ""
+    Module.new do
+      
+      define_method :link do
+        if (ou = to_openurl)
+          "#{base_url}?#{ou.kev}#{extra_query}"
+        else
+          nil
+        end
+      end
+      
+    end
+  end
+  
+  
+  
+end

data/app/models/bento_search/author.rb

@@ -0,0 +1,25 @@
+module BentoSearch
+  class Author
+    def initialize(args ={})
+      args.each_pair do |key, value|
+        send("#{key}=", value)
+      end
+    end
+    
+    # Can be first name or initial, whatever source provides
+    attr_accessor :first
+    # last name/surname/family name as provided by source
+    attr_accessor :last
+    # middle name or initial, as and if provided by source
+    attr_accessor :middle
+    
+    # if source doens't provide seperate first/last, 
+    # source may only be able to provide one big string, author_display
+    attr_accessor :display
+    
+    def empty?
+      first.blank? && last.blank? && middle.blank? && display.blank?
+    end
+    
+  end
+end

data/app/models/bento_search/link.rb

@@ -0,0 +1,30 @@
+module BentoSearch
+  # Represents an 'additional link' held in BentoSearch::ResultItem#other_links
+  #
+  # label, url, other metadata about the link. 
+  class Link
+    # url is normally a string, but can also be a Hash passed
+    # to url_for in the local app. 
+    attr_accessor :label, :url
+    
+    # Used both for HTML links and possibly later Atom. 
+    # Must be a string, EITHER a complete URL (representing
+    # vocab term), OR a legal short name from 
+    # http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#linkTypes    
+    attr_accessor :rel
+    
+    # Array of strings, used for CSS classes on this link, possibly
+    # for custom styles/images etc. May be used in non-html link
+    # contexts too. 
+    attr_accessor :style_classes
+    
+    def initialize(hash = {})
+      self.style_classes = []
+      
+      hash.each_pair do |key, value|
+        send("#{key}=", value)
+      end            
+    end
+    
+  end
+end

data/app/models/bento_search/multi_searcher.rb

@@ -0,0 +1,109 @@
+require 'celluloid'
+
+# Based on Celluloid, concurrently runs multiple searches in
+# seperate threads. You must include 'celluloid' gem dependency
+# into your local app to use this class. 
+#
+# I am not an expert at use of Celluloid, it's possible there's a better
+# way to do this all, but seems to work. 
+#
+# ## Usage
+#
+# initialize with id's of registered engines:
+#     searcher = BentoBox::MultiSearcher.new(:gbs, :scopus)
+#
+# start the concurrent searches, params same as engine.search
+#     searcher.start( query_params )
+#
+# retrieve results, blocking until each is completed:
+#     searcher.results
+#
+# returns a Hash keyed by engine id, values BentoSearch::Results objects. 
+#
+# Can only call #results once per #start, after that it'll return empty hash.
+# (should we make it actually raise instead?). . 
+# 
+# important to call results at some point after calling start, in order
+# to make sure Celluloid::Actors are properly terminated to avoid
+# resource leakage. 
+#
+# TODO: have a method that returns Futures instead of only supplying the blocking
+# results method? Several tricks, including making sure to properly terminate actors. 
+class BentoSearch::MultiSearcher
+  
+  def initialize(*engine_ids)
+    @engines = []
+    @actors = []
+    engine_ids.each do |id|
+      add_engine( BentoSearch.get_engine id )
+    end
+  end
+  
+  # Adds an instantiated engine directly, rather than by id from global
+  # registry. 
+  def add_engine(engine)    
+    @engines << engine
+  end
+  
+  # Starts all searches, returns self so you can chain method calls if you like. 
+  def start(*search_args)
+    @engines.each do |engine|
+      a = Actor.new(engine)
+      @actors << a
+      a.start! *search_args
+    end    
+    return self
+  end
+  
+  # Call after #start. Blocks until each included engine is finished
+  # then returns a Hash keyed by engine registered id, value is a
+  # BentoSearch::Results object. 
+  #
+  # Can only call _once_ per invocation of #start, after that it'll return
+  # an empty hash. 
+  def results
+    results = {}
+    
+    # we use #delete_if to get an iterator that deletes
+    # each item after iteration. 
+    @actors.delete_if do |actor|
+      result_key = (actor.engine.configuration.id || actor.engine.class.name)
+      results[result_key] = actor.results
+      actor.terminate
+      
+      true
+    end
+    
+    return results
+  end
+  
+  
+  class Actor
+    include Celluloid
+    
+    attr_accessor :engine
+    
+    def initialize(a_engine)
+      self.engine = a_engine
+    end
+    
+    # call as start! with bang, to invoke async. 
+    def start(*search_args)
+      begin
+        @results = self.engine.search(*search_args)
+      rescue Exception => e
+        warn e
+        # Make a fake results with caught exception. 
+        @results = BentoSearch::Results.new
+        @results.error ||= {}
+        @results.error["exception"] = e        
+      end
+    end
+    
+    def results
+      @results
+    end
+    
+  end
+  
+end

data/app/models/bento_search/openurl_creator.rb

@@ -0,0 +1,128 @@
+require 'openurl'
+
+module BentoSearch
+  
+  # Helper class used to take a ResultItem, and construct
+  # a ruby OpenURL::ContextObject out of it. That represents
+  # a NISO Z39.88 OpenURL context object, useful for using
+  # with linking software that expects such. http://en.wikipedia.org/wiki/OpenURL
+  #
+  #     co = OpenurlCreator.new(  result_item ).to_open_url
+  #        # => ruby OpenURL::ContextObject object.
+  #
+  #     co.kev 
+  #        # => context object serialized to KEV format (URL query string) 
+  #
+  # In some cases nil can be returned, if no reasonable OpenURL can
+  # be created from the ResultItem. 
+  class OpenurlCreator
+    attr_accessor :result_item
+    
+    def initialize(ri)
+      self.result_item = ri
+    end
+    
+    def to_openurl      
+      # If we have a pre-constructed KEV, just use it. 
+      if result_item.openurl_kev_co
+        return OpenURL::ContextObject.new_from_kev( result_item.openurl_kev_co )
+      end
+      
+      
+      context_object = OpenURL::ContextObject.new
+      
+      r = context_object.referent
+      
+      r.set_format( self.format )
+      
+      if result_item.doi
+        r.add_identifier("info:doi:#{result_item.doi}")
+      end
+      
+      r.set_metadata("genre", self.genre)
+      
+      if result_item.authors.length > 0
+        r.set_metadata("aufirst", result_item.authors.first.first)
+        r.set_metadata("aulast", result_item.authors.first.last)
+        r.set_metadata("au", result_item.author_display(result_item.authors.first))
+      end
+
+      r.set_metadata("date",    result_item.year.to_s)
+      r.set_metadata("volume",  result_item.volume.to_s)
+      r.set_metadata("issue",   result_item.issue.to_s)
+      r.set_metadata("spage",   result_item.start_page.to_s)
+      r.set_metadata("epage",   result_item.end_page.to_s)
+      r.set_metadata("jtitle",  result_item.journal_title)
+      r.set_metadata("issn",    result_item.issn)
+      r.set_metadata("isbn",    result_item.isbn)
+      r.set_metadata("pub",     result_item.publisher)
+      
+      case result_item.format
+      when "Book"
+        r.set_metadata("btitle", result_item.complete_title)
+      when "Article", :conference_paper
+        r.set_metadata("atitle", result_item.complete_title)
+      else
+        r.set_metadata("title", result_item.complete_title)
+      end
+      
+      return context_object
+    end      
+      
+    
+    # rft.genre value. Yeah, the legal ones differ depending on openurl
+    # 'format', but we've given up trying to do things strictly legal, 
+    # OpenURL is a bear, we do things as generally used and good enough.
+    # 
+    # can be nil. 
+    def genre
+      case result_item.format
+        when "Book"
+          "book"
+        when :book_item
+          "bookitem"
+        when :conference_paper
+          "proceeding"
+        when :conference_proceedings
+          "conference"
+        when :report
+          "report"
+        when :serial
+          "journal"
+        when "Article"
+          "article"
+        else
+          nil
+      end          
+    end
+    
+    
+    # We need to map from our formats to which OpenURL 'format'
+    # we're going to create. 
+    #
+    # We only pick from a limited set of standard scholarly citation formats,
+    # that's all any actual widespread software recognizes.
+    #
+    # Returns the last component of a valid format from:
+    # http://alcme.oclc.org/openurl/servlet/OAIHandler?verb=ListRecords&metadataPrefix=oai_dc&set=Core:Metadata+Formats
+    #
+    # Eg, "book", "journal", "dissertation". 
+    #
+    # In fact, we only pick from one of those three -- by default, if we
+    # can't figure out exactly what it is or can't map it to a specific
+    # format, we'll return 'journal', never nil. 'journal' serves, in practice, 
+    # with much actual software, as a neutral default. 
+    def format
+      case result_item.format
+      when "Book"
+        "book"
+      when :dissertation
+        "dissertation"
+      else
+        "journal"
+      end
+    end
+    
+    
+  end
+end