blacklight 4.6.3 → 4.7.0.pre1

data/doc/Release-Notes-And-Upgrade-Guides.md

@@ -0,0 +1,20 @@
+This is for upgrade guides for each version.
+* [Blacklight 4.5 Release Notes and Upgrade Guide](https://github.com/projectblacklight/blacklight/releases/tag/v4.5.0) (???)
+* [Blacklight 4.4 Release Notes And Upgrade Guide](https://github.com/projectblacklight/blacklight/releases/tag/v4.4.0) (September 17, 2013)
+* [Blacklight 4.3 Release Notes And Upgrade Guide](https://github.com/projectblacklight/blacklight/releases/tag/v4.3.0) (July 30, 2013)
+* [Blacklight 4.2.2 Release Notes And Upgrade Guide](https://github.com/projectblacklight/blacklight/releases/tag/v4.2.2) (2013)
+* [Blacklight 4.2.1 Release Notes And Upgrade Guide](https://github.com/projectblacklight/blacklight/releases/tag/v4.2.1) (2013)
+* [Blacklight 4.2.0 Release Notes And Upgrade Guide](https://github.com/projectblacklight/blacklight/releases/tag/v4.2.0) (Mar 29, 2013)
+* [Blacklight 4.1 Release Notes And Upgrade Guide](https://github.com/projectblacklight/blacklight/releases/tag/v4.1.0) (Mar 7, 2013)
+* [Blacklight 4.0 Release Notes And Upgrade Guide](https://github.com/projectblacklight/blacklight/releases/tag/v4.0.0) (Nov 29, 2012)
+* [[Blacklight 3.8 Release Notes And Upgrade Guide]] (Nov 2, 2012)
+* [[Blacklight 3.7 Release Notes And Upgrade Guide]] (Sep 25, 2012)
+* [[Blacklight 3.6 Release Notes And Upgrade Guide]] (Sep 10, 2012)
+* [[Blacklight 3.5 Release Notes And Upgrade Guide]] (Jun 25, 2012)
+* [[Blacklight 3.4 Release Notes And Upgrade Guide]] (Apr 24, 2012)
+* [[Blacklight 3.3 Release Notes And Upgrade Guide]] (Mar 19, 2012)
+* [[Blacklight 3.2 Release Notes And Upgrade Guide]] (Dec 15, 2011)
+* [[Blacklight 3.1 Release Notes And Upgrade Guide]] (Sep 28, 2011)
+* [[Blacklight 3.0 Release Notes And Upgrade Guide]] (July 11, 2011)
+
+Unreleased

data/doc/Roadmap.md

@@ -0,0 +1,43 @@
+<table>
+<thead><td>Feature</td><td>What can be reused?</td><td>Who wants this</td><td>Who can work on this</td></thead>
+<tbody>
+<tr>
+  <td>Document Index view toggles</td>
+  <td><a href="https://revs-lib.stanford.edu/catalog?f%5Bpub_year_isim%5D%5B%5D=1930&q=&utf8=%E2%9C%93">Stanford</a>, <a href="http://levysheetmusic.mse.jhu.edu/catalog?utf8=%E2%9C%93&q=&f%5Bmods_subject_facet%5D%5B%5D=African+Americans">JHU</a></td>
+  <td></td>
+  <td></td>
+</tr>
+<tr>
+  <td>i18n files in blacklight</td>
+  <td>Stanford has fr + it</td>
+  <td></td>
+  <td></td>
+</tr>
+
+<tr>
+  <td><a href="https://groups.google.com/forum/?fromgroups=#!topic/blacklight-development/Brz3ePltc3w">Thumbnails in search results</a></td>
+  <td>Many places</td>
+  <td></td>
+  <td>cbeer</td>
+</tr>
+
+<tr>
+  <td><a href="https://groups.google.com/forum/?fromgroups#!topic/blacklight-development/LGk2DtsA8rA">Blacklight curriculum for RailsBridge</a></td>
+  <td></td>
+  <td></td>
+  <td>bess</td>
+</tr>
+<tr>
+  <td>Tags and Comments</td>
+  <td></td>
+  <td>afred,awead</td>
+  <td></td>
+</tr>
+<tr>
+  <td>Caching</td>
+  <td></td>
+  <td>jronallo</td>
+  <td></td>
+</tr>
+</tbody>
+</table>

data/doc/Sunspot-for-indexing.md

@@ -0,0 +1,46 @@
+If you have a Rails application as your data store, you may look to [Sunspot](http://outoftime.github.com/sunspot/) to help index your ActiveRecord models. Sunspot provides a nice DSL that makes it easy to index your models and associations. There is one gotcha, though, for using Sunspot with Blacklight. Both Sunspot and Blacklight expect the Solr uniqueKey to be in the "id" field. Sunspot will use the class of your model plus the primary key of that instance as the value for the id field. So a value for the id field may look like this: "Resource 123". 
+
+When a Sunspot-indexed Solr is used with Blacklight your model names and primary keys are exposed in your URLs. You may want to use a different value as your id value for Blacklight to use for document recall and URLs. For instance you want to use a unique filename as your id value for Blacklight.  
+
+You can use something like the following monkeypatch of Sunspot (1.2) by placing it in config/initializers/sunspot_monkeypatch_id.rb. It takes the value of the id field that Sunspot creates (Resource 123) and places it in the resource_id_ss field. It then overwrites the id value with the value from the filename field. The second part then takes a Solr hit and reverses it so that Sunspot can retrieve your models.
+
+```ruby
+     # for using a different value for the id field of your Solr documents
+     Sunspot::Indexer.module_eval do
+       alias :old_prepare :prepare
+       def prepare(model)
+         document = old_prepare(model)
+         document.fields_by_name(:resource_id_ss).first.value = document.fields_by_name(:id).first.value
+         if !document.fields_by_name(:filename).blank? and !document.fields_by_name(:filename).first.blank?
+            document.fields_by_name(:id).first.value = document.fields_by_name(:filename).first.value
+         end
+         document
+       end
+
+       alias :old_remove :remove  
+       def remove(*models)
+         @connection.delete_by_id(
+           models.map do |model| 
+             prepare(model).fields_by_name(:id).first.value
+           end
+         )
+       end
+
+     end
+
+     # to allow searching with Sunspot's DSL as well to retrieve your models
+     class Sunspot::Search::Hit
+       def initialize(raw_hit, highlights, search) 
+         raw_hit['id'] = raw_hit['resource_id_ss']
+         @class_name, @primary_key = *raw_hit['id'].match(/([^ ]+) (.+)/)[1..2]
+         @score = raw_hit['score']
+         @search = search
+         @stored_values = raw_hit
+         @stored_cache = {}
+         @highlights = highlights
+       end
+     end
+```
+
+
+

data/doc/Theming.md

@@ -0,0 +1,64 @@
+# Theming Blacklight
+
+## Bootswatches
+
+The Blacklight 4.x styling is [[Twitter Bootstrap|http://twitter.github.com/bootstrap]] based. While there is some Blacklight-specific code for handling layouts and positions, most (if not all) the "styling" (colors, fonts, etc) are handled by Bootstrap.
+
+There are many sources for Bootstrap themes. We'll look at bootswatches because they are fairly painless to integrate into a Rails application.
+
+First, add the [[bootswatch-rails gem|https://github.com/maxim/bootswatch-rails]]  to your Gemfile (and run ```bundle install```):
+
+```ruby
+gem 'bootswatch-rails'
+```
+
+This will give you the set of themes from [[http://bootswatch.com/]], converted to SASS and exposed to the Rails asset pipeline. 
+
+Out of the box, your application's blacklight stylesheet (generated by default to ```app/assets/stylesheets/blacklight.css.scss```) looks something like:
+
+```css
+@import 'bootstrap';
+@import 'bootstrap-responsive';
+
+@import 'blacklight/blacklight';
+```
+
+To add the one of the bootswatch themes ('cerulean' in this example):
+
+```css
+@import "bootswatch/cerulean/variables";
+
+@import "bootstrap";
+@import "bootstrap-responsive";
+
+@import "bootswatch/cerulean/bootswatch";
+
+@import 'blacklight/blacklight'
+```
+
+![Blacklight with the Cerulean theme applied](http://projectblacklight.org/images/blacklight-cerulean.png)
+
+The [[bootswatch-rails|https://github.com/maxim/bootswatch-rails]] documentation provides similar directions, a list of available out-of-the-box themes, and more.
+
+> As of this writing, not all bootswatch-rails themes seem to be bootstrap 2.1.x compatible, or do weird things to the Blacklight navbar, etc. Your milage may vary.
+
+## Developing a Customized "Local" Theme
+
+In most cases, you will want to develop your own theme within your Blacklight app, outside of the Bootswatch gem.  To do this, you can do the following in your ```app/assets/stylesheets``` directory:
+
+1. create your own _variables.scss and _bootswatch.scss files in stylesheets/ (easiest way to do this is to copy those files from the [[bootstrap-sass project|https://github.com/thomas-mcdonald/bootstrap-sass/tree/master/vendor/assets/stylesheets/bootstrap]] or an existing theme and customize from there)
+2. change application.css to application.css.scss 
+3. add the import statements given in the above "theming" example to application.css.scss
+4. delete blacklight.css.scss
+
+So, your application.css.scss should look like this:
+```css
+@import "variables";
+
+@import "bootstrap";
+@import "bootstrap-responsive";
+
+@import "bootswatch";
+
+@import 'blacklight/blacklight'
+```

data/doc/User-Authentication.md

@@ -0,0 +1,60 @@
+Blacklight does not require user authentication, however, if included, Blacklight can provide additional features for users ([[Bookmarks]], [[Saved Searches]], etc). Because of the wide range of institutional needs and capabilities, Blacklight does not require a specific user authentication provider. 
+
+## Installing with Devise
+
+If you are rolling your own user authentication system, we highly recommend [[Devise|https://github.com/plataformatec/devise]], an extremely flexible authentication solution that is relatively straightforward. For directions to install the Blacklight gem using devise, see the [[Quickstart]].
+
+## Install and Use (with a custom user authentication system)
+
+Create a new rails 3 application
+```bash
+$ rails new my_app
+```
+
+Add blacklight to your gem file 
+```bash
+edit ./my_app/Gemfile
+```
+```ruby.
+# Append this line to the end of the file:
+gem 'blacklight'
+```
+
+```bash
+$ bundle install
+```
+
+If you have a `User` model already, the Blacklight generator will connect to it automatically during installation.  However, you will need to make sure the following named routes are included in your /config/routes.rb file:
+
+```ruby
+  match 'your_login',          :to => 'Your User Session Controller # Log in action',       :as => 'new_user_session'
+  match 'your_logout',         :to => 'Your User Session Controller # Log Out action',      :as => 'destroy_user_session'
+  match 'your_account_page',   :to => 'Your User Session Controller # Account edit action', :as => 'edit_user_registration'
+```
+
+One blacklight view partial uses `#to_s` on your user model to get a user-displayable account name/identifier for the currently logged in account, so you probably want to have such a method. 
+
+Finally, you will need to make sure the following methods are available both on controllers and as helpers:
+
+* `current_user`   - Which should return an ActiveRecord-based user object that include Blacklight::User
+* `user_session`   - Which are included in your /config/routes.rb file:
+
+Optionally,
+* `guest_user` -  Which should return an ActiveRecord-based temporary guest user object available across the current user session.
+* `current_or_guest_user` - Which should return the `current_user`, if available, or `guest_user`. If you don't provide this method, a stub method (that just returns `current_user`) will be provided for you.
+
+If you are supporting guest users, if a guest user logs in, you should call `#transfer_guest_user_actions_to_current_user` to move any persisted data to the permanent user.
+
+> The `devise-guests` gem implements the `guest_user`, `current_or_guest_user` and callbacks for Blacklight applications using devise. It may be a useful reference for rolling your own functionality. See [DeviseGuests::Controllers::Helpers](https://github.com/cbeer/devise-guests/blob/master/lib/devise-guests/controllers/helpers.rb)
+
+Once these are in place, you can run the Blacklight Installation Generator:
+
+```bash
+$ rails generate blacklight [MODEL NAME]
+```
+Where model name is the name of your user model.
+
+Execute your migrations, and you should be good to go.
+```bash
+$ rake db:migrate
+```

data/doc/testing.md

@@ -0,0 +1,57 @@
+## Using Blacklight source checkout as gem for development
+
+The ordinary install instructions install the BL gem (which is not
+full source code) in wherever your system installs gems. 
+
+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. 
+
+Checkout the code:
+
+    $ git clone git@github.com:projectblacklight/blacklight.git  
+
+
+## Automatically generate a test application (and run the tests)
+
+To run the Blacklight test suite, Blacklight comes with a rake task that creates local dependencies like a Solr with indexed test data and a test Rails application, and then runs tests. 
+
+Requirements:
+
+  * Java (1.6 or above) (for Solr)
+  * phantomjs (used by integration tests, you may be able to install with your local package manager, for instance on OSX with `brew install phantomjs`)
+
+Then from the root directory of your blacklight git checkout:
+
+```
+rake ci  
+```
+This ensure a test Solr exists and is running, creates a test application, and loads the fixtures and then runs specs and cucumber tests.
+
+### Step by step, with more control
+
+`rake ci` will, every time you run it, re-index test data in solr, and re-build the test application. Re-building the test application in particular is kind of time-consuming. You may prefer to set up the environment and run tests as separate steps, to make development easier. 
+
+To create the dummy test app:
+
+    $ rake engine_cart:generate
+
+(If you have an existing dummy app that is outdated, `rake engine_cart:clean` first, then `rake engine_cart:generate). 
+
+Then start up the test jetty with:
+
+    $ rake jetty:start
+
+If you haven't yet indexed the test data in the test jetty. (??? Not sure how to do this. Run `rake ci` once to make sure test data has been indexed).  Run `rake jetty:stop` when you're done with it. 
+
+Then run all the specs with:
+
+    $ rake spec
+
+Or just run one spec
+
+    $ rake spec SPEC=just/one_spec.rb
+
+And stop your test solr when you're done with it:
+
+    $ rake jetty:stop

data/lib/blacklight.rb

@@ -30,6 +30,7 @@ module Blacklight
   autoload :Facet, 'blacklight/facet'
 
   extend SearchFields
+  extend Deprecation
   
   require 'blacklight/version'
   require 'blacklight/engine' if defined?(Rails)
@@ -40,6 +41,7 @@ module Blacklight
   
   # Adding a little jruby support
   def self.jruby?
+    Deprecation.warn(Blacklight, "Blacklight.jruby? is deprecated")
     defined?(RUBY_ENGINE) && RUBY_ENGINE == "jruby" 
   end
 
@@ -52,6 +54,7 @@ module Blacklight
   end
 
   def self.solr
+    Deprecation.warn Blacklight, "Blacklight.solr is deprecated and will be removed in Blacklight 5.0"
     @solr ||=  RSolr.connect(Blacklight.solr_config)
   end
 
@@ -116,10 +119,12 @@ module Blacklight
   # 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
+    Deprecation.warn(Blacklight, "Blacklight.models_dir is deprecated")
     "#{root}/app/models"
   end
   
   def self.controllers_dir
+    Deprecation.warn(Blacklight, "Blacklight.controllers_dir is deprecated")
     "#{root}/app/controllers"
   end
 
@@ -133,6 +138,7 @@ module Blacklight
   # full_path_to_solr_marc_jar = Blacklight.locate_path 'solr_marc', 'SolrMarc.jar'
   
   def self.locate_path(*subpath_fragments)
+    Deprecation.warn(Blacklight, "Blacklight.locate_path is deprecated")
     subpath = subpath_fragments.join('/')
     base_match = [Rails.root, self.root].find do |base|
       File.exists? File.join(base, subpath)

data/lib/blacklight/base.rb

@@ -5,6 +5,8 @@ module Blacklight::Base
   include Blacklight::Configurable
   include Blacklight::SolrHelper
 
+  require 'blacklight/catalog/search_context'
+  include Blacklight::Catalog::SearchContext
 
   included do  
     # When RSolr::RequestError is raised, the rsolr_request_error method is executed.

data/lib/blacklight/catalog.rb

@@ -6,9 +6,6 @@ module Blacklight::Catalog
   extend ActiveSupport::Concern
   
   include Blacklight::Base
-  
-  require 'blacklight/catalog/search_context'
-  include Blacklight::Catalog::SearchContext
 
   SearchHistoryWindow = 100 # how many searches to save in session history
 
@@ -267,6 +264,10 @@ module Blacklight::Catalog
       render "index", :status => 404
     end
 
+    def start_new_search_session?
+      action_name == "index"
+    end
+
     def blacklight_solr
       @solr ||=  RSolr.connect(blacklight_solr_config)
     end

data/lib/blacklight/catalog/search_context.rb

@@ -26,7 +26,7 @@ module Blacklight::Catalog::SearchContext
   # The current search session 
   def current_search_session
 
-    @current_search_session ||= if action_name == "index"
+    @current_search_session ||= if start_new_search_session?
       find_or_initialize_search_session_from_params params
     elsif params[:search_context] and !params[:search_context].blank?
       find_or_initialize_search_session_from_params JSON.load(params[:search_context])
@@ -52,6 +52,13 @@ module Blacklight::Catalog::SearchContext
     @current_search_session
   end
 
+  ##
+  # If the current action should start a new search session, this should be
+  # set to true
+  def start_new_search_session?
+    false
+  end
+
   def find_or_initialize_search_session_from_params params
     params_copy = params.reject { |k,v| blacklisted_search_session_params.include?(k.to_sym) or v.blank? }
 

data/lib/blacklight/configurable.rb

@@ -41,8 +41,7 @@ module Blacklight::Configurable
     end
 
     ##
-    # The default configuration object, by default it reads from Blacklight.config for backwards
-    # compatibility with Blacklight <= 3.1
+    # The default configuration object
     def default_configuration
       Blacklight::Configurable.default_configuration.inheritable_copy
     end

data/lib/blacklight/solr/document.rb

@@ -172,7 +172,8 @@ module Blacklight::Solr::Document
     end
 
      def connection
-      @connection ||= Blacklight.solr
+       Deprecation.warn(self, "Document.connection is deprecated and will be removed in Blacklight 5.0")
+       @connection ||= Blacklight.solr
      end
     
     # Returns array of hashes of registered extensions. Each hash

data/lib/blacklight/solr_helper.rb

@@ -642,4 +642,12 @@ module Blacklight::SolrHelper
     blacklight_config.index.group
   end
 
+  def blacklight_solr
+    @solr ||= RSolr.connect(blacklight_solr_config)
+  end
+
+  def blacklight_solr_config
+    Blacklight.solr_config
+  end
+
 end

data/lib/blacklight/user.rb

@@ -1,6 +1,9 @@
 # -*- encoding : utf-8 -*-
 module Blacklight::User
 
+  extend Deprecation
+  self.deprecation_horizon = 'blacklight 5.0'
+
   # This gives us an is_blacklight_user method that can be included in
   # the containing applications models. 
   # SEE ALSO:  The /lib/blacklight/engine.rb class for how when this 
@@ -19,18 +22,19 @@ module Blacklight::User
   end
 
   def has_bookmarks?
+    Deprecation.warn(Blacklight::User, "User#has_bookmarks? is deprecated; use User#bookmarks.any? instead")
     bookmarks.any?
   end
     
   def has_searches?
+    Deprecation.warn(Blacklight::User, "User#has_searchs? is deprecated; use User#searches.any? instead")
     searches.any?
   end
     
   def bookmarked_document_ids
     self.bookmarks.pluck(:document_id)
   end
-    
-  # see #current_bookmark_for, is easier
+
   def document_is_bookmarked?(document_id)
     bookmarked_document_ids.include? document_id.to_s
   end
@@ -42,6 +46,7 @@ module Blacklight::User
   end
     
   def documents_to_bookmark=(docs)
+    Deprecation.warn(Blacklight::User, "User#documents_to_bookmarks= is deprecated and will be removed in Blacklight 5.0")
     docs.reject { |doc| document_is_bookmarked?(doc[:document_id]) }.each do |doc|
       self.bookmarks.create(doc) 
     end