blacklight 3.0pre1 → 3.0pre2

data/.gitmodules

@@ -1,6 +0,0 @@
-[submodule "test_app/jetty"]
-	path = test_app/jetty
-	url = git://github.com/projectblacklight/blacklight-jetty.git
-[submodule "test_app/data"]
-	path = test_app/data
-	url = git://github.com/projectblacklight/blacklight-data.git

data/README.rdoc

@@ -25,7 +25,18 @@ Install blacklight
 Run your database migrations
 
   $ rake db:migrate
-
+  
+You will need a Solr setup, referred to in your config/solr.yml. You can install
+an example jetty container with Solr, that has Solr configured to work with
+Blacklight's defaults, like:
+  $ rails generate blacklight:jetty
+
+You can also install your own Solr or use an existing install. But Blacklight
+configuration needs to match your Solr setup, and there are certain things
+in a Solr setup that Blacklight requires. To generate some Solr config files
+that match what default Blacklight expects:
+  $ rails generate blacklight:solr_conf path/to/output/directory/
+  
 Start up your application
 
   $ rails server
@@ -48,7 +59,15 @@ If you have a user model already, the Blacklight generator will connect to it au
    match 'new_user_session',          :to => 'Your User Session Controller # Log in action'
    match 'destroy_user_session',      :to => 'Your User Session Controller # Log Out action'
 
-And you will need to make sure the following helper methods are available:
+One blacklight view uses #to_s on your user model to get a user-displayable
+account name/identifier for the currently logged in account, you probably
+want to have such a method. 
+
+(TODO: Instructions on how to tell BL the name of your user model if it's
+not User?)
+
+And you will need to make sure the following methods are available both
+on controllers and as helpers:
 
   current_user   - Which should return a user object that include Blacklight::User
   user_session   - Which should return a user session
@@ -67,99 +86,87 @@ Start up your application
 
 Visit the catalog at:  http://localhost/catalog
 
-== Setting up a development environment
-
-Checkout the code:
-
-  $ git clone git@github.com:projectblacklight/blacklight.git blacklight
-  $ cd blacklight
-
-(While the rails3 branch is still a seperate branch called 'rails3':)
-  $ git checkout -t origin/rails3
-
-Now create a test bed application inside of Blacklight that will allow you
-to include Blacklight as a gem.
-The test_app directory already exists, and contains a .gitignore file that
-will mean all of the generated code is ingored.  - There are a few directories
-already in palce in test_app that WILL be included in the git repository.  These
-include:
-* test_app/features - which contains cucumber tests for blacklight
-* test_app/spec - rspec tests
-* test_app/jetty - The blacklight Jetty module (discussed later)
-* test_app/data - Another remote module.
-
-To create the rails application:
-
-  $ rails new test_app --skip-test-unit --skip-git
-
-Or if you are using Jruby:
-
-  $ jruby -S rails new test_app -m http://jruby.org/rails3.rb --skip-test-unit --skip-git
-
-Add gem 'blacklight' to the test applications Gemfile:
-
-  gem 'blacklight', :path => '../'
+== Using Blacklight source checkout as gem for development
 
-Run bundle install in the test app
-  $ bundle install
+The ordinary install instructions install the BL gem (which is not
+full source code) in wherever your system installs gems. 
 
-Install and configure blacklight (with devise setting)
-  $ rails generate blacklight --devise
+Sometimes, especially for development, it's useful to check out
+a complete copy of the blacklight source code, and link your app
+to that as a 'gem' instead. 
 
-Remove index.html - which will allow the routes to take you directly to the catalog page.
-  $ rm public/index.html  (allow us to redirect to catalog)
+Checkout the code:
 
-Migrate your database
-  $ rake db:migrate
+  $ git clone git@github.com:projectblacklight/blacklight.git  
 
-Get Solr running somewhere.  If you don't have Solr installed, blacklight comes with a default setup.
+(While the rails3 branch is still a seperate branch called 'rails3', 
+if you'd like to checkout the rails3 branch, or any other particular
+branch/tag using ordinary git commands:
   $ cd blacklight
-  $ git submodule init
-  $ git submodule update
-  $ cd test_app
-  $ rake solr:marc:index_test_data RAILS_ENV=test
-  $ cd jetty
-  $ java -jar start.jar
-
-Start up your Server, and take a test run. (from blacklight/test_app)
-  $ rails server
-  
-Now go check it out, should be running.
-
-== Running the tests
-
-You will need to add some gems to your test_app's Gemfile
-
-   group :development, :test do 
-      gem "rspec"
-      gem "rspec-rails", "~>2.5.0"       
-      gem "cucumber-rails"
-      gem "database_cleaner"  
-      gem "capybara"
-      gem "webrat"
-      gem "aruba"
-   end
-
-Run bundle install
+  $ git checkout -t origin/rails3
+)
   
-  $ bundle install
-
-Install cucumber
-
-  $ rails generate cucumber:install
+Now, in your local app's Gemfile, simply specify that it should find
+the Blacklight gem at this source checkout location:
+
+   gem 'blacklight', :path=>"./relative/path/to/blacklight_checkout"
+   
+You can have the blacklight source checkout anywhere you want, referred
+to by absolute or relative path. You can have it inside your local app's
+directory if you want, or you can have it outside using a relative path
+beginning with "../".  If you have it inside your app's root, you can
+even use 'git submodule' techniques to link your app to a particular
+git commit, like some of us did in Rails2 Blacklight. (But you probably
+don't want it in your local apps ./vendor/plugins, that'll likely
+confuse Rails, since it's already being referred to in your Gemfile). 
+
+== Running Blacklight's own tests
+
+Any application that refers to a Blacklight gem using a source checkout
+(see above) can run the automated tests (cucumber and rspec) that
+come with Blacklight source. 
+
+Of course, if you've customized the app quite a bit, the tests may not
+pass, as they test expected default behavior in some cases. So ordinarily
+tests are run against a pretty basic stub app. The tests also
+test authentication features, so expect the app to have auth features
+installed, for instance with a Devise install.
+
+To run the tests:
+
+* Create a stub app with BL with devise, following the ordinary instructions for
+  installing blacklight, but linking to a source checkout of Blacklight
+  following the instructions above in "Using Blacklight source checkout
+  as gem for development"
+* You also need to include some gems in your test app's Gemfile needed for
+  running our tests:
+       group :development, :test do 
+          gem "rspec"
+          gem "rspec-rails", "~>2.5.0"       
+          gem "cucumber-rails"
+          gem "database_cleaner"  
+          gem "capybara"
+          gem "webrat"
+          gem "aruba"
+       end
+* run `bundle install` in the test app, and don't forget `rake db:migrate`
+* complete the install of cucumber:  'rails g cucumber:install'
+* remove /public/index.html (blacklight tests expect / to map to catalog)
+* You need to install a jetty/solr with test data for testing. You can do that
+  like this (from your stub app home directory):
+      rails generate blacklight:jetty test_jetty -e test
+      rake solr:marc:index_test_data RAILS_ENV=test
+* Now use some rake tasks that come with Blacklight to actually run the tests. 
+  Run these from your stub app:
+  * rake blacklight:cucumber:with_solr -- run tests in BL, start and stop the test jetty/solr around tests
+  * rake blacklight:cucumber -- run tests in BL, no jetty/solr. (Tests will fail unless you start it yourself)
+  * rake blacklight:spec:with_solr
+  * rake blacklight:spec
+  * the standard rails tasks for cucumber/rspec are all included with 
+    blacklight: prefix, and should work as expected, but using
+    specs/features defined in BL plugin instead of in your local
+    app. (Not every variant has a :with_solr yet). 
 
-If you haven't yet done this to load the bundled jetty/solr environment and test data in your blacklight checkout, from the blacklight checkout dir:
-  git submodule init
-  git submodule update
-
-Load in the test data
-
-  $ rake solr:marc:index_test_data RAILS_ENV=test
-
-Run the tests
-  
-  $ rake solr:spec 
-  $ rake solr:features
 
 ==Pre-requisites
 Whichever method you choose for installation, be sure you have all the pre-requisites in place. You can find these detailed in {PRE-REQUISITES}[https://github.com/projectblacklight/blacklight/wiki/PRE-REQUISITES]

data/blacklight.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |s|
   end  
 
   # Required Gems
-  s.add_dependency "rails", "= 3.0.6"
+  s.add_dependency "rails", "~> 3.0"
   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.

data/config/routes.rb

@@ -25,7 +25,7 @@ Rails.application.routes.draw do
 
   # 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",       :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"
   

data/lib/blacklight.rb

@@ -63,8 +63,8 @@ module Blacklight
     @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
+        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
 

data/lib/blacklight/catalog.rb

@@ -1,24 +1,22 @@
 module Blacklight::Catalog 
+  extend ActiveSupport::Concern
+  include Blacklight::SolrHelper
 
   # 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
+  included do  
+    before_filter :search_session, :history_session
+    before_filter :delete_or_assign_search_session_params, :only => :index
+    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
+    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
+    rescue_from RSolr::Error::Http, :with => :rsolr_request_error
   end
   
 
@@ -281,7 +279,7 @@ module Blacklight::Catalog
        
     # when solr (RSolr) throws an error (RSolr::RequestError), this method is executed.
     def rsolr_request_error(exception)
-      if RAILS_ENV == "development"
+      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."
@@ -299,7 +297,7 @@ module Blacklight::Catalog
     
     # when a request for /catalog/BAD_SOLR_ID is made, this method is executed...
     def invalid_solr_id_error
-      if RAILS_ENV == "development"
+      if Rails.env == "development"
         render # will give us the stack trace
       else
         flash[:notice] = "Sorry, you have requested a record that doesn't exist."

data/lib/blacklight/controller.rb

@@ -39,9 +39,9 @@ module Blacklight::Controller
     # http://api.rubyonrails.org/classes/ActionController/Filters/ClassMethods.html
     # for how to turn off a filter in a sub-class and such.
     def default_html_head
-      stylesheet_links << ['yui', 'jquery/ui-lightness/jquery-ui-1.8.1.custom.css', 'blacklight', {:plugin=>:blacklight, :media=>'all'}]
+      stylesheet_links << ['blacklight/yui', 'blacklight/jquery/ui-lightness/jquery-ui-1.8.1.custom.css', 'blacklight/blacklight', {:media=>'all'}]
       
-      javascript_includes << ['jquery-1.4.2.min.js', 'jquery-ui-1.8.1.custom.min.js', 'blacklight', { :plugin=>:blacklight } ]
+      javascript_includes << ['blacklight/jquery-1.4.2.min.js', 'blacklight/jquery-ui-1.8.1.custom.min.js', 'blacklight/blacklight' ]
     end
     
     

data/lib/blacklight/engine.rb

@@ -24,8 +24,11 @@ module Blackight
 
     # This makes our rake tasks visible.
     rake_tasks do
-      load "railties/blacklight.rake"
-      load "railties/solr_marc.rake"
+      Dir.chdir(File.expand_path(File.join(File.dirname(__FILE__), '..'))) do
+        Dir.glob(File.join('railties', '*.rake')).each do |railtie|
+          load railtie
+        end
+      end
     end
 
   end

data/lib/blacklight/solr/document.rb

@@ -124,7 +124,7 @@ module Blacklight::Solr::Document
       begin      
         mime_type = "Mime::#{short_name.to_s.upcase}".constantize
         content_type = mime_type.to_s unless content_type      
-      rescue NameError
+      rescue NameError,LoadError
         # 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)

data/lib/blacklight/solr/document/marc.rb

@@ -25,22 +25,7 @@ module Blacklight::Solr::Document::Marc
     # Register our exportable formats, we inherit these from MarcExport    
     Blacklight::Solr::Document::MarcExport.register_export_formats( document )
   end
-
-  # DEPRECATED. Here for legacy purposes, but use to_marc instead. Or
-  # internally, use the protected _marc_helper method to get the
-  # (somewhat confusingly named)  Blacklight::Marc::Document helper object.
-  #
-  # This method gets attached to a SolrDocument.
-  # it uses the marc_source_field and marc_format_type
-  # class attributes to create the Blacklight::Marc::Document instance.
-  # Only returns a Blacklight::Marc::Document instance if
-  # the self.class.marc_source_field key exists.
-  def marc
-    warn "[DEPRECATION] aDocument.marc is deprecated.  Please use aDocument.respond_to?(:to_marc) / aDocument.respond_to?(:marc),  or aDocument.exports_as.keys.include?(:some_format) / aDocument.export_as(:some_format) instead."
-
-    _marc_helper
-  end  
-
+  
   # ruby-marc object
   def to_marc
     @_ruby_marc_obj ||= load_marc

data/lib/blacklight/solr_helper.rb

@@ -5,42 +5,71 @@
 #
 # Override these methods in your own controller for customizations:
 # 
-# class CatalogController < ActionController::Base
+#   class CatalogController < ActionController::Base
 #   
-#   include Blacklight::SolrHelper
+#     include Blacklight::Catalog
 #   
-#   def solr_search_params
-#     super.merge :per_page=>10
+#     def solr_search_params
+#       super.merge :per_page=>10
+#     end
 #   end
+#
+# Or by including in local extensions:
+#   module LocalSolrHelperExtension
+#     [ local overrides ]
+#   end
+#
+#   class CatalogController < ActionController::Base
+#   
+#     include Blacklight::Catalog
+#     include LocalSolrHelperExtension
 #   
-# end
+#     def solr_search_params
+#       super.merge :per_page=>10
+#     end
+#   end
+#
+# Or by using ActiveSupport::Concern:
+#
+#   module LocalSolrHelperExtension
+#     extend ActiveSupport::Concern
+#     include Blacklight::SolrHelper
+#
+#     [ local overrides ]
+#   end
 #
+#   class CatalogController < ApplicationController
+#     include LocalSolrHelperExtension
+#     include Blacklight::Catalog
+#   end  
 
 module Blacklight::SolrHelper
+  extend ActiveSupport::Concern
+
   MaxPerPage = 100
-  
-  def self.included(klass)
-    if klass.respond_to?(:helper_method)
-      klass.helper_method(:facet_limit_hash)
-      klass.helper_method(:facet_limit_for)
+
+  included do
+    if self.respond_to?(:helper_method)
+      helper_method(:facet_limit_hash)
+      helper_method(:facet_limit_for)
     end
-    
+
     # We want to install a class-level place to keep 
     # solr_search_params_logic method names. Compare to before_filter,
     # similar design. Since we're a module, we have to add it in here.
     # There are too many different semantic choices in ruby 'class variables',
     # we choose this one for now, supplied by Rails. 
-    klass.class_inheritable_accessor :solr_search_params_logic
+    class_inheritable_accessor :solr_search_params_logic
+
     # Set defaults. Each symbol identifies a _method_ that must be in
     # this class, taking two parameters (solr_parameters, user_parameters)
     # Can be changed in local apps or by plugins, eg:
     # CatalogController.include ModuleDefiningNewMethod
     # CatalogController.solr_search_params_logic << :new_method
     # CatalogController.solr_search_params_logic.delete(:we_dont_want)
-    klass.solr_search_params_logic = [:default_solr_parameters , :add_query_to_solr, :add_facet_fq_to_solr, :add_facetting_to_solr, :add_sorting_paging_to_solr ]
+    self.solr_search_params_logic = [:default_solr_parameters , :add_query_to_solr, :add_facet_fq_to_solr, :add_facetting_to_solr, :add_sorting_paging_to_solr ]
   end
   
-  
   # A helper method used for generating solr LocalParams, put quotes
   # around the term unless it's a bare-word. Escape internal quotes
   # if needed.