blacklight 5.9.4 → 5.10.0

data/doc/Saved-Searches.md

@@ -1,5 +0,0 @@
-Blacklight search URLs are stable and can be bookmarked using any browser or third-party bookmark manager.
-
-Blacklight also tracks search history in the scope of a session. Searches can be also be permanently persisted for a user.
-
- 

data/doc/Solr-Configuration.md

@@ -1,154 +0,0 @@
-# Blacklight configuration
-
-The example Blacklight configuration is a simple application for displaying library holdings. In this section, we will describe the Blacklight configuration settings that determine how the Blacklight interface works with your data.
-
-## Connecting to Solr
-
-The Solr connection parameters are configured globally in `config/solr.yml`. It looks something like this:
-
-```yaml
-# config/solr.yml
-development:
-  url: <%= ENV['SOLR_URL'] || "http://127.0.0.1:8983/solr" %>
-test: &test
-  url: <%= "http://127.0.0.1:#{ENV['TEST_JETTY_PORT'] || 8888}/solr" %>
-```
-
-The configuration is used to configure [RSolr::Client](https://github.com/rsolr/rsolr/blob/master/lib/rsolr/client.rb). Available options include:
-
-* url
-* proxy
-* open_timeout
-* read_timeout
-* retry_503
-* retry_after_limit
-
-### Dynamic configuration
-
-
-Blacklight pre-parses the YAML file using ERB, which means you can use environment variables to configure the Solr location. With the default configuration, this means you can start Blacklight and point it at an external solr index without changing the `solr.yml` file:
-
-```console
-$ SOLR_URL="http://my.production.server/solr/core/" rails server
-```
-
-### Run-time configuration
-
-The `solr.yml` configuration is applied globally to all Solr connections from your application. If you need to configure dynamic (e.g. per-user or per-controller) connections, Blacklight provides and uses instance-level accessor methods. Applications can override these accessors in By overriding these accessors, applications can provide either custom RSolr clients (e.g. [rsolr-async](https://github.com/mwmitchell/rsolr-async)) or per-user or per-controller solr connections:
-
-```ruby
-class CatalogController < ApplicationController
-  include Blacklight::Catalog
-  include MyApplicationRuntimeConfiguration
-end
-
-module MyApplicationRuntimeConfiguration
-  def solr_repository
-    @solr_repository ||= MyCustomSolrRepository.new(blacklight_config)
-  end
-end
-
-class MyCustomSolrRepository < Blacklight::SolrRepository
-  def blacklight_solr
-    @blacklight_solr ||= RSolr::Custom::Client.new :user => current_user.id
-  end
-end
-```
-
-
-## Solr Configuration
-
-### Schema
-
-
-#### Solr Unique Key
-
-If your solr configuration uses a unique field other than `id`, you must configure your `SolrDocument` (in app/models/solr_document.rb) to set the unique key:
-
-```ruby
-# app/models/solr_document.rb
-
-class SolrDocument
-  include Blacklight::Solr::Document
-
-  self.unique_key = 'my_unique_key_field'
- 
-  ...
-end
-```
-
-### Blacklight search requests
-
-[Search Handler](http://wiki.apache.org/solr/SearchHandler)
-
-Blacklight configuration parameters to directly add solr request parameters:
-* default_solr_params
-* qt
-* solr_path
-* document_solr_request_handler
-* document_solr_path
-* document_unique_id_param
-* default_document_solr_params
-
-### Request handlers
-
-Blacklight supports rapid application development by allowing you to configure Blacklight to send every parameter in every solr request. One of the ways to productionize this is to move the static logic into Solr request handlers. [Request Handlers](http://wiki.apache.org/solr/SolrRequestHandler) are configured in the [solrconfig.xml](http://wiki.apache.org/solr/SolrConfigXml). 
-
-Request handler parameters can be configured three different ways:
-
-* defaults - provides default param values that will be used if the param does not have a value specified at request time.
-* appends - provides param values that will be used in addition to any values specified at request time (or as defaults.
-* invariants - provides param values that will be used in spite of any values provided at request time. They are a way of letting the Solr maintainer lock down the options available to Solr clients. Any params values specified here are used regardless of what values may be specified in either the query, the "defaults", or the "appends" params.
-
-Here is an example request handler demonstrating all types of configuration:
-
-```xml
-  <requestHandler name="standard" class="solr.StandardRequestHandler">
-     <lst name="defaults">
-       <!-- assume they want 50 rows unless they tell us otherwise -->
-       <int name="rows">50</int>
-       <!-- assume they only want popular products unless they provide a different fq -->
-       <str name="fq">popularity:[1 TO *]</str>
-     </lst>
-    <lst name="appends">
-      <!-- no matter what other fq are also used, always restrict to only inStock products -->
-      <str name="fq">inStock:true</str>
-    </lst>
-    <lst name="invariants">
-      <!-- don't let them turn on faceting -->
-      <bool name="facet">false</bool>
-    </lst>
-
-  </requestHandler>
-```
-
-
-#### Document request handler
-
-In addition to the search request handler, we strongly encourage you to configure a request handler for retrieving single documents. This request handler can be highly optimized to remove unnecessary parameters and processing, makes it easier to understand the Solr request log, and allows you to easily change request parameters for search and single-item behaviors separately.
-
-The blacklight document request handler looks like this:
-
-```xml
-<requestHandler name="document" class="solr.SearchHandler" >
-  <lst name="defaults">
-    <str name="echoParams">all</str>
-    <str name="fl">*</str>
-    <str name="rows">1</str>
-    <bool name="facet">false</bool>
-    <str name="q">{!raw f=id v=$id}</str> <!-- use id=666 instead of q=id:666 -->
-  </lst>
-</requestHandler>
-```
-
-If you're using Solr 4.0+, you may also consider using the [Solr Real-Time Get](https://cwiki.apache.org/confluence/display/solr/RealTime+Get) request handler.
-
-```xml
-<requestHandler name="/get" class="solr.RealTimeGetHandler">
-  <lst name="defaults">
-    <str name="omitHeader">true</str>
-    <str name="wt">json</str>
-    <str name="indent">true</str>
-  </lst>
-</requestHandler>
-```

data/doc/Sunspot-for-indexing.md

@@ -1,46 +0,0 @@
-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/Support.md

@@ -1,33 +0,0 @@
-## Context
-
-Blacklight is a collaborative open source project by developers at various institutions, which we each work on largely motivated by our own local institutions' needs. We work on the shared project together so we can benefit from each other's code, but most developers primary priorities are to their own local development. In this it is like many such projects.
-
-The Blacklight developers do want to create a product that is easy for newcomers to install and get started with -- both as a service to the community and in the interests of our own institutions in creating a sustainable project and product that continue to thrive through personnel changes. However, the developers may not always have time to find or fix bugs that may be affecting you, or lead you through every detail of getting Blacklight to work for you.
-
-But we do try when we can -- please don't be scared to ask a question on the listserv, just don't be shocked if we can't always give you the answer you want.  We always welcome patches; and we are always excited to hear about what others are doing with Blacklight. We're also always looking for more committers, although we usually like to see a patch or two before considering granting committer status.
-
-## Wiki
-
-Some guides are available on this wiki, including installation instructions. We hope the wiki documentation will continue to expand and improve. If you figure something out that wasn't already in the wiki, please feel free to edit or add a wiki page on it to help those who come after you.  If there's something you think needs documenting but you aren't sure you understand it well enough to document it, feel free to add a note to that effect in the wiki too, as a stub.
-
-## Code-level documentation
-
-Auto-generated code-level API documentation is available at: [http://rdoc.info/github/projectblacklight/blacklight](http://rdoc.info/github/projectblacklight/blacklight).
-
-## Mailing list
-
-The blacklight listserv can be found at: [http://groups.google.com/group/blacklight-development](http://groups.google.com/group/blacklight-development).
-
-Searching the archives might be helpful.
-
-Don't be scared to ask a question on the list. We appreciate you checking the documentation first and asking an educated question, but don't beat your head against the wall -- sometimes the existing documentation may be out of date and inaccurate.
-
-In order to reduce spam, the first time you post your email will be held in a moderation queue, but as soon as your first message is approved your posts won't be held for moderation any longer. (Is this really true on the google groups hosted list? Not sure.)
-
-## IRC channel
-
-Some Blacklight developers hang out on  our IRC channel, usually during North American office hours. On chat.freenode.net, channel #blacklight.  Stop in and say hi, we're happy to help with questions when we have time.
-
-## The Code
-
-Blacklight code is hosted on GitHub, which provides a pretty impressive web GUI for browsing the code and revision history. 

data/doc/Theming.md

@@ -1,62 +0,0 @@
-# Theming Blacklight
-
-
-Blacklight uses the [[Twitter Bootstrap|http://twitter.github.com/bootstrap]] framework for styling the out-of-the-box UI. While there is some Blacklight-specific customizations, most (if not all) the "styling" (colors, fonts, etc) are handled by Bootstrap.
-
-## Bootswatches
-
-One approach to styling Bootstrap-based sites is using "bootswatches", which are simple bootstrap themes that override SASS variables, mixins and declarations.
-
-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 'blacklight/blacklight';
-```
-
-To add the one of the bootswatch themes ('cerulean' in this example):
-
-```css
-@import "bootswatch/cerulean/variables";
-
-@import "bootstrap";
-
-@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 "bootswatch";
-
-@import 'blacklight/blacklight'
-```

data/doc/Understanding-Rails-and-Blacklight.md

@@ -1,75 +0,0 @@
-# Understanding Rails
-
-In order to understand how Blacklight works, you should have a basic knowledge about how Rails works. In the previous section, we offered resources to develop a general understanding of Rails. In this section, we'll look at the most important concepts that contribute to the way Blacklight functions.
-
-Blacklight is packaged as a [Rails Engine](http://guides.rubyonrails.org/engines.html), which means it is a Ruby gem that provides functionality to a Rails application, including functionality, javascript and css assets, etc. Installing Blacklight is as simple as adding the Blacklight gem to your Rails application's gemfile, and running the included `blacklight:install` generator (see Installing).
-
-## Controllers
-
-Blacklight generates a `CatalogController` into your application. This controller adds discovery and single-item "show" actions. This controller is where you can perform the majority of your Blacklight configuration and customization. The configuration options are discussed in future chapters. 
-
-Blacklight also provides several controllers to the host application. These controllers respect the `CatalogController` configurations.
-
-> Engine model and controller classes can be extended by open classing them in the main Rails application (since model and controller classes are just Ruby classes that inherit Rails specific functionality). 
-
-
-## Models
-
-As with the `CatalogController` above, Blacklight generates a `SolrDocument` model into your application. This model is used to translate Solr response documents into Rails models. Unlike many Rails models, the `SolrDocument` is not backed by an ActiveRecord row, but is merely a read-only, Ruby-friendly  representation of Solr's response.
-
-Within the `SolrDocument` model, you can provide custom model methods, accessors, and behaviors to the documents returned from Solr.
-
-The `SolrDocument` also provides an extension framework for conditionally adding additional behavior to documents. The extension framework is discussed in greater detail later.
-
-
-## Views
-
-Blacklight views can by customized by simply creating a new view within your application with the same name as the Blacklight view you want to override. If you wanted to override the view provided by the Blacklight `app/views/catalog/_per_page_widget.html.erb` partial, you could create the file `app/views/catalog/_per_page_widget.html.erb` in your own application. 
-
-> When Rails looks for a view to render, it will first look in the app/views directory of the application. If it cannot find the view there, then it will check in the app/views directories of all engines which have this directory.
-
-## Layout
-
-Blacklight provides a generic layout to the application. 
-
-If you're integrating Blacklight into an existing Rails application, 
-Blacklight also expects the host application's layout to be responsible for rendering Rails flash messages and a shared Bootstrap modal. In addition, the layout should include:
-
-A place for Blacklight views (and, mainly, plugins) to inject content into the <head>:
-
-```erb
-<head>
-...
-<%= content_for(:head) %>
-...
-</head>
-```
-
-The layout should also provide a Bootstrap container and row wrapper:
-
-```erb
-<div class="container">
-...
-<div class="row">
-<%= yield %>
-</div>
-</div>
-```
-
-
-## Routes
-
-Many Rails engines are "mounted" and are entirely isolated from the main application's routes. Blacklight routes, however, are injected directly into your application. Blacklight routes are added by a generator, and add this line to your `config/routes.rb`.
-
-```ruby
-blacklight_for :catalog
-```
-
-Mostly legacy. Allows for some greater flexibility.
-
-## Assets
-
-Blacklight adds assets to your application. Pick-and-choose, or override. Javascript is implemented using a pluggable approach, which we hope provides an easy way to customize behavior.
-
-
-## Locales and i18n

data/doc/User-Authentication.md

@@ -1,60 +0,0 @@
-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/_Sidebar.md

@@ -1,9 +0,0 @@
-[[https://github.com/projectblacklight/projectblacklight.github.com/raw/master/images/logo.png]]
-
-[[Quickstart Guide|Quickstart]]
-
-[[Site Search|http://projectblacklight.org/search.html]]
-
-[[Demo|http://demo.projectblacklight.org]]
-
-[[Example installations|Examples]]