blacklight 3.1.2 → 3.2.0pre1

data/doc/Integration-with-Rails-Footnotes.md

@@ -1,20 +0,0 @@
-[[Rails Footnotes|https://github.com/josevalim/rails-footnotes]] is a helpful plugin that displays footnotes in your application for easy debugging, such as sessions, request parameters, cookies, filter chain, routes, queries, etc. Installing Rails Footnotes is very easy, just add this to your Gemfile:
-```ruby
-gem 'rails-footnotes', '>= 3.7', :group => :development
-```
-
-And add something like this to config/initializers/footnotes.rb to run the Footnotes plugin:
-```ruby
-if defined?(Footnotes) && Rails.env.development?
-  Footnotes.run!
-end
-```
-
-To add RSolr debugging information to the footnotes panel, you can use the [[RSolr Footnotes|https://github.com/cbeer/rsolr-footnotes]] gem by adding this to your Gemfile:
-```ruby
-gem "rsolr-footnotes", :group => :development
-```
-
-RSolr footnotes will capture every solr request with basic performance information and provide a link back to the Solr request URL.
-
-[[https://github.com/projectblacklight/projectblacklight.github.com/raw/master/images/rsolr_footnotes_example.png|frame|alt=Example of RSolr Footnotes in the Blacklight Demo App]]

data/doc/Pagination.md

@@ -1,38 +0,0 @@
-Blacklight uses [kaminari](https://github.com/amatsuda/kaminari) for providing pagination of Solr responses. 
-
-One motivation for this is so a pagination view theme can be provided that you can use for your custom code with ordinary ActiveRecord or anything else kaminari can handle, to have consistency between the rest of your app's pagination and Blacklight's Solr response pagination. 
-
-## How it works
-
-The Blacklight #paginate_params helper method takes an RSolr::Response, and converts it to something Kaminari #paginate can handle. (Basically just by translating some attribute names). So you could call:
-
-    paginate( paginate_params(@response) )  # where @response is an RSolr::Response
-
-But there's a shortcut Blacklight helper method which compacts this, #paginate_rsolr_response:
-
-    paginate_solr_response @response, :theme => 'blacklight'
-
-The `theme => 'blacklight'` part will be passed through kaminari, and tell kaminari to use the theme that the Blacklight plugin supplies at [app/views/kaminari/blacklight](https://github.com/projectblacklight/blacklight/tree/master/app/views/kaminari/blacklight)
-
-Any other arguments of ordinary kaminari paginate can also be passed in there. If all client code uses #paginate_solr_response, it also provides a 'hook' for local apps to completely over-ride pagination rendering, perhaps not even using kaminari. 
-
-Additionally, we sometimes want to output a "Showing X through Y of N" message, which kaminari doesnt' have a way to do by default, so we just provide our own way in a Blacklight view helper method, which takes a RSolr::Response too:
-
-    render_pagination_info(@response)
-
-## Changing the kaminari theme
-
-If you want to change how pagination links are rendered, the easiest/cleanest thing to do is to over-ride the 'blacklight' theme that the Blacklight plugin defines. Copy the view templates in Blacklight source at app/views/kaminari/blacklight to your own local app/views/kaminari/blacklight.  You actually only need to copy files you'll want to modify, templates not overridden with a local copy will still be found by kaminari from the Blacklight gem.  You can use any techniques available for creating a kaminari theme when editing these files, including over-riding more kaminari view templates if available. See the kaminari documentation. 
-
-There are other ways you could change how Blacklight pagination renders, but by doing it this way, any code (in core Blacklight or additional plugins you install) that tries to render pagination using kaminari with 'blacklight' theme will get your locally defined theme. 
-
-The "pagination info" (showing X through Y of N) is not part of the kaminari theme, but just a blacklight view helper method, #render_pagination_info.  To change this, just over-ride this method [[over-ride locally|CUSTOMIZING]] like any other Blacklight view helper method. 
-
-## Using kaminari theme for your own pagination
-
-Your local app may show pagination of ActiveRecord objects, that you'd like to appear consistent with other Blacklight pagination. Just use kaminari to show the pagination HTML, with the theme :blacklight.  This technique can be used for anything kaminari can paginate, such as Mongoid et al, in addition to ActiveRecord. Fetch the ActiveRecords using ordinary kaminari techniques (see kaminari docs) and then:
-
-    paginate @my_active_records, :theme => 'blacklight'
-
-That's it. There's currently no great way to display the #render_pagination_info for anything but RSolr::Response. 
-

data/doc/Quickstart.md

@@ -1,97 +0,0 @@
-## Pre-requisites
- * ruby v 1.8.7 or higher
- * git
- * java 1.5 or higher
- * access to a command prompt on the machine to install
-    (preferably unix based)
-
-In addition, you must have the Bundler and Rails ruby gems installed:
-
-```bash
-$ gem install bundler
-$ gem install rails
-```
-
-## Install and Use
-
-1. Create a new rails 3 application
-
-    ```bash
-    $ rails new my_app      
-    #      create  
-    #      create  README
-    #      create  Rakefile
-    #      create  config.ru
-    #      create  .gitignore
-    #      create  Gemfile
-    #      [...]
-
-    $ cd my_app
-    ```
-
-    Rails automatically created an `index.html` file; Blacklight will provide a default `root` route, so you probably want to remove it:
-
-    ```bash
-    $ rm public/index.html
-    ```
-
-2. Append this line to your application's `Gemfile`
-
-    ```ruby
-    gem 'blacklight'
-    ```
-    and update the bundle
-
-    ```bash
-    $ bundle install
-    ```
-
-3. Install blacklight using Devise for user authentication: 
-
-    ```bash
-    $ gem install devise
-    $ rails generate blacklight --devise
-    ```
-    If you would prefer to integrate with an alternative user authentication provider, see the [[User Authentication]] documentation.
-
-4. Run your database migrations
-
-    ```bash
-    $ rake db:migrate
-    ```
-
-5. You will need to install and configure Solr. You can install
-Blacklight's example Solr configuration (using the jetty servlet container) that is configured to work with
-Blacklight's defaults, like:
-
-    ```bash
-    $ rails generate blacklight:jetty
-    ```
-
-    Alternatively, you can also install your own copy of Solr or point Blacklight at an existing Solr server ( referred to in your `config/solr.yml`). The Blacklight
-configuration must match your Solr configuration. In addition, Blacklight has minor expectations about the Solr configuration and schemas. You can generate the Blacklight demonstration solrconfig and schema files using:
-
-    ```bash
-    $ rails generate blacklight:solr_conf path/to/output/directory/
-    ```
-  
-6.  Make sure your Solr server is running. If you installed the Blacklight demo Solr/Jetty package, you can start the Jetty/Solr server using:
-
-    ```bash
-    $ cd jetty && java -jar start.jar &
-    $ cd ..
-    ```
-
-6. Index some data. You can index test MARC records provided Blacklight running:
-
-    ```bash
-    $ rake solr:marc:index_test_data
-    ```
-
-7. Start up your application
-
-    ```bash
-    $ rails server
-    ```
-
-Visit the catalog at [[http://localhost:3000/catalog]]

data/doc/Upgrading-Guide.md

@@ -1,98 +0,0 @@
-This page outlines the basic steps needed to upgrade your customized installation of Blacklight to work with the new Rails 3 branch available in our repository.  This is very much in beta now - and while we would love feedback, I don't recommend you use this branch in any sort of production environment. 
-
-## Rails 3 Specific Changes:
-Please see [[http://omgbloglol.com/post/353978923/the-path-to-rails-3-approaching-the-upgrade]] - for a good introduction.
- 
-1. Start by installing Rails3, generate a new app, make sure it works.  doing this not only proves your rails3 installation is working, but it will also get you familiar with the command line tools - which are very different now.
-1. Now, create a new rails app on top of your existing application. This will make all sorts of modifications, creating and updating your Gemfile, Rakefile, application.rb, locals, new javascript, etc...  You should also remove all the files in /script/ except for rails - since these scripts are no longer used.
-```bash
-$ rails new my_existing_app
-```
-
-1. Routes are WAY different in rails 3.  Please see [[http://www.engineyard.com/blog/2010/the-lowdown-on-routes-in-rails-3/]]
-1. Most of your application specific configuration now takes place in a file called config/application.rb  - you will need to move most of what is currently in your config/environment.rb and config/boot.rb into this new file. (see the link at the top of thie section for a good overview of how this works)
-1. The lib directory is no longer auto-loaded - and the general recommendation is not to make it so (though it is possible inside of config/application.rb) - I went through and added requires methods where and when they are needed in the individual files, which is nice - because now it is far more clear what needs what.
-1. Rails3 escapes strings by default.  You will have to add html_safe to any ruby string variables printed within "<%=" tags
-
-## Other Gems that will need upgrading
-1. If you were using the ExceptionNotification gem, things have changed in rails,  There is a good explanation here:
-    http://stackoverflow.com/questions/3524127/exception-notification-gem-and-rails-3
-1.  If your are using Rspec, you will need to upgrade it in your gem file to version 2.  And you will need to re-run the generator
-```ruby
-gem 'rspec', '>2.0.0'
-$rails generate spec:install
-```
-1.  Recapcha, and Prawnto - I was previously using these as plugins, but they have good gems now, so I removed these from the plugin directory, and added them to the gemfile.
-1. If you are using Marc, make sure you are running 0.4.1 - ran into some problems related to changes in the way Rails3 handles json prior to this upgrade.
-
-## Blacklight Specific Changes
-1. There is no application_helper.rb file in blacklight now.  It was moved to blacklight_helper, and its methods are made available automatically. (see blacklight/engine.rb for more information) So if you were attepting to include this file and override it, don't.  Just redefine the methods in your application_helper, and you should be fine.
-1.  Remove the blacklight plugin directory from /vendor - since you will be installing in as a gem.   If you have blacklight checked out somewhere, you can point to it in your gem file as follows:
-```ruby
-   gem 'blacklight', :path => '../some/file/path/to/blacklight' 
-```
-otherwise, just reference the blacklight gem, which we will make available on rubygems shortly.
-```ruby
-   gem 'blacklight' 
-```
-1. Most of the configuration of blacklight is done through monkey patching at present.  In Virgo you would often see lines like:
-```ruby
-  require_dependency 'vendor/plugins/blacklight/....
-```
-at the top of a file that re-opened the class and made modifications to it. 
-You would now need to change this to:
-```ruby
-  require "#{Blacklight.controllers_dir}/bookmarks_controller" For controllers, and ...
-  require "#{Blacklight.models_dir}/bookmark" For models.
-```
-1. Blacklight no longer includes a user model or session controller.  It seems that everyone just rolls their own anyway.  So here you will need to add in whatever you need - in my case, that was just creating a user model.  Which looks like this:
-```ruby
-       class User < ActiveRecord::Base                                    
-         include Blacklight::User
-         acts_as_authentic                               
-       end
-```
-Please also see the notes on the application controller below ...
-
-1. Execute the Blacklight Generator   - This will add all kinds of files to your local application - including stylesheets, images, jar files, database migrations, etc..  It will try it's best to be "idempotent" as Jonathan likes to say - that it is shouldn't mess anything up to run this over and over again.  It will verify that the changes it's making are not already in place.
-```bash
-      $ rails generate blacklight
-```
-1. For the most part, you override a blacklight controller by including the class and then reopening it.  Unfortunately, the catalog controller was unique in the way it number of additional lib files it required and included, and it caused a number of problems attepting to just override it.  So a catalog controller is generated for you on installation (unless you already have one).  You catalog controller should look something like this (which allows you to easily override solrhelper and catalog controller methods)
-```ruby
-class CatalogController < ApplicationController
-    include Blacklight::SolrHelper
-    inlcude Blacklight::Catalog
-     .....
- end
-```
-If you end up overriding a large number of solrhelper methods, you can also override the solr helpers in your own file, and then include that file.
-```ruby
-module UVA::SolrHelper
-   include Blacklight::SolrHelper
-   .....
-end
-
-class CatalogController < ApplicationController
-   include UVA::SolrHelper
-   include Blacklight::Catalog
-  ....
-end
-```
-1. Application Controller
-     The blacklight generator, will add a line to your application controller if isn't there already which will cause the application controller to include the base controller logic for blacklight:
-```ruby
-     class ApplicationController < ActionController::Base
-         include Blacklight::Controller
-     end     
-```
-    This blacklight controller forces the the blacklight layout, adds the default_html_head before filter and associated helper methods, and creates a few helper methods for users.  Blacklight by no means requires the inclusion of this file.  In the case of Virgo, we do not. 
-
-   You will most likely need to define the following methods in your application controller, paticularly if you have any sort of custom user authentication.
-
-* `user_session` - which should return the current rails session object.
-* `current_user`  - which should return a user object that includes Blacklight::User
-* `new_user_session_path` - which should return the path for logging into your application
-* `destroy_user_session_path` - which should return the path for logging out of your application.
-
-SolrDocument is no longer a file in Blacklight, but rather a generated model in your application, in this way you can easily override and modify the behavior of individual documents. This is automatically created for you, I just wanted to draw you attention to it.

data/doc/User-Authentication.md

@@ -1,54 +0,0 @@
-After [[CODEBASE-325|http://jira.projectblacklight.org/jira/browse/CODEBASE-325]] is implemented, 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 'blackight'
-```
-
-```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 a user object that include Blacklight::User
-* `user_session`   - Which are included in your /config/routes.rb file:
-
-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
-```
-
-If you need to install Solr or the sample data, follow the directions from the see the [[Quickstart]].

data/doc/Using-a-custom-solr-uniquekey-field.md

@@ -1,36 +0,0 @@
-> The [[`uniqueKey`|http://wiki.apache.org/solr/UniqueKey]] encodes the identity semantics of a document. In database jargon, the primary key. 
-
-The default `uniqueKey` field in Blacklight is "id", however it is possible to configure Blacklight to use a different field. To configure the `uniqueKey` field to use, you must in Blacklight, you can update the Blacklight initializer in `./config/blacklight_initializer.rb`:
-
-```ruby
-Blacklight.configure(:shared) do |config|
-  config[:unique_key] = "my_custom_unique_key_field"
-```
-
-(You could also make this change "in code" by defining a `Class`-level `unique_key` method on `SolrDocument`, e.g.:
-```ruby
-class SolrDocument
-  def self.unique_key
-    "my_custom_unique_key_field"
-  end
-end
-```
-)
-
-You must also modify the `document` request handler in Solr to map the user parameter `id` to the Solr `uniqueKey` field, e.g.:
-
-```xml
-  <!-- for requests to get a single document; use id=666 instead of q=id:666 -->
-  <requestHandler name="document" class="solr.SearchHandler" >
-    <lst name="defaults">
-      <str name="echoParams">all</str>
-      <str name="fl">*</str>
-      <str name="rows">1</str>
-      <str name="q">{!raw f=my_custom_unique_key_field v=$id}</str> <!-- use id=666 instead of q=id:666 -->
-    </lst>
-  </requestHandler>
-```
-
-## Code Standards
-
-When writing code in Blacklight (or a dependent plugin or local app) that needs to look at the unique ID for a SolrDocument, you should always ask for someDocument.id and *not* someDocument['id'], in order for your code to work with configured unique_key, not hard-coded to a key named 'id'. 

data/lib/blacklight/comma_link_renderer.rb

@@ -1,28 +0,0 @@
-# -*- encoding : utf-8 -*-
-require 'will_paginate/view_helpers/link_renderer'
-
-# Custom link renderer for WillPaginate
-# Inserts commas into large page numbers
-# example: 443719 becomes 443,719
-#
-# Note: To use this class, please call:
-# <%= will_paginate(@users, :renderer => CommaLinkRenderer) %>
-
-module Blacklight
-
-  class CommaLinkRenderer < WillPaginate::ViewHelpers::LinkRenderer
-    
-    protected
-    # Just overriding the page_number method, so that large numbers are 
-    # contain appropriate commas. 
-    def page_number(page)
-      unless page == current_page
-        text = @template.number_with_delimiter(page)
-        link(text, page, :rel => rel_value(page))
-      else
-        tag(:em, page)
-      end
-    end
-    
-  end
-end

data/lib/railties/jetty_solr_server.rb

@@ -1,108 +0,0 @@
-# -*- encoding : utf-8 -*-
-# The ASF licenses this file to You under the Apache License, Version 2.0
-# (the "License"); you may not use this file except in compliance with
-# the License.  You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-# A singleton class for starting/stopping a Solr server for testing purposes
-# The behavior of TestSolrServer can be modified prior to start() by changing 
-# port, solr_home, and quiet properties.
-
-class JettySolrServer
-  attr_accessor :port, :jetty_home, :solr_home, :quiet, :sleep_after_start, :pid
-
-  # configure the singleton with some defaults
-  def initialize(params = {})
-    @pid = nil
-    self.quiet = params.has_key?(:quiet) ? !!params[:quiet] : true
-    self.jetty_home = params[:jetty_home]
-    self.solr_home = params[:solr_home] || File.expand_path("./solr", self.jetty_home)
-    self.port = params[:jetty_port] || 8888
-    self.sleep_after_start = params[:sleep_after_start]
-  end
-
-  def wrap        
-    puts "JettySolrServer: starting server on #{RUBY_PLATFORM}"
-    self.start
-    begin
-      yield
-    ensure      
-      puts "JettySolrServer: stopping solr server"
-      self.stop
-    end
-  end
-  
-  def jetty_command
-    "java -Djetty.port=#{@port} -Dsolr.solr.home=#{@solr_home} -jar start.jar"
-  end
-  
-  def start
-    puts "\nexecuting: #{jetty_command}\n\n"
-    
-    platform_specific_start
-    
-    if self.sleep_after_start
-      puts "sleeping #{self.sleep_after_start}s waiting for startup."
-      sleep self.sleep_after_start
-    end
-  end
-  
-  def stop
-    platform_specific_stop
-  end
-  
-  if RUBY_PLATFORM =~ /mswin32/
-    require 'win32/process'
-
-    # start the solr server
-    def platform_specific_start
-      Dir.chdir(@jetty_home) do
-        @pid = Process.create(
-              :app_name         => jetty_command,
-              :creation_flags   => Process::DETACHED_PROCESS,
-              :process_inherit  => false,
-              :thread_inherit   => true,
-              :cwd              => "#{@jetty_home}"
-           ).process_id
-      end
-    end
-
-    # stop a running solr server
-    def platform_specific_stop
-      Process.kill(1, @pid)
-      Process.wait
-    end
-  else # Not Windows
-    
-    def jruby_raise_error?
-      raise 'JRuby requires that you start solr manually."' if defined?(JRUBY_VERSION)
-    end
-    
-    # start the solr server
-    def platform_specific_start
-      jruby_raise_error?
-      
-      Dir.chdir(@jetty_home) do
-        @pid = fork do
-          STDERR.close if @quiet
-          exec jetty_command
-        end
-      end
-    end
-
-    # stop a running solr server
-    def platform_specific_stop
-      jruby_raise_error?
-      Process.kill('TERM', @pid)
-      Process.wait
-    end
-  end
-
-end