blacklight 3.0pre1

data/blacklight.gemspec

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+require "lib/blacklight/version"
+
+Gem::Specification.new do |s|
+  s.name        = "blacklight"
+  s.version     = Blacklight::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["jrochkind", "Matt Mitchell", "Chris Beer", "Jessie Keck", "Jason Ronallo", "Vernon Chapman", "Marck A. Matienzo"]
+  s.email       = ["blacklight-development@googlegroups.com"]
+  s.homepage    = "http://projectblacklight.org/"
+  s.summary     = "A next-geration Library Catalag for Universities"
+  s.description = %q{Blacklight is a free and open source ruby-on-rails based discovery interface (a.k.a. “next-generation catalog”) especially optimized for heterogeneous collections. You can use it as a library catalog, as a front end for a digital repository, or as a single-search interface to aggregate digital content that would otherwise be siloed.}
+  
+  s.rubyforge_project = "blacklight"
+  
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # PRODUCTION GEM REQUIREMENTS
+  # ---------------------------------------    
+  # JRuby Specific Gems - and their counterparts
+  if defined?(JRUBY_VERSION)
+    # Jruby specific gems should go here.
+  else
+    s.add_dependency "unicode" # provides C-form normalization of unicode characters, as required by refworks.
+  end  
+
+  # Required Gems
+  s.add_dependency "rails", "= 3.0.6"
+  s.add_dependency "nokogiri", "~>1.5.0.beta.3"   # XML Parser
+  s.add_dependency "marc"  # Marc record parser
+  s.add_dependency "rsolr",  '1.0.0' # Library for interacting with rSolr.
+  s.add_dependency "rsolr-ext", '1.0.0' # extension to the above for some rails-ish behaviors - currently imbeded in our solr document ojbect.
+  s.add_dependency "will_paginate", "3.0.pre2" # the pagination (page 1,2,3, etc..) of our search results
+
+
+  # TESTING GEM REQUIREMENTS
+  # -------------------------------------------
+  # For testing the generators
+#  s.add_dependency "cucumber-rails"
+#  s.add_dependency "capybara"
+#  s.add_dependency "aruba"
+
+#  s.add_dependency "rspec-rails", "~>2.3.0"
+#  s.add_dependency "webrat"
+#  s.add_dependency "database_cleaner"
+
+end

data/config.ru

@@ -0,0 +1,4 @@
+# This file is used by Rack-based servers to start the application.
+
+require ::File.expand_path('../config/environment',  __FILE__)
+run BlacklightApp::Application

data/config/routes.rb

@@ -0,0 +1,54 @@
+Rails.application.routes.draw do
+  
+  # Root context
+  root :to => "catalog#index"
+
+  # A Note on User Sessions:
+  # Blacklight expects the following named routes or at least the associated path helper methods to be defined.
+  # new_user_session   (for logging in) - pages that require a log in will redirect users here.
+  # destroy_user_session (for logging out)
+
+  
+  # Bookmarks 
+  match "bookmarks/clear", :to => "bookmarks#clear", :as => "clear_bookmarks"
+  resources :bookmarks
+  
+  # Folder Paths
+  match "folder/clear", :to => "folder#clear", :as => "clear_folder"
+  match "folder/destroy", :to => "folder#destroy"
+  resources :folder, :only => [:index, :update, :destroy] 
+  
+  # Search History
+  match "search_history",             :to => "search_history#index",   :as => "search_history"
+  match "search_history/clear",       :to => "search_history#clear",   :as => "clear_search_history"
+  match "search_history/destroy/:id", :to => "search_history#destroy", :as => "delete_search"
+
+  # Saved Searches
+  match "saved_searches/clear",       :to => "saved_searches#clear",   :as => "clear_saved_searches"
+  match "saved_searches/index",       :to => "saved_searches#index",   :as => "saved_searches"
+  match "saved_searches/save/:id",    :to => "saved_searches#save",    :as => "save_search"
+  match "saved_searches/forget/:id",  :to => "saved_searches#forget",  :as => "forget_search"
+  
+  # Catalog stuff.
+  match 'catalog/map', :as => "map_catalog"
+  match 'catalog/opensearch', :as => "opensearch_catalog"
+  match 'catalog/citation', :as => "citation_catalog"
+  match 'catalog/email', :as => "email_catalog"
+  match 'catalog/sms', :as => "sms_catalog"
+  match 'catalog/endnote', :as => "endnote_catalog"
+  match 'catalog/send_email_record', :as => "send_email_record_catalog"
+  match "catalog/facet/:id", :to => 'catalog#facet', :as => 'catalog_facet'
+  match 'catalog/unapi', :to => "catalog#unapi", :as => 'unapi'
+  resources :catalog, :only => [:index, :show, :update]
+  match 'catalog/:id/image', :to => "catalog#image"
+  match 'catalog/:id/status', :to => "catalog#status"
+  match 'catalog/:id/availability', :to => "catalog#availability"
+  match 'catalog/:id/librarian_view', :to => "catalog#librarian_view", :as => "librarian_view_catalog"
+
+  
+  # Feedback
+  match "feedback", :to => "feedback#show"    
+  match "feedback/complete", :to => "feedback#complete"
+  
+end
+

data/db/seeds.rb

@@ -0,0 +1,7 @@
+# This file should contain all the record creation needed to seed the database with its default values.
+# The data can then be loaded with the rake db:seed (or created alongside the db with db:setup).
+#
+# Examples:
+#
+#   cities = City.create([{ :name => 'Chicago' }, { :name => 'Copenhagen' }])
+#   Mayor.create(:name => 'Daley', :city => cities.first)

data/features/generators.feature

@@ -0,0 +1,77 @@
+Feature:
+  In order to easily add Blacklight fucntionality to a new rails app
+  As a user of Rails3 and Blacklight
+  I would like to use the blacklight generator.
+
+  Scenario: The Blacklight generators create all the correct files and file modifications when executed with defaults
+    When I run "rails new test_app"
+    And I cd to "test_app"
+    And a file named "Gemfile" with:
+    """
+    source "http://rubygems.org"
+    gem 'rails', '>=3.0.4'
+    gem 'sqlite3-ruby', :require => 'sqlite3'
+    gem 'blacklight', :path => '../../../'
+    """  
+    And I run "bundle install --local"
+
+    When I write to "app/models/user.rb" with:
+    """
+    class User < ActiveRecord::Base
+    end
+    """
+    And I run "rails generate blacklight"
+    Then the following files should exist:
+       | config/initializers/blacklight_config.rb         |
+       | config/solr.yml                                  |
+       | public/images/blacklight/bg.png                  |
+       | public/javascripts/blacklight.js                 |
+       | public/javascripts/jquery-1.4.2.min.js           |
+       | public/javascripts/jquery-ui-1.8.1.custom.min.js |
+       | public/stylesheets/blacklight.css                |
+       | public/stylesheets/yui.css                       | 
+    And a directory named "public/stylesheets/jquery" should exist
+    And the file "app/models/user.rb" should contain "is_blacklight_user"
+    
+    # Devise should next exist in thie scenerio
+    And a directory named "app/views/devise" should not exist
+    And the file "app/models/user.rb" should not contain "devise"
+
+
+  @really_slow_process
+  Scenario: The Blacklight generator installs devise when given the -d option
+    When I run "rails new test_app"
+    And I cd to "test_app"
+    And a file named "Gemfile" with:
+    """
+    source "http://rubygems.org"
+    gem 'rails', '>=3.0.4'
+    gem 'sqlite3-ruby', :require => 'sqlite3'
+    gem 'blacklight', :path => '../../../'
+
+    # For testing
+    gem 'rspec-rails'	
+    gem 'cucumber-rails'
+    gem 'webrat'    # still needed for rspec view tests
+    gem 'capybara'  # used by latest cucumber
+
+    """  
+    And I run "bundle install --local"
+
+    Then the file "app/models/user.rb" should not exist
+    And I run "rails generate blacklight -d"    
+
+    # Devise should now be installed.
+    Then a file named "app/models/user.rb" should exist
+    Then a directory named "app/views/devise" should exist
+    Then the file "app/models/user.rb" should contain "devise"
+    
+    # And the user model should be setup with Blacklight
+    And the file "app/models/user.rb" should contain "is_blacklight_user"
+
+    # And I copy over the rspec and feature tests, just in case I want to test them.
+    And I run "cp -r ../../../test_app/spec ."
+    And I run "cp -r ../../../test_app/features ."
+    And I run "cp    ../../../test_app/Rakefile ."
+    And I run "cp -r ../../../test_app/jetty ."
+ 

data/features/support/aruba.rb

@@ -0,0 +1,9 @@
+require 'aruba/cucumber'
+
+Before do
+    @aruba_timeout_seconds = 30
+end
+
+Before ('@really_slow_process') do
+    @aruba_timeout_seconds = 30
+end

data/install/solr.yml

@@ -0,0 +1,8 @@
+production:
+    url: http://127.0.0.1:8983/solr
+development:
+    url: http://127.0.0.1:8983/solr
+test: &TEST
+    url: http://127.0.0.1:8983/solr
+cucumber:
+    <<: *TEST

data/lib/blacklight.rb

@@ -0,0 +1,121 @@
+require 'will_paginate'
+require 'marc'
+require 'rsolr'
+require 'rsolr-ext'
+
+module Blacklight
+
+  autoload :Configurable, 'blacklight/configurable'
+  autoload :SearchFields, 'blacklight/search_fields'
+
+  autoload :Solr, 'blacklight/solr'
+  autoload :Marc, 'blacklight/marc'
+  
+  autoload :SolrHelper, 'blacklight/solr_helper'
+  
+  autoload :Exceptions, 'blacklight/exceptions'
+
+  autoload :User, 'blacklight/user'
+
+  autoload :CommaLinkRenderer, 'blacklight/comma_link_renderer'
+
+  autoload :Controller, 'blacklight/controller'
+  autoload :Catalog,    'blacklight/catalog'
+
+  extend Configurable
+  extend SearchFields
+  
+  require 'blacklight/engine' if defined?(Rails)
+  
+  class << self
+    attr_accessor :solr, :solr_config
+  end
+  
+  # Just returning a string for the Blacklight version number.
+  # I've just put master here now, should it say when it's running under master?  (Master?)
+  # We need to find a better way of increasing this number automatically during releases, but this is a good way for now.
+  def self.version
+    "2.8.0"
+  end
+
+  # Adding a little jruby support
+  def self.jruby?
+    defined?(RUBY_ENGINE) && RUBY_ENGINE == "jruby" 
+  end
+
+  def self.solr_file
+    "#{::Rails.root.to_s}/config/solr.yml"
+  end
+  
+  def self.init
+    SolrDocument.connection = Blacklight.solr
+    logger.info("BLACKLIGHT: running version #{Blacklight.version}")
+    logger.info("BLACKLIGHT: initialized with Blacklight.solr_config: #{Blacklight.solr_config.inspect}")
+    logger.info("BLACKLIGHT: initialized with Blacklight.solr: #{Blacklight.solr.inspect}")
+    logger.info("BLACKLIGHT: initialized with Blacklight.config: #{Blacklight.config.inspect}")
+  end
+
+  def self.solr
+    @solr ||=  RSolr::Ext.connect(Blacklight.solr_config)
+  end
+
+  def self.solr_config
+    @solr_config ||= begin
+        raise "You are missing a solr configuration file: #{solr_file}. Have you run \"rails generate blacklight\"?" unless File.exists?(solr_file) 
+        solr_config = YAML::load(File.open(solr_file))
+        raise "The #{RAILS_ENV} environment settings were not found in the solr.yml config" unless solr_config[RAILS_ENV]
+        solr_config[RAILS_ENV].symbolize_keys
+      end
+  end
+
+  def self.logger
+    ::Rails.logger
+  end
+
+  #############  
+  # Methods for figuring out path to BL plugin, and then locate various files
+  # either in the app itself or defaults in the plugin -- whether you are running
+  # from the plugin itself or from an actual app using te plugin.
+  # In a seperate module so it can be used by both Blacklight class, and
+  # by rake tasks without loading the whole Rails environment. 
+  #############
+  
+  # returns the full path the the blacklight plugin installation
+  def self.root
+    @root ||= File.expand_path(File.dirname(File.dirname(__FILE__)))
+  end
+
+  # This is useful for modifying Blacklight models.
+  # In the main app you can then do this:
+  # require "#{MyEngine.models_dir}/bookmark"
+  # class Bookmark
+  # ...
+  # end
+  # BE AWARE - When you do this, you are monkey patching Blacklight
+  # we should eventually find a better way - such as the acts_as pattern
+  def self.models_dir
+    "#{root}/app/models"
+  end
+  
+  def self.controllers_dir
+    "#{root}/app/controllers"
+  end
+
+  
+  # Searches Rails.root then Blacklight.root for a valid path
+  # returns a full path if a valid path is found
+  # returns nil if nothing is found.
+  # First looks in Rails.root, then Blacklight.root
+  #
+  # Example:
+  # full_path_to_solr_marc_jar = Blacklight.locate_path 'solr_marc', 'SolrMarc.jar'
+  
+  def self.locate_path(*subpath_fragments)
+    subpath = subpath_fragments.join('/')
+    base_match = [Rails.root, self.root].find do |base|
+      File.exists? File.join(base, subpath)
+    end
+    File.join(base_match.to_s, subpath) if base_match
+  end
+  
+end

data/lib/blacklight/catalog.rb

@@ -0,0 +1,311 @@
+module Blacklight::Catalog 
+
+  # The following code is executed when someone includes blacklight::catalog in their
+  # own controller.
+  def self.included(base)
+    # These two helper methods are provided by the blacklight solr::helper
+    base.send :helper_method, :facet_limit_hash
+    base.send :helper_method, :facet_limit_for
+
+    base.send :before_filter, :search_session, :history_session
+    base.send :before_filter, :delete_or_assign_search_session_params, :only => :index
+    base.send :after_filter, :set_additional_search_session_values, :only=>:index
+
+    # Whenever an action raises SolrHelper::InvalidSolrID, this block gets executed.
+    # Hint: the SolrHelper #get_solr_response_for_doc_id method raises this error,
+    # which is used in the #show action here.
+    base.send :rescue_from, Blacklight::Exceptions::InvalidSolrID, :with => :invalid_solr_id_error
+    # When RSolr::RequestError is raised, the rsolr_request_error method is executed.
+    # The index action will more than likely throw this one.
+    # Example, when the standard query parser is used, and a user submits a "bad" query.
+    base.send :rescue_from, RSolr::Error::Http, :with => :rsolr_request_error
+  end
+  
+
+    # get search results from the solr index
+    def index
+      
+      delete_or_assign_search_session_params
+      
+      extra_head_content << view_context.auto_discovery_link_tag(:rss, url_for(params.merge(:format => 'rss')), :title => "RSS for results")
+      extra_head_content << view_context.auto_discovery_link_tag(:atom, url_for(params.merge(:format => 'atom')), :title => "Atom for results")
+      extra_head_content << view_context.auto_discovery_link_tag(:unapi, unapi_url, {:type => 'application/xml',  :rel => 'unapi-server', :title => 'unAPI' })
+      
+      (@response, @document_list) = get_search_results
+      @filters = params[:f] || []
+      search_session[:total] = @response.total unless @response.nil?
+      
+      respond_to do |format|
+        format.html { save_current_search_params }
+        format.rss  { render :layout => false }
+        format.atom { render :layout => false }
+      end
+    end
+    
+    # get single document from the solr index
+    def show
+      extra_head_content << view_context.auto_discovery_link_tag(:unapi, unapi_url, {:type => 'application/xml',  :rel => 'unapi-server', :title => 'unAPI' })
+      @response, @document = get_solr_response_for_doc_id    
+
+      respond_to do |format|
+        format.html {setup_next_and_previous_documents}
+
+        # Add all dynamically added (such as by document extensions)
+        # export formats.
+        @document.export_formats.each_key do | format_name |
+          # It's important that the argument to send be a symbol;
+          # if it's a string, it makes Rails unhappy for unclear reasons. 
+          format.send(format_name.to_sym) { render :text => @document.export_as(format_name), :layout => false }
+        end
+        
+      end
+    end
+
+    def unapi
+      @export_formats = Blacklight.config[:unapi] || {}
+      @format = params[:format]
+      if params[:id]
+        @response, @document = get_solr_response_for_doc_id
+        @export_formats = @document.export_formats
+      end
+  
+      unless @format
+        render 'unapi.xml.builder', :layout => false and return
+      end
+  
+      respond_to do |format|
+        format.all do
+          send_data @document.export_as(@format), :type => @document.export_formats[@format][:content_type], :disposition => 'inline' if @document.will_export_as @format
+        end
+      end
+    end
+  
+    
+    # updates the search counter (allows the show view to paginate)
+    def update
+      adjust_for_results_view
+      session[:search][:counter] = params[:counter]
+      redirect_to :action => "show"
+    end
+    
+    # displays values and pagination links for a single facet field
+    def facet
+      @pagination = get_facet_pagination(params[:id], params)
+    end
+    
+    # single document image resource
+    def image
+    end
+    
+    # single document availability status (true/false)
+    def status
+    end
+    
+    # single document availability info
+    def availability
+    end
+    
+    # collection/search UI via Google maps
+    def map
+    end
+    
+    # method to serve up XML OpenSearch description and JSON autocomplete response
+    def opensearch
+      respond_to do |format|
+        format.xml do
+          render :layout => false
+        end
+        format.json do
+          render :json => get_opensearch_response
+        end
+      end
+    end
+    
+    # citation action
+    def citation
+      @response, @documents = get_solr_response_for_field_values("id",params[:id])
+    end
+    # grabs a bunch of documents to export to endnote
+    def endnote
+      @response, @documents = get_solr_response_for_field_values("id",params[:id])
+      respond_to do |format|
+        format.endnote
+      end
+    end
+    
+    # Email Action (this will render the appropriate view on GET requests and process the form and send the email on POST requests)
+    def email
+      @response, @documents = get_solr_response_for_field_values("id",params[:id])
+      if request.post?
+        if params[:to]
+          from = request.host # host w/o port for From address (from address cannot have port#)
+          url_gen_params = {:host => request.host_with_port, :protocol => request.protocol}
+          
+          if params[:to].match(/^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,4}$/)
+            email = RecordMailer.create_email_record(@documents, {:to => params[:to], :message => params[:message]}, from, url_gen_params)
+          else
+            flash[:error] = "You must enter a valid email address"
+          end
+          email.deliver unless flash[:error]
+          redirect_to :back
+        else
+          flash[:error] = "You must enter a recipient in order to send this message"
+        end
+      end
+    end
+    
+    # SMS action (this will render the appropriate view on GET requests and process the form and send the email on POST requests)
+    def sms 
+      @response, @documents = get_solr_response_for_field_values("id",params[:id])
+      if request.post?
+        from = request.host # host w/o port for From address (from address cannot have port#)
+        url_gen_params = {:host => request.host_with_port, :protocol => request.protocol}
+        
+        if params[:to]
+          phone_num = params[:to].gsub(/[^\d]/, '')
+          unless params[:carrier].blank?
+            if phone_num.length != 10
+              flash[:error] = "You must enter a valid 10 digit phone number"
+            else
+              email = RecordMailer.create_sms_record(@documents, {:to => phone_num, :carrier => params[:carrier]}, from, url_gen_params)
+            end
+            email.deliver unless flash[:error]
+            redirect_to :back
+          else
+            flash[:error] = "You must select a carrier"
+          end
+        else
+          flash[:error] = "You must enter a recipient's phone number in order to send this message"
+        end
+        
+      end
+    end
+    
+    # DEPRECATED backwards compatible method that will just redirect to the appropriate action.  It will return a 404 if a bad action is supplied (just in case).
+    def send_email_record
+      warn "[DEPRECATION] CatalogController#send_email_record is deprecated.  Please use the email or sms controller action instead."
+      if ["sms","email"].include?(params[:style])
+        redirect_to :action => params[:style] 
+      else
+        render :file => "#{::Rails.root}/public/404.html", :layout => false, :status => 404
+      end
+    end
+
+    def librarian_view
+      @response, @document = get_solr_response_for_doc_id
+    end
+    
+    
+    protected    
+    #
+    # non-routable methods ->
+    #
+
+    # calls setup_previous_document then setup_next_document.
+    # used in the show action for single view pagination.
+    def setup_next_and_previous_documents
+      setup_previous_document
+      setup_next_document
+    end
+    
+    # gets a document based on its position within a resultset  
+    def setup_document_by_counter(counter)
+      return if counter < 1 || session[:search].blank?
+      search = session[:search] || {}
+      get_single_doc_via_search(counter, search)
+    end
+    
+    def setup_previous_document
+      @previous_document = session[:search][:counter] ? setup_document_by_counter(session[:search][:counter].to_i - 1) : nil
+    end
+    
+    def setup_next_document
+      @next_document = session[:search][:counter] ? setup_document_by_counter(session[:search][:counter].to_i + 1) : nil
+    end
+    
+    # sets up the session[:search] hash if it doesn't already exist
+    def search_session
+      session[:search] ||= {}
+    end
+    
+    # sets up the session[:history] hash if it doesn't already exist.
+    # assigns all Search objects (that match the searches in session[:history]) to a variable @searches.
+    def history_session
+      session[:history] ||= []
+      @searches = searches_from_history # <- in BlacklightController
+    end
+    
+    # This method copies request params to session[:search], omitting certain
+    # known blacklisted params not part of search, omitting keys with blank
+    # values. All keys in session[:search] are as symbols rather than strings. 
+    def delete_or_assign_search_session_params
+      session[:search] = {}
+      params.each_pair do |key, value|
+        session[:search][key.to_sym] = value unless ["commit", "counter"].include?(key.to_s) ||
+          value.blank?
+      end
+    end
+    
+    # Saves the current search (if it does not already exist) as a models/search object
+    # then adds the id of the serach object to session[:history]
+    def save_current_search_params    
+      # If it's got anything other than controller, action, total, we
+      # consider it an actual search to be saved. Can't predict exactly
+      # what the keys for a search will be, due to possible extra plugins. 
+      return if (search_session.keys - [:controller, :action, :total, :counter, :commit ]) == [] 
+      params_copy = search_session.clone # don't think we need a deep copy for this
+      params_copy.delete(:page)
+      unless @searches.collect { |search| search.query_params }.include?(params_copy)
+        new_search = Search.create(:query_params => params_copy)
+        session[:history].unshift(new_search.id)
+      end
+    end
+          
+    # sets some additional search metadata so that the show view can display it.
+    def set_additional_search_session_values
+      unless @response.nil?
+        search_session[:total] = @response.total
+      end
+    end
+    
+    # we need to know if we are viewing the item as part of search results so we know whether to
+    # include certain partials or not
+    def adjust_for_results_view
+      if params[:results_view] == "false"
+        session[:search][:results_view] = false
+      else
+        session[:search][:results_view] = true
+      end
+    end
+    
+       
+    # when solr (RSolr) throws an error (RSolr::RequestError), this method is executed.
+    def rsolr_request_error(exception)
+      if RAILS_ENV == "development"
+        raise exception # Rails own code will catch and give usual Rails error page with stack trace
+      else
+        flash_notice = "Sorry, I don't understand your search."
+        # Set the notice flag if the flash[:notice] is already set to the error that we are setting.
+        # This is intended to stop the redirect loop error
+        notice = flash[:notice] if flash[:notice] == flash_notice
+        unless notice
+          flash[:notice] = flash_notice
+          redirect_to root_path, :status => 500
+        else
+          render :template => "public/500.html", :layout => false, :status => 500
+        end
+      end
+    end
+    
+    # when a request for /catalog/BAD_SOLR_ID is made, this method is executed...
+    def invalid_solr_id_error
+      if RAILS_ENV == "development"
+        render # will give us the stack trace
+      else
+        flash[:notice] = "Sorry, you have requested a record that doesn't exist."
+        redirect_to root_path, :status => 404
+      end
+      
+    end
+  
+end