bento_search 0.8.0 → 0.9.0

data/README.md

@@ -292,7 +292,7 @@ do not provide additional links by default, custom local Decorators would
 be used to add them. See wiki for more info on decorators, and BentoSearch::Link
 for fields. 
      
-## OpenURL and metadata
+### OpenURL and metadata
 
 Academic library uses often need openurl links from scholarly citations. One of
 the design goals of bento_search is to produce standardized normalized BentoSearch::ResultItem
@@ -309,7 +309,21 @@ can be solved.
 
 See `./app/item_decorators/bento_search/openurl_add_other_link.rb` for an example
 of using item decorators to add a link to your openurl resover to an item when
-displayed. 
+displayed.
+
+### Exporting (eg as RIS) and get by unique_id
+
+A class is included to convert an individual BentoSearch::ResultItem to
+the RIS format, suitable for import into EndNote, Refworks, etc. 
+
+~~~ruby
+    ris_data = RISCreator.new( bento_item ).export 
+~~~
+
+Accomodating actual exports into the transactional flow of a web app can be
+tricky, and often requires use of the `result_item#unique_id` and 
+`engine.get( unique_id )` features. See the wiki at 
+
 
 ## Planned Features
 

data/app/helpers/bento_search_helper.rb

@@ -60,12 +60,10 @@ module BentoSearchHelper
       end +
       content_tag(:div, 
         :class => "bento_search_ajax_loading", 
-        :style => "display:none") do
-      
+        :style => "display:none") do      
           image_tag("bento_search/large_loader.gif", 
-            :alt => I18n.translate("bento_search.ajax_loading"),            
+            :alt => I18n.translate("bento_search.ajax_loading")            
           ) 
-
         end
       end
     else
@@ -88,13 +86,9 @@ module BentoSearchHelper
   
   # Wrap a ResultItem in a decorator! For now hard-coded to
   # BentoSearch::StandardDecorator
-  def bento_decorate(result_item)
-    # What decorator class? If specified as string in #decorator,
-    # look it up as a class object, else default. 
-    decorator_class = result_item.decorator.try {|name| BentoSearch::Util.constantize(name) } || BentoSearch::StandardDecorator  
-    
+  def bento_decorate(result_item)    
     # in a helper method, 'self' is a view_context already I think?
-    decorated = decorator_class.new(result_item, self)    
+    decorated = BentoSearch::DecoratorBase.decorate(result_item, self)    
     yield(decorated) if block_given?    
     return decorated    
   end

data/app/item_decorators/bento_search/decorator_base.rb

@@ -49,5 +49,22 @@ module BentoSearch
       ERB::Util.html_escape(*args, &block)
     end
     
+    # Applies decorator to item and returns decorated item. 
+    # uses standard logic to look up which decorator to apply or
+    # applies default one. The point of this method is just that
+    # standard logic. 
+    #
+    # Need to pass a Rails ActionView::Context in, to use to
+    # initialize decorator. In Rails, in most places you can
+    # get one of those from #view_context. In helpers/views 
+    # you can also use `self`. 
+    def self.decorate(item, view_context)
+      # What decorator class? If specified as string in #decorator,
+      # look it up as a class object, else default. 
+      decorator_class = item.decorator.try {|name| BentoSearch::Util.constantize(name) } || BentoSearch::StandardDecorator  
+      
+      return decorator_class.new(item, view_context)    
+    end
+    
   end  
 end

data/app/item_decorators/bento_search/standard_decorator.rb

@@ -16,11 +16,11 @@ module BentoSearch
     
     # How to display a BentoSearch::Author object as a name    
     def author_display(author)
-      if (author.first && author.last)
+      if (author.first.present? && author.last.present?)
         "#{author.last}, #{author.first.slice(0,1)}"
-      elsif author.display
+      elsif author.display.present?
         author.display
-      elsif author.last
+      elsif author.last.present?
         author.last
       else
         nil

data/app/models/bento_search/link.rb

@@ -18,6 +18,9 @@ module BentoSearch
     # contexts too. 
     attr_accessor :style_classes
     
+    # Suggested `target` attribute to render link with as html <a> 
+    attr_accessor :target
+    
     def initialize(hash = {})
       self.style_classes = []
       

data/app/models/bento_search/result_item.rb

@@ -26,6 +26,11 @@ module BentoSearch
       self.custom_data ||= {}
     end
     
+    # internal unique id for the document, from the particular
+    # search service it came from. May be alphanumeric. May be nil
+    # for engines that don't support it. 
+    attr_accessor :unique_id 
+    
     # If set to true, item will refuse to generate an openurl,
     # returning nil from #to_openurl or #openurl_kev
     attr_accessor :openurl_disabled 
@@ -75,7 +80,6 @@ module BentoSearch
     # * WebPage
     # * VideoObject
     # * AudioObject
-    # * SoftwareApplication
     # 
     # 
     # 
@@ -185,6 +189,18 @@ module BentoSearch
     # qualified name of a decorator class. Can be nil for default. 
     attr_accessor :decorator
     
+    # Copied over from engine configuration :for_display key
+    # by BentoSearch#search wrapper, here as a convenience t
+    # parameterize logic in decorators or other presentational logic, based
+    # on configuration, in places where logic has access to an item but
+    # not the overall Results obj anymore. 
+    #
+    # TODO: Consider, should we just copy over the whole Results
+    # into a backpointing reference instead? And user cover-methods
+    # for it? Nice thing about the configuration has instead is it's
+    # easily serializable, it's just data.  
+    attr_accessor :display_configuration
+    attr_accessor :engine_id
     
   end
 end

data/app/models/bento_search/results.rb

@@ -59,5 +59,10 @@ module BentoSearch
     def failed?
       ! error.nil?
     end
+    
+    def inspect
+      "<BentoSearch::Results #{super} #{'FAILED' if self.failed?}>"
+    end
+    
   end
 end

data/app/models/bento_search/ris_creator.rb

@@ -0,0 +1,166 @@
+module BentoSearch
+  #
+  # Export a BentoSearch::ResultItem in RIS format, as a file
+  # to import into EndNote etc, or in a callback for Refworks export, etc. 
+  #
+  # RISCreator.new( result_item ).export
+  #
+  # Note: We assume input and output in UTF8. The RIS spec kind of says
+  # it has to be ascii only, but most actual software seems to be able to do
+  # UTF8. 
+  #
+  # Note: If you want your decorator to be taken into account in links
+  # or other data, you have to make sure it's applied. If you got result_item
+  # from SearchEngine#get, you should apply decorators yourself:
+  #
+  #    RISCreator.new(  BentoSearch::StandardDecorator.decorate(result_item) ).export
+  # 
+  #
+  # Best spec/docs for RIS format seems to be at 
+  # http://www.refman.com/support/risformat_intro.asp
+  # Download zip file there, pay attention to excel spreadsheet
+  # as well as PDF overview. 
+  #
+  # But note this 'spec' is often ignored/violated, even by the vendors
+  # who wrote it. Wikipedia at http://en.wikipedia.org/wiki/RIS_(file_format)#Tags
+  # contains some additional tags not mentioned in 'spec'. 
+  class RISCreator
+    def initialize(i)
+      @item = i
+      @ris_format = translate_ris_format
+    end
+    
+    def export
+      out = "".force_encoding("UTF-8")
+      
+      out << tag_format("TY", @ris_format)
+      
+      out << tag_format("TI", @item.title)
+      
+      @item.authors.each do |author|
+        out << tag_format("AU", format_author_name(author))
+      end
+      
+      out << tag_format("PY", @item.year)
+      out << tag_format("DA", format_date(@item.publication_date))
+      
+      out << tag_format("LA", @item.language_str)
+      
+      out << tag_format("VL", @item.volume)
+      out << tag_format("IS", @item.issue)
+      out << tag_format("SP", @item.start_page)
+      out << tag_format("EP", @item.end_page)
+      
+      out << tag_format("T2", @item.source_title)
+      
+      # ISSN and ISBN both share SN, sigh. 
+      out << tag_format("SN", @item.issn)
+      out << tag_format("SN", @item.isbn)
+      out << tag_format("DO", @item.doi)
+      
+      out << tag_format("PB", @item.publisher)
+      
+      out << tag_format("AB", @item.abstract)
+      
+      # include main link and any other links?
+      out << tag_format("UR", @item.link)
+      @item.other_links.each do |link|
+        out << tag_format("UR", link.url)
+      end
+      
+      # end with blank lines, so multiple ones can be concatenated for
+      # a file. 
+      out << "\r\nER  - \r\n\r\n"
+    end
+    
+    @@format_map = {
+      # bento_search doesn't distinguish between journal, magazine, and newspaper,
+      # RIS does, sorry, we map all to journal article. 
+      "Article"         => "JOUR",
+      "Book"            => "BOOK",
+      "Movie"           => "MPCT",
+      "MusicRecording"  => "MUSIC",
+      #"Photograph"     => "GEN",
+      "SoftwareApplication" => "COMP",
+      "WebPage"         => "ELEC",
+      "VideoObject"     => "VIDEO",
+      "AudioObject"     => "SOUND",
+      :serial           => "SER",
+      :dissertation     => "THES",
+      :conference_paper => "CPAPER",
+      :conference_proceedings => "CONF",
+      :report           => "RPRT",
+      :book_item        => "CHAP"      
+    }
+    
+    # based on current @item.format, output
+    # appropriate RIS format string
+    def translate_ris_format
+      # default "GEN"=generic if unknown 
+      @@format_map[@item.format] || "GEN"
+    end
+    
+    # Formats refworks tag/value line and returns it. 
+    # 
+    # Returns empty string if you pass in an empty value though. 
+    # 
+    # "Each six-character tag must be in the following format:
+    # "<upper-case letter><upper-case letter or number><space><space><dash><space>"
+    #
+    # "Each tag and its contents must be on a separate line, 
+    # preceded by a "carriage return/line feed" (ANSI 13 10)."
+    #
+    # "Note, however, that the asterisk (character 42)
+    # is not allowed in the author, keywords or periodical name fields."
+    #
+    # The spec also seems to say ascii-only, but I don't think that's true
+    # for actually existing software, we do utf-8. 
+    #
+    # Refworks MAY require unicode composed normalization if it accepts utf8
+    # at all. but not doing that yet. http://bibwild.wordpress.com/2010/04/28/refworks-problems-importing-diacritics/
+    def tag_format(tag, value)
+      return "" if value.blank?
+      
+      raise ArgumentError.new("Illegal RIS tag") unless tag =~ /[A-Z][A-Z0-9]/
+      
+      # "T2" seems to be the only "journal name field", which is
+      # mentioned along with these others as not being allowed to contain
+      # asterisk. 
+      if ["AU", "A2", "A3", "A4", "KW", "T2"].include? tag
+        value = value.gsub("*", " ")
+      end
+      
+      return "\r\n#{tag}  - #{value}"
+    end    
+    
+    # Take a ruby Date and translate to RIS date format
+    # "YYYY/MM/DD/other info"
+    # 
+    # returns nil if input is nil. 
+    def format_date(d)
+      return nil if d.nil?
+      
+      return d.strftime("%Y/%m/%d")
+    end
+    
+    # RIS wants `Last, First M.`, we'll do what we can. 
+    def format_author_name(author)
+      if author.last.present? && author.first.present?
+        str = "#{author.last}, #{author.first}"
+        if author.middle.present?
+          middle = author.middle
+          middle += "." if middle.length == 1
+          str += " #{middle}"
+        end
+        return str
+      elsif author.display.present?
+        return author.display
+      elsif author.last.present?
+        return author.last?
+      else
+        return nil
+      end        
+    end
+    
+  end
+end

data/app/models/bento_search/search_engine.rb

@@ -8,6 +8,12 @@ require 'multi_json'
 require 'nokogiri'
 
 module BentoSearch
+  # Usually raised by #get on an engine, when result for specified identifier
+  # can't be found. 
+  class NotFound < Exception ; end
+  # Usually raised by #get when identifier results in more than one record. 
+  class TooManyFound < Exception ; end
+  
   # Module mix-in for bento_search search engines. 
   #
   # ==Using a SearchEngine 
@@ -219,7 +225,14 @@ module BentoSearch
       results.timing = (Time.now - start_t)
             
       results.display_configuration = configuration.for_display
-      results.each {|item| item.decorator = configuration.lookup!("for_display.decorator") }
+      results.each do |item| 
+        # We copy some configuraton info over to each Item, as a convenience
+        # to display logic that may have decide what to do given only an item,
+        # and may want to parameterize based on configuration.
+        item.engine_id              = results.engine_id 
+        item.decorator              = configuration.lookup!("for_display.decorator")
+        item.display_configuration  = configuration.for_display
+      end
         
       return results
     rescue *auto_rescue_exceptions => e
@@ -235,6 +248,13 @@ module BentoSearch
       failed = BentoSearch::Results.new
       failed.error ||= {}
       failed.error[:exception] = e
+      
+      failed.search_args           = arguments
+      failed.engine_id             = configuration.id
+      failed.display_configuration = configuration.for_display
+      failed.timing                = (Time.now - start_t)
+
+      
       return failed
     end
         
@@ -355,7 +375,7 @@ module BentoSearch
     # to be something diff in production and dev?
     #
     # This default list is probably useful already, but individual
-    # engines can override if it's convenient for their own error
+    # engines can override if it's convenient for their own errorau
     # handling. 
     def auto_rescue_exceptions
       [TimeoutError, HTTPClient::TimeoutError, 

data/app/search_engines/bento_search/ebsco_host_engine.rb

@@ -28,6 +28,8 @@ require 'httpclient'
 #                         one or both of pubyear_start and pubyear_end
 #                         #to_i will be called on it, so can be string. 
 #                         .search(:query => "foo", :pubyear_start => 2000)
+# [:databases]            List of licensed EBSCO dbs to search, can override
+#                         list set in config databases, just for this search. 
 # 
 # == Custom response data
 # 
@@ -103,8 +105,18 @@ require 'httpclient'
 class BentoSearch::EbscoHostEngine
   include BentoSearch::SearchEngine
   
-  extend HTTPClientPatch::IncludeClient
-  include_http_client
+  # Can't change http timeout in config, because we keep an http
+  # client at class-wide level, and config is not class-wide. 
+  # Change this 'constant' if you want to change it, I guess.
+  #
+  # In some tests we did, 5.2s was 95th percentile slowest, but in
+  # actual percentage 5.2s is still timing out way too many requests,
+  # let's try 6.3, why not. 
+  HttpTimeout = 6.3   
+  extend HTTPClientPatch::IncludeClient  
+  include_http_client do |client|
+    client.connect_timeout = client.send_timeout = client.receive_timeout = HttpTimeout
+  end
   
   # Include some rails helpers, text_helper.trucate
   def text_helper
@@ -117,7 +129,7 @@ class BentoSearch::EbscoHostEngine
   
   def search_implementation(args)
     url = query_url(args)
-    
+        
     results = BentoSearch::Results.new
     xml, response, exception = nil, nil, nil
 
@@ -162,6 +174,34 @@ class BentoSearch::EbscoHostEngine
     
   end
   
+  # Method to get a single record by "identifier" string, which is really
+  # a combined "db:id" string, same string that would be returned by
+  # an individual item.identifier
+  #
+  # Returns an individual BentoSearch::Result, or raises an exception.
+  # Can raise BentoSearch::NotFound, BentoSearch::TooManyFound, or 
+  # any other weird random exception caused by problems fetching (network
+  # error etc. Is it bad that we don't wrap these in an expected single
+  # exception type? Should we?)
+  def get(id)
+    # split on first colon only. 
+    id =~ /^([^:]+)\:(.*)$/
+    db = $1 ; an = $2
+    
+    raise ArgumentError.new("EbscoHostEngine#get requires an id with a colon, like `a9h:12345`. Instead, we got #{id}") unless db && an
+    
+    # "AN" search_field is not listed in our search_field_definitions,
+    # but it is an internal EBSCOHost search index on 'accession number'
+    
+    results = search(an, :search_field => "AN", :databases => [db])
+    
+    raise (results.error[:exception] || Exception.new) if results.failed?
+    raise BentoSearch::NotFound.new("For id: #{id}") if results.length == 0
+    raise BentoSearch::TooManyFound.new("For id: #{id}") if results.length > 1
+    
+    return results.first
+  end
+  
   # pass in nokogiri record xml for the records/rec node. 
   # Returns nil if NO fulltext is avail on ebsco platform, 
   # non-nil if fulltext is available. Non-nil value will
@@ -351,8 +391,8 @@ class BentoSearch::EbscoHostEngine
     url += "&sort=#{ sort_definitions[args[:sort]][:implementation]}"
     
     # Contrary to docs, don't pass these comma-seperated, pass em in seperate
-    # query params. 
-    configuration.databases.each do |db|
+    # query params. args databases overrides config databases.     
+    (args[:databases] || configuration.databases).each do |db|
       url += "&db=#{db}"
     end    
 
@@ -361,11 +401,19 @@ class BentoSearch::EbscoHostEngine
   
   # pass in a nokogiri representing an EBSCO <rec> result,
   # we'll turn it into a BentoSearch::ResultItem. 
-  def item_from_xml(xml_rec)        
+  def item_from_xml(xml_rec)                
     info = xml_rec.at_xpath("./header/controlInfo")
     
     item = BentoSearch::ResultItem.new
     
+    # Get unique id. Think we need both the database code and accession
+    # number combined, accession numbers not neccesarily unique accross
+    # dbs. We'll combine with a colon. 
+    db                  = text_if_present xml_rec.at_xpath("./header/@shortDbName")
+    accession           = text_if_present xml_rec.at_xpath("./header/@uiTerm")    
+    item.unique_id             = "#{db}:#{accession}" if db && accession
+    
+    
     item.link           = get_link(xml_rec)
 
     item.issn           = text_if_present info.at_xpath("./jinfo/issn")