bento_search 0.5.0 → 0.6.0

data/README.md

@@ -13,7 +13,7 @@ Rails3 and tested only under ruby 1.9.3.
 * It is focused on use cases for academic libraries, but may be useful in generic
 cases too. Initially, engine adapters are planned to be provided for: 
 Google Books, Scopus, SerialSolutions Summon, Ex Libris Primo, 
-EBSCO Discovery Service, and EBSCO traditional 'EIT' api. Most
+EBSCO Discovery Service, EBSCO traditional 'EIT' api, Google Site Search.  Most
 of these search engines require a vendor license to use. 
 
 * bento_search could be considered building blocks for a type of 'federated
@@ -42,6 +42,7 @@ BentoSearch::SearchEngine. http://rubydoc.info/gems/bento_search/frames/
 
 An example app using BentoSearch and showing it's features is
 available at http://github.com/jrochkind/sample_megasearch
+There is a short screencast showing that sample app in action here: http://screencast.com/t/JLS0lclrBZU
 
 ## Usage Examples
 
@@ -104,8 +105,8 @@ field type names:
 This will raise if an engine doesn't support that semantic search field. 
 You can find out what fields a particular engine supports.
 
-    BentoSearch::GoogleBooksEngine.search_keys # => internal keys
-    BentoSearch::GoogleBooksEngine.semantic_search_keys 
+    google_books_engine.search_keys # => internal keys
+    google_books_engine.semantic_search_keys 
 
 You can also provide all arguments in a single hash when it's convenient
 to do so:
@@ -116,9 +117,9 @@ to do so:
 
 An engine advertises what sort types it supports:
 
-    BentoSearch::GoogleBooksEngine.sort_definitions
+    google_books_engine.sort_keys
    
-That returns a hash, where the keys are sort identifiers, where possible
+An array of sort identifiers, where possible
 chosen from a standard list of semantics. (See list in config/i18n/en.yml,
 bento_search.sort_keys). 
 

data/app/assets/javascripts/bento_search/ajax_load.js

@@ -1,22 +1,48 @@
+var BentoSearch = BentoSearch || {}
+
+// Pass in a DOM node that has a data-ajax-url attribute. 
+// Will AJAX load bento search results inside that node.
+// optional second arg success callback function. 
+BentoSearch.ajax_load = function(node, success_callback) {
+  div = $(node);
+  
+  if (div.length == 0) {
+    //we've got nothing
+    return
+  }
+  
+
+  // We find the "waiting"/spinner section already rendered,
+  // and show it. We experimented with generating the spinner/waiting
+  // purely in JS, instead of rendering a hidden one server-side. But
+  // it was too weird and unreliable to do that, sorry.   
+  div.find(".bento_search_ajax_loading").show();
+  
+  
+  // Now load the actual external content from html5 data-bento-ajax-url
+  $.ajax({
+      url: div.data("bentoAjaxUrl"), 
+      success: function(response, status, xhr) {        
+        if (success_callback) {
+           success_callback.apply(div, response);
+        }
+        div.replaceWith(response);          
+      },
+      error: function(xhr, status, errorThrown) {
+        var msg = "Sorry but there was an error: ";
+        div.html(msg + xhr.status + " " + xhr.statusText + ", " + status);
+      }
+  });
+ 
+  
+}
+
 jQuery(document).ready(function($) {
     //Intentionally wait for window.load, not just onready, to
     //prevent interfering with rest of page load. 
     $(window).bind("load", function() {   
-      $(".bento_search_ajax_wait").each(function(i, div) {
-         div = $(div);
-         // from html5 data-bento-ajax-url
-         $.ajax({
-           url: div.data("bentoAjaxUrl"), 
-           success: function(response, status, xhr) {
-            div.replaceWith(response);   
-           },
-           error: function(xhr, status, errorThrown) {
-             var msg = "Sorry but there was an error: ";
-             div.html(msg + xhr.status + " " + xhr.statusText + ", " + status);
-           }
-         });
-                              
+        $("*[data-bento-search-load=ajax_auto]").each(function(i, div) {
+            BentoSearch.ajax_load(div);                              
       });
-    });
-    
+    });    
 });

data/app/assets/stylesheets/bento_search/suggested_styles.css

@@ -20,3 +20,12 @@
   margin: 2em;
 }
 
+/* we put title in an h4, but if it's a link too, it
+   doesn't really need to be bold, link style is already
+   visible enough. */ 
+.bento_item_title a {
+  font-weight: normal;
+}
+.bento_item_title a .bento_search_highlight {
+    font-style: inherit;
+}

data/app/controllers/bento_search/search_controller.rb

@@ -40,25 +40,34 @@ module BentoSearch
       
     # returns partial HTML results, suitable for
     # AJAX to insert into DOM. 
-    # arguments for engine.search are taken from URI request params.
-    # (TODO: Is this a security issue, do we need to whitelist em? )
-    def search                  
-      engine = BentoSearch.get_engine(params[:engine_id])
+    # arguments for engine.search are taken from URI request params, whitelisted
+    def search           
+      engine  =  BentoSearch.get_engine(params[:engine_id])
+      # put it in an iVar mainly for testing purposes. 
+      @engine = engine
 
       
       unless engine.configuration.allow_routable_results == true
         raise AccessDenied.new("engine needs to be registered with :allow_routable_results => true")
       end
 
-      @results = engine.search(params.to_hash.symbolize_keys)
+      @results         = engine.search safe_search_args(engine, params)
+      # template name of a partial with 'yield' to use to wrap the results
+      @partial_wrapper = @results.display_configuration.lookup!("ajax.wrapper_template")
       
-      render :layout => false # partial HTML results     
+      # partial HTML results
+      render "bento_search/search/search", :layout => false 
+
     end
     
 
     
     protected 
     
+    def safe_search_args(engine, params)
+      params.to_hash.symbolize_keys.slice( *engine.public_settable_search_args )       
+    end
+    
     def deny_access(exception)
       render :text => exception.message, :status => 403
     end

data/app/helpers/bento_search_helper.rb

@@ -40,13 +40,26 @@ module BentoSearchHelper
       
     end
 
-    if (!results && load_mode == :ajax_auto)
+    if (!results && [:ajax_auto, :ajax_triggered].include?(load_mode))
       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"
+      content_tag(:div,
+        :class => "bento_search_ajax_wait",
+        :"data-bento-search-load" => load_mode.to_s, 
+        :"data-bento-ajax-url"    => to_bento_search_url( {:engine_id => engine.configuration.id}.merge(options) )) do
+      
+      # An initially hidden div with loading msg/spinner that will be shown
+      # by js on ajax load
+      content_tag("noscript") do
+        I18n.t("bento_search.ajax_noscript")
+      end +
+      content_tag(:div, 
+        :class => "bento_search_ajax_loading", 
+        :style => "display:none") do
+      
+          image_tag("bento_search/large_loader.gif", 
+            :alt => I18n.translate("bento_search.ajax_loading"),            
+          ) 
+
         end
       end
     else
@@ -55,7 +68,7 @@ module BentoSearchHelper
       if results.failed?
         render :partial => "bento_search/search_error", :locals => {:results => results}
       elsif results.length > 0      
-        render :partial => "bento_search/std_item", :collection => results
+        render :partial => "bento_search/std_item", :collection => results, :as => :item
       else
         content_tag(:div, :class=> "bento_search_no_results") do
           I18n.translate("bento_search.no_results")
@@ -126,10 +139,13 @@ module BentoSearchHelper
   # 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.*
+  #
+  # If no i18n is found, titleized version of key itself is used as somewhat
+  # reasonable default. 
   def bento_sort_hash_for(engine)
     Hash[ 
       engine.sort_definitions.keys.collect do |key|
-        [I18n.translate(key, :scope => "bento_search.sort_keys"), key]
+        [I18n.translate(key.to_s, :scope => "bento_search.sort_keys", :default => key.to_s.titleize), key.to_s]
       end        
     ]    
   end

data/app/item_decorators/bento_search/no_links.rb

@@ -0,0 +1,13 @@
+# An item decorator that just erases all links, main link and other
+# links. 
+module BentoSearch::NoLinks
+  
+  def link
+    nil
+  end
+  
+  def other_links
+    []
+  end
+
+end

data/app/models/bento_search/openurl_creator.rb

@@ -16,6 +16,8 @@ module BentoSearch
   # In some cases nil can be returned, if no reasonable OpenURL can
   # be created from the ResultItem. 
   class OpenurlCreator
+    include ActionView::Helpers::SanitizeHelper # for strip_tags
+    
     attr_accessor :result_item
     
     def initialize(ri)
@@ -42,9 +44,9 @@ module BentoSearch
       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))
+        r.set_metadata("aufirst", ensure_no_tags(result_item.authors.first.first))
+        r.set_metadata("aulast", ensure_no_tags(result_item.authors.first.last))
+        r.set_metadata("au", result_item.author_display(ensure_no_tags result_item.authors.first))
       end
 
       r.set_metadata("date",    result_item.year.to_s)
@@ -52,18 +54,18 @@ module BentoSearch
       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("jtitle",  ensure_no_tags(result_item.source_title))
       r.set_metadata("issn",    result_item.issn)
       r.set_metadata("isbn",    result_item.isbn)
-      r.set_metadata("pub",     result_item.publisher)
+      r.set_metadata("pub",     ensure_no_tags(result_item.publisher))
       
       case result_item.format
       when "Book"
-        r.set_metadata("btitle", result_item.complete_title)
+        r.set_metadata("btitle", ensure_no_tags(result_item.complete_title))
       when "Article", :conference_paper
-        r.set_metadata("atitle", result_item.complete_title)
+        r.set_metadata("atitle", ensure_no_tags(result_item.complete_title))
       else
-        r.set_metadata("title", result_item.complete_title)
+        r.set_metadata("title", ensure_no_tags(result_item.complete_title))
       end
       
       return context_object
@@ -124,5 +126,13 @@ module BentoSearch
     end
     
     
+    # If the input is not marked html_safe?, just return it. Otherwise
+    # strip html tags from it.
+    def ensure_no_tags(str)
+      return str unless str.html_safe?
+      
+      strip_tags(str)      
+    end
+    
   end
 end

data/app/models/bento_search/registrar.rb

@@ -57,12 +57,8 @@ class BentoSearch::Registrar
   # Turn a string into a constant/class object, lexical lookup
   # within BentoSearch module. Can use whatever would be legal
   # in ruby, "A", "A::B", "::A::B" (force top-level lookup), etc. 
-  def constantize(klass_string)        
-    unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ klass_string
-      raise NameError, "#{klass_string.inspect} is not a valid constant name!"
-    end
-
-    BentoSearch.module_eval(klass_string, __FILE__, __LINE__)
+  def constantize(klass_string)     
+    BentoSearch::Util.constantize(klass_string)    
   end
   
 

data/app/models/bento_search/result_item.rb

@@ -1,3 +1,5 @@
+require 'language_list'
+
 module BentoSearch
   # Data object representing a single hit from a search, normalized
   # with common data fields. Usually held in a BentoSearch::Results object.
@@ -24,6 +26,10 @@ module BentoSearch
       self.custom_data ||= {}
     end
     
+    # If set to true, item will refuse to generate an openurl,
+    # returning nil from #to_openurl or #openurl_kev
+    attr_accessor :openurl_disabled 
+    
     # Array (possibly empty) of BentoSearch::Link objects
     # representing additional links. Often SearchEngine's themselves
     # won't include any of these, but Decorators will be used
@@ -81,6 +87,29 @@ module BentoSearch
     # format. 
     attr_accessor :format_str
     
+    # Language of materials. Producer can set language_code to an ISO 639-1 (two
+    # letter) or 639-3 (three letter) language code. If you do this, you don't
+    # need to set language_str, it'll be automatically looked up. (Providing
+    # language name in English at present, i18n later maybe). 
+    #
+    # Or, if you don't know the language code (or there isn't one?), you can set 
+    # language_str manually to a presumably english user-displayable string.
+    # Manually set language_str will over-ride display string calculated from
+    # language_code. 
+    # 
+    # Consumers can look at language_code or language_str regardless (although
+    # either or both may be nil). You can use language_list gem to normalize to a 
+    # 2- or 3-letter from language_code that could be either. 
+    attr_accessor :language_code
+    attr_writer :language_str
+    def language_str
+      @language_str || language_code.try do |code|
+        LanguageList::LanguageInfo.find(code).try do |lang_obj|
+          lang_obj.name
+        end
+      end
+    end
+    
     # year published. a ruby int
     # PART of:. 
     # * schema.org CreativeWork "datePublished", year portion
@@ -93,9 +122,18 @@ module BentoSearch
     attr_accessor :start_page
     attr_accessor :end_page
     
-    attr_accessor :journal_title
+    # source_title is often used for journal_title (and aliased
+    # as #journal_title, although that may go away), but can
+    # also be used for other 'container' titles. Book title for
+    # a book chapter. Even web site or URL for a web page. 
+    attr_accessor :source_title
+    alias_method :journal_title, :source_title
+    alias_method :'journal_title=',  :'source_title='
+    
+    
     attr_accessor :issn
     attr_accessor :isbn
+    attr_accessor :oclcnum # OCLC accession number, WorldCat. 
     
     attr_accessor :doi
     
@@ -125,6 +163,8 @@ module BentoSearch
     
     # Returns a ruby OpenURL::ContextObject (NISO Z39.88).     
     def to_openurl
+      return nil if openurl_disabled
+      
       BentoSearch::OpenurlCreator.new(self).to_openurl
     end
     
@@ -180,9 +220,9 @@ module BentoSearch
         result_elements.push "<span class='year'>#{year}</span>"
       end
       
-      result_elements.push(journal_title) unless journal_title.blank?      
+      result_elements.push(source_title) unless source_title.blank?      
       
-      if journal_title.blank? && ! publisher.blank?
+      if source_title.blank? && ! publisher.blank?
         result_elements.push html_escape publisher
       end
       

data/app/models/bento_search/results.rb

@@ -11,6 +11,10 @@ module BentoSearch
     attr_accessor :start
     # per_page setting, can be used for pagination. 
     attr_accessor :per_page
+    
+    # simply copied over from search engine configuration :display key,
+    # useful for making config available at display time in a DRY way. 
+    attr_accessor :display_configuration
 
     # If error is non-nil, it's an error condition with no real results.
     # error should be a hash with these (and possibly other) keys, although

data/app/models/bento_search/search_engine.rb

@@ -50,7 +50,8 @@ module BentoSearch
   # framework:
   #
   #  [item_decorators]
-  #      Array of Modules that will be decorated on to each individual search
+  #      Array of Modules (or strings specifying modules, helpful to keep
+  #      config serializable) that will be decorated on to each individual search
   #      BentoSearch::ResultItem. These can be used to, via configuration, change
   #      the links associated with items, change certain item behaviors, or massage
   #      item metadata. (Needs more documentation). 
@@ -125,6 +126,14 @@ module BentoSearch
     # handles configuration loading, mostly. Argument is a
     # Confstruct::Configuration or Hash. 
     def initialize(aConfiguration = Confstruct::Configuration.new)
+      # To work around weird confstruct bug, we need to change
+      # a hash to a Confstruct ourselves. 
+      # https://github.com/mbklein/confstruct/issues/14
+      unless aConfiguration.kind_of? Confstruct::Configuration
+        aConfiguration = Confstruct::Configuration.new aConfiguration
+      end
+        
+      
       # init, from copy of default, or new      
       if self.class.default_configuration
         self.configuration = Confstruct::Configuration.new(self.class.default_configuration)
@@ -136,6 +145,7 @@ module BentoSearch
       
       # global defaults?
       self.configuration[:item_decorators] ||= []
+      self.configuration[:for_display] ||= {}
             
       # check for required keys -- have to be present, and not nil
       if self.class.required_configuration
@@ -208,6 +218,8 @@ module BentoSearch
       results.engine_id     = configuration.id
       
       results.timing = (Time.now - start_t)
+            
+      results.display_configuration = configuration.for_display
         
       return results
     rescue *auto_rescue_exceptions => e
@@ -303,15 +315,26 @@ module BentoSearch
     alias_method :parse_search_arguments, :normalized_search_arguments
     
     
-    
+    # Used mainly/only by the AJAX results loading. 
+    # an array WHITELIST of attributes that can be sent as non-verified
+    # request params and used to execute a search. For instance, 'auth' is
+    # NOT on there, you can't trust a web request as to 'auth' status. 
+    # individual engines may over-ride, call super, and add additional
+    # engine-specific attributes. 
+    def public_settable_search_args
+      [:query, :search_field, :semantic_search_field, :sort, :page, :start, :per_page]
+    end
    
     
     protected
     
     # Extend each result with each specified decorator module
+    # configuration.item_decorators is an array of either Module constants,
+    # or strings specifying module constants. 
     def decorate(results)      
       results.each do |result|
         configuration.item_decorators.each do |decorator|
+          decorator = (decorator.kind_of? Module) ? decorator : BentoSearch::Util.constantize(decorator)          
           result.extend decorator
         end
       end
@@ -337,27 +360,6 @@ module BentoSearch
     
     module ClassMethods
       
-      # If support fielded search, over-ride to specify fields
-      # supported. Returns a hash, key is engine-specific internal
-      # search field, value is nil or a hash of metadata about
-      # the search field, including semantic mapping. 
-      #
-      # def search_field_definitions
-      #  { "intitle" => {:semantic => :title}}
-      # end
-      def search_field_definitions
-        {}
-      end
-      
-            
-      # Returns list of string internal search_field's that can
-      # be supplied to search(:search_field => x)
-      def search_keys        
-        return search_field_definitions.keys
-      end
-      
-      
-      
       # Over-ride returning a hash or Confstruct with 
       # any configuration values you want by default. 
       # actual user-specified config values will be deep-merged