blacklight 3.8.1 → 3.8.2

data/doc/Contributing-to-Blacklight.md

@@ -0,0 +1,25 @@
+# Contributing to Blacklight
+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 [[Blacklight mailing list|http://groups.google.com/group/blacklight-development]], just don't be shocked if we can't always give you the answer you want. We always welcome patch submissions; 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.
+
+If you follow this short guide, it will make it much easier for the community to review your changes, and the core team to get them included in the next release. If you are new to Git, be sure to read Github's (really good) [[step-by-step directions|http://help.github.com/fork-a-repo/]] for contributing to projects. If you want a basic introduction to git, check out [[Git Reference|http://gitref.org/]].
+
+We also encourage a lot of peripheral functionality -- especially for features that may not be used by most implementations, as the Blacklight install base has a wide range of users -- to consider developing stand-alone, optional [[Blacklight add-ons]].
+
+## Adding a ticket
+Let us know you're interested in working on a feature by filing a ticket in our [[issue tracker|https://github.com/projectblacklight/blacklight/issues]].  
+
+## Making Your Changes
+
+* Fork the project (Github has really good step-by-step directions
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so we don't break it in a future version unintentionally.
+* After making your changes, be sure to run the [[Blacklight rspec and cucumber tests|Testing]] to make sure everything works. 
+* Submit your change as a [[Pull Request|http://help.github.com/pull-requests/]].
+
+## Support
+If you are interested in working on the Blacklight plugin, but want guidance or support, please send an email to our [[Blacklight-development mailing list|http://groups.google.com/group/blacklight-development]] and we'll be glad to help.

data/doc/Examples.md

@@ -0,0 +1,62 @@
+You can see a demonstration of the generic Blacklight plugin at http://demo.projectblacklight.org
+
+Columbia University:
+
+* Academic Commons (Institutional Repository) - http://academiccommons.columbia.edu/
+* New Arrivals (Subset of OPAC) - http://newarrivals.cul.columbia.edu
+* Staff Collection Viewer (Internal only)
+* CLIO Beta (opac replacement + metasearch) - http://cliobeta.columbia.edu
+
+Agriculture Network Information Center
+http://www.agnic.org/search
+
+Historical State (NCSU Libraries)
+http://historicalstate.lib.ncsu.edu
+
+Johns Hopkins University Libraries (Catalyst)
+http://catalyst.library.jhu.edu
+
+Northwest Digital Archives
+http://nwda.projectblacklight.org
+
+Northwestern University Library Archival and Manuscript Collections
+http://findingaids.library.northwestern.edu
+
+NRM (Natural Resource Management) knowledge online
+http://nrmonline.nrm.gov.au/
+
+Rock & Roll Hall of Fame
+http://catalog.rockhall.com/
+
+Stanford University
+http://searchworks.stanford.edu
+
+University of Virginia
+http://search.lib.virginia.edu
+
+University of Wisconsin-Madison
+http://forward.library.wisconsin.edu/
+
+United States Holocaust Memorial Museum
+(Currently internal only; public instance soon)
+
+WGBH Open Vault
+http://openvault.wgbh.org
+
+NCSU Libraries' Digital Collections: Rare and Unique Materials
+http://d.lib.ncsu.edu/collections/
+
+University of Hull:
+
+* Institutional repository - http://hydra.hull.ac.uk
+* Library catalogue prototype - http://blacklight.hull.ac.uk/
+
+The UI component of the Hydra Framework - http://projecthydra.org
+
+The New York Public Library
+
+* Andre Studios 1930-1941 - http://andrestudios.nypl.org 
+
+## Media/Presentations
+
+* ["Highly Relevant Search Result Ranking for Large Law Enforcement Information Sharing Systems"](http://www.lucidimagination.com/blog/2011/06/01/solr-and-law-enforcement-highly-relevant-results-can-be-a-crime/), presented by Ronald Mayer of Forensic Logic at Lucene Revolution 2011 - Blacklight was used to quickly provide a proof-of-concept on law enforcement data.

data/doc/Extending-or-Modifying-Blacklight-Search-Behavior.md

@@ -0,0 +1,141 @@
+# Extending or Modifying Blacklight Search Behavior
+
+Solr parameters used by for a given request can come from several different places. 
+
+* Solr request handler: `solrconfig.xml` in your solr config
+* Application logic: logic in the BL rails app itself
+
+## Solr request handler
+
+The Solr [[Request Handlers|http://wiki.apache.org/solr/SolrRequestHandler]] may be configured in the [[solrconfig.xml|http://wiki.apache.org/solr/SolrConfigXml]] and are baked into the request handler itself. Depending on how you have blacklight configured, your app may be using the same Solr request handler for all searches, or may be using different request handlers for different "search fields".  
+
+The request handler is often set up with default parameters:
+
+```xml
+  <requestHandler name="standard" class="solr.SearchHandler" >
+     <lst name="defaults">
+       <str name="echoParams">explicit</str>
+       <str name="rows">10</str> 
+       <str name="fl">*</str>   
+       <str name="facet">true</str>
+       <str name="facet.mincount">1</str>
+       <str name="facet.limit">30</str> 
+       <str name="facet.field">access_facet</str>
+       <str name="facet.field">author_person_facet</str>
+       <str name="facet.field">author_other_facet</str>
+       <str name="facet.field">building_facet</str>
+       <str name="facet.field">callnum_1_facet</str>
+       <str name="facet.field">era_facet</str>
+       <str name="facet.field">format</str>
+       <str name="facet.field">geographic_facet</str>
+       <str name="facet.field">language</str>
+       <str name="facet.field">pub_date_group_facet</str>
+       <str name="facet.field">topic_facet</str>
+     </lst>
+  </requestHandler>
+```
+## Configuration
+
+The default application logic (explained below) looks in configuration for things like the name of a the solr request handler to use, and default request parameters to send on every solr search request (or with every request from a certain blacklight search type/field). An example getting started configuration is generally installed into your app when you install Blacklight at `[[./app/controllers/catalog_controller.rb|https://github.com/projectblacklight/blacklight/blob/master/lib/generators/blacklight/templates/catalog_controller.rb]]`.
+
+## Application logic
+
+The logic Blacklight uses to determine how to map user-supplied parameters into Solr request parameters for a given application request is in the [[#solr_search_params method in the SolrHelper module|https://github.com/projectblacklight/blacklight/blob/master/lib/blacklight/solr_helper.rb#L76]]. Note that `[[CatalogController|https://github.com/projectblacklight/blacklight/blob/master/app/controllers/catalog_controller.rb]]` extends `[[SolrHelper|https://github.com/projectblacklight/blacklight/blob/master/lib/blacklight/solr_helper.rb]]`, so the `SolrHelper` methods become available in the `CatalogController` (and other controllers, if they extend `SolrHelper` too). 
+
+Behind the scenes, #solr_search_params uses the `class_inheritable_accessor` method [[solr_search_params_logic|https://github.com/projectblacklight/blacklight/blob/master/lib/blacklight/solr_helper.rb#L30]]. solr_search_params_logic is essentially a class variable that is mixed into the CatalogController and provides an ordered list of methods to call that may inspect the supplied user parameters and add, remove, or modify the Solr request parameters that will be sent to an [[RSolr|https://github.com/mwmitchell/rsolr/]] object, which in turn will convert the hash into query parameters for a Solr request. One confusing thing is that RSolr and  [[RSolr-ext|https://github.com/mwmitchell/rsolr-ext]] provide their own mappings from certain custom terms to Solr-recognized request parameters. For instance, a `:per_page` key in that hash will get mapped to the Solr `&rows` parameter -- but a `:rows` key will also.  Blacklight developers have found that using these special RSolr "aliases" leads to confusion, as well as confusing bugs (if both `:per_page` and `:rows` are set in the hash, what happens can be hard to predict).  So we try to avoid using the special RSolr aliases, and just use ordinary Solr parameters in our hashes. But you may encounter older code that uses the RSolr aliases. 
+
+There can be similar confusing behavior or bugs if one piece of code adds a key to a `Hash` using a `Symbol`, but another piece of code looks for and/or adds that same key to the `Hash` using a `String` instead. RSolr happens to accepts either one, but if both are present RSolr behavior can be unexpected. And even before it gets to RSolr, you may have code that thinks it replaced a key but did not becuase it was using the wrong form. Blacklight developers have agreed to try and always use `Symbol` based keys in hashes meant for Solr parameters, to try and avoid these problems. Longer term, we could probably make some code changes to make this kind of error less likely. 
+
+The default `#solr_search_params_logic` is meant to handle very common cases and patterns based on simple configuration options from the controller and the user-supplied URL parameters.
+
+* `[[blacklight_config.default_solr_params|https://github.com/projectblacklight/blacklight/blob/master/lib/generators/blacklight/templates/catalog_controller.rb#L9]]`
+    * Default params sent to solr with every search, including the default :qt param, which determines which Solr request handler will be targetted. Some people like to use solrconfig.xml request handler defaults exclusively, and include only a :qt here; others find it more convenient to specify some defaults at the application level here. 
+* `[[blacklight_config.search_fields|https://github.com/projectblacklight/blacklight/blob/master/lib/generators/blacklight/templates/catalog_controller.rb#L81]]`
+   * Each search field will be presented in a select menu in the BL user interface search box. These 'search fields' don't neccesarily correspond 1-to-1 with Solr fields. What they instead correspond to is Solr parameter over-rides that will be used for this BL UI search field.  Those over-rides are present here. 
+   * You could simply chose a different `:qt` Solr request handler for each search field, which has it's own default parameters in the sorlconfig.xml. This is what we started out doing with Solr, but found it led to much duplication of information in solrconfig.xml. 
+   * You can continue using the same Solr request handler, but simply specify different parameters which will be included in the http query string sent to Solr here, with the `:solr_parameters`  key. This works fine, but some people don't like how it makes your Solr requests much longer/more complex in the Solr logs; and/or they prefer to control this Solr side instead of Application side. 
+   * For the best of both worlds, although it's a bit confusing at first, you can use the `:solr_local_parameters` key to have parameters supplied to Solr using the Solr [[LocalParams|http://wiki.apache.org/solr/LocalParams]] syntax, which means you can use "parameter dereferencing"  with dollar-sign-prefixed references to variables defined in solrconfig.xml request handler. This is what the current example BL setup does. 
+
+So the default implementation of `#solr_search_params` takes these configured parameters, combines them with certain query parameters from the current users HTTP request to the BL app, and prepares a Hash of parameters that will be sent to solr. For common use patterns, this is all you need. 
+
+But sometimes you want to add some custom logic to `#solr_search_params` to come up with the solr params Hash in different ways. Typically to support a new UI feature of some kind, either in your local app or in a Blacklight add-on plugin you are developing. 
+
+
+# Extending Blacklight::SolrHelper#solr_search_params
+
+To add new search behaviors (e.g. authorization controls, pre-parsing query strings, etc), the easiest route is to add additional steps to the `#solr_search_params_logic`, either at the beginning of the list (to set default parameters) or at the end of the list (to force particular parameters). Because `#solr_search_params_logic` is just an ordinary array, you may perform any normal array operation (e.g. push/pop/delete/insert) to customize the parameter generation to meet your needs.
+
+`#solr_search_params_logic` steps take two inputs, the hash of `solr_parameters` and the hash of `user_parameters` (often provided by the URL parameters), and modifies the `solr_parameters` directly, as needed. 
+
+You can add custom solr_search_params_logic steps within your controller (or in many other places, including initializers, mixins, etc) by adding a Symbol with the name of a method (provided by the controller) you wish to use, e.g.:
+
+*./config/initializers/blacklight_config.rb*
+
+```ruby
+class CatalogController
+  self.solr_search_params_logic += :show_only_public_records
+end
+```
+The controller must provide the method added to `solr_search_params_logic`, in this case `show_only_public_records`. It is often convenient to do this in a separate `Module` and include it into the controller:
+
+*./app/controllers/catalog_controller.rb*
+
+```ruby
+require 'blacklight/catalog'
+class CatalogController < ApplicationController 
+  include Blacklight::Catalog
+  include MyApplication::SolrHelper::Authorization
+  
+  # Instead of defining this within an initializer, you may instead wish to do it on the controller directly:
+  # self.solr_search_params_logic << :show_only_public_records
+
+  # You could also define the actual method here, but this is not recommended.
+  # def show_only_public_records solr_parameters, user_parameters
+  #  [...]
+  # end
+end
+```
+
+The included module then defines the logic method:
+ 
+*./lib/my_application/solr_helper/authorization.rb*
+
+```ruby
+module MyApplication::SolrHelper::Authorization
+#  You could also add the logic here
+#  def self.included base
+#    base.solr_search_params_logic << :show_only_public_records
+#  end
+
+  # solr_search_params_logic methods take two arguments
+  # @param [Hash] solr_parameters a hash of parameters to be sent to Solr (via RSolr)
+  # @param [Hash] user_parameters a hash of user-supplied parameters (often via `params`)
+  def show_only_public_records solr_parameters, user_parameters
+    # add a new solr facet query ('fq') parameter that limits results to those with a 'public_b' field of 1 
+    solr_parameters[:fq] ||= []
+    solr_parameters[:fq] << 'public_b:1'
+  end
+end
+```
+
+## Other examples
+
+In addition to providing this behavior locally, some Blacklight plugins also extend the `#solr_search_params`:
+
+* [[Blacklight Range Limit|https://github.com/projectblacklight/blacklight_range_limit/blob/master/lib/blacklight_range_limit/controller_override.rb]]
+
+* A walk through on adding a checkbox limit at: http://bibwild.wordpress.com/2011/06/13/customing-blacklight-a-limit-checkbox/
+
+* A much more complicated walk-through on adding an 'unstemmed search' checkbox limit: http://bibwild.wordpress.com/2011/06/20/customizing-blacklight-disable-automatic-stemming/
+
+## Suppressing search results
+
+You can configure your `solrconfig.xml` to not show results based on fields in your solr document.  For example, if you have a solr boolean field such as `show_b`, you can suppress any records that have this field present.  To do so, add:
+```
+<lst name="appends"><str name="fq">-show_b:["" TO *]</str></lst>
+```
+to the request handler in your `solrconfig.xml` file.  If you would like this to be for standard solr searches, add the above line to this request handler:
+```
+<requestHandler name="search" class="solr.SearchHandler" default="true">
+```
+By doing so, solr queries that use the "document" request handler will still give you any records with the show_b field, but solr queries with the "search" handler will not.

data/doc/Home.md

@@ -0,0 +1,77 @@
+#
+[[https://github.com/projectblacklight/projectblacklight.github.com/raw/master/images/logo.png]]
+
+## Introduction
+
+Blacklight is an open source, Ruby on Rails engine/gem that provides a discovery interface for  [Apache Solr](http://lucene.apache.org/solr). Blacklight provides a basic user interface with a search box, facet constraints, stable document urls, etc., all of which is customizable via Rails (templating) mechanisms.  Blacklight accommodates heterogeneous data, allowing different information displays for different types of objects. 
+
+Some other features include:
+
+* Stable URLs for search and record pages allow users to bookmark, share, and save search queries for later access
+* Every Blacklight search provides RSS and Atom Responses of search results
+* For certain types of solr documents, an OpenURL/Z39.88 COinS object is embedded in each document, which allows plugins like Zotero to easily extract data from the page.
+* Blacklight supports OpenSearch, a collection of simple formats for the sharing of search results.
+* Faceted searching
+* Search queries can be targeted at specific sets of fields
+* Results sorting
+* Tools for exporting records to Refworks or Endnote, sending records via Email or SMS, or as a formatted citation.
+
+A [demo application](http://demo.projectblacklight.org) uses the latest version of Blacklight to display a basic library catalog.
+
+> NOTE: This wiki provides developer documentation for the latest Blacklight release. For documentation of older releases, see the end of this page.
+
+## Getting Started
+* [[Quickstart Guide|Quickstart]]
+* [[Site Search|http://projectblacklight.org/search.html]]
+* [[Demo|http://demo.projectblacklight.org]]
+* [[Example installations|Examples]]
+* [[Release Notes And Upgrade Guides]]
+
+
+## Developing your application
+* [[Blacklight Configuration]]: Search results, facets, query fields
+* [[Providing your own view templates]]: Overriding the out-of-the-box Blacklight templates the Rails way.
+* [[User Authentication]]: Connecting Blacklight with an existing Authentication system
+* [[Extending or Modifying Blacklight Search Behavior]] How to change the way the Blacklight discovery feature works.
+* [[Internationalization]]: Translating (or simply customizing) the Blacklight copy
+* [[Common Blacklight Patterns]]
+* [[Indexing your data into Solr]]
+* [[Additional Blacklight-specific Solr documentation|README_SOLR]]
+* [[Blacklight on Heroku]]
+* [[Pagination]]: Advise on how to customize pagination with Kaminari
+
+
+## Support
+Don't be scared to ask a question on the [[Blacklight mailing list|http://groups.google.com/group/blacklight-development]]. 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. 
+
+Some Blacklight developers aso 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. [[http://freenode.net/faq.shtml]].
+
+* [[Bug Tracker|https://github.com/projectblacklight/blacklight/issues/]]
+* [[Mailing List|http://groups.google.com/group/blacklight-development]]
+* [[Jenkins Continuous Integration|http://hudson.projectblacklight.org]]
+
+## Contributing to Blacklight
+
+* [[Contributing to Blacklight]]
+* [[Community Principles]]
+* [[How to release a version]]
+* [[Testing]]
+
+## Releases
+Blacklight releases are published on the [[Rubygems.org blacklight project|https://rubygems.org/gems/blacklight]].
+
+For a list of features and bugfixes in Blacklight releases, see the [[Release announcements|Release Notes And Upgrade Guides]] on this wiki.
+
+### Older Documentation
+This wiki provides developer documentation for the ```master``` branch of Blacklight, which may include documentation of features not present in every Blacklight version. For documentation of specific Blacklight releases, see also:
+
+* [[Home]]
+* [[Blacklight 3.x|https://github.com/projectblacklight/blacklight/tree/release-3.8/doc]]
+* [[Blacklight 3.0 or 3.1|https://github.com/projectblacklight/blacklight/tree/release-3.1/doc]]
+* [[Blacklight 2.x|https://github.com/projectblacklight/blacklight/tree/v2.9-frozen/doc]] for all Blacklight 2.x releases; version-specific documentation is also available:
+    * [[Blacklight 2.7|https://github.com/projectblacklight/blacklight/tree/v2.7.0/doc]]
+    * [[Blacklight 2.6|https://github.com/projectblacklight/blacklight/tree/v2.6.0/doc]]
+    * [[Blacklight 2.5|https://github.com/projectblacklight/blacklight/tree/v2.5.0/doc]]
+    * [[Blacklight 2.4|https://github.com/projectblacklight/blacklight/tree/v2.4.2/doc]]

data/doc/How-to-release-a-version.md

@@ -0,0 +1,37 @@
+Before releasing, ensure that you're on the master branch.  Run all  tests and ensure that they pass. Also check the [[hudson site|http://hudson.projectblacklight.org/hudson/]] to make sure tests are passing.
+    ```bash
+    $ ./test_support/bin/test.sh 
+    ```
+
+1.  Create a release branch, wit the format release-{major}.{minor}
+    ```bash
+    $ git checkout -b release-{major}.{minor}
+    # Switched to a new branch 'release-{major}.{minor}'
+    ```
+
+1. Update the version number in ./VERSION
+    ```
+    {major}.{minor}.{patch}
+    ```
+
+1. Update the links in the readme files to point at the correct version so we're not linking to the documents in master which may not be correct for the specific tagged release (change "master" to version number)
+
+1. Fix GitHub issue tracker to know about the release
+      * Create a milestone in GitHub for the NEXT version.
+      * Move any open tickets for released version to the next version.
+      * Mark the milestone as released.
+
+1. Write an upgrade guide for [[Release Notes And Upgrade Guides]].
+
+1. Prepare announcement
+  * Include URL to GitHub closed issues for version 
+  * Include URL to github commits between tags. github can show all commits between two versions with a URL of this form: [[http://github.com/projectblacklight/blacklight/compare/v2.5.0...v2.6.0]]  Replace with previous version and current release version tags. 
+  * Include URL to the Github wiki [[Release Notes And Upgrade Guides]].
+
+1. Release the gem 
+```bash
+$ rake release
+```
+
+1. Announce
+  * Write emails announcing the release to Blacklight Development 

data/doc/Indexing-your-data-into-solr.md

@@ -0,0 +1,5 @@
+Blacklight uses Solr as its data index. Blacklight is agnostic as to how that Solr index gets populated. Many Blacklight contributors work in university libraries and have to deal with library data in the MARC format. The Blacklight out-of-the-box demo and test suite is geared towards that use case.
+
+## What’s the relationship between Blacklight and SolrMarc?
+
+However, one excellent way to index lots of MARC records into Solr quickly is to use SolrMarc. Some of the same people are active in both projects, e.g, Bob Haschart from UVA and Naomi Dushay from Stanford University. SolrMarc is not a Blacklight-specific project, it is also used by VuFind and other projects, and is a separate project that exists in its own right.

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

@@ -0,0 +1,20 @@
+[[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

@@ -0,0 +1,38 @@
+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/Providing-your-own-view-templates.md

@@ -0,0 +1,109 @@
+> TODO: Validate this page for Blacklight 4.x!
+
+# Customizing the User Interface
+## Layouts 
+
+The built-in Blacklight controllers all by default use a Rails view layout called "blacklight", that lives in the Blacklight source. This ends up being a bit confusing, but is the best way we have at present to have out of the box default using a layout with full functionality, without stepping on a possibly existing local 'application' layout. 
+
+To change what layout the Blacklight controllers use, simply implement a method #layout_name in your local application_controller.rb that returns the name of the layout you'd like them to use. 
+
+```ruby
+# [from app/controllers/application_controller.rb]
+class ApplicationController < ActionController::Base
+  ...
+    def layout_name
+       "application"
+    end
+  ...
+end
+```
+
+When implementing your own layout instead of using the stock one, you may want to look at the Blacklight app/views/layouts/blacklight.html.erb file to see what helper methods are called there, to maintain full Blacklight functionality you may want to call these same helper methods. 
+
+* `render_head_content` renders content within the
+  html `<head>` tag, which includes document-specific alternative
+formats as well as tags generated by plugins, etc.
+* `sidebar_items` renders features including sidebar content, e.g. facet
+  lists.
+* flash messages
+* user util links
+
+## Overriding Views (templates and partials)
+As a Rails Engine, you can easily override views in your app. You can see what views and partials are provided by looking in `[[./app/views|https://github.com/projectblacklight/blacklight/tree/master/app/views]]` inside the Blacklight source.
+
+Once you find the view you'd like to change, you should create a file with the same name and relative path in your own application (e.g. if you wanted to override [[./app/views/catalog/_show_partials/_default.html.erb|https://github.com/projectblacklight/blacklight/blob/master/app/views/catalog/_show_partials/_default.html.erb]] you would create ./app/views/catalog/_show_partials/_default.html.erb in your local application. Frequently, you will start by copying the existing Blacklight view and modifying it from there.
+
+It is generally recommended that you override as little as possible, in order to maximize your forward compatibility. Look to override either a small, focused partial template, or a helper method of partial template called from a larger template, so your application's version can call out to those same helpers or partial templates within blacklight core code. 
+
+## Overriding the CatalogController
+Overriding the Blacklight `CatalogController` implementation is easy, and the skeleton of the `CatalogController` is generated into your application for you when you install Blacklight. 
+
+See the [[Extending or Modifying Blacklight Search Behavior]] for tips and approaches to customizing the catalog.
+
+## Overriding Other Controllers
+
+1. Find the controller you're interested in blacklight's app/controllers/  . 
+2. Create a file with the same name in your local app/controllers. 
+3. This file requires the original class, and then re-opens it to add more methods.
+ 
+```ruby
+require "#{Blacklight.controllers_dir}/some_controller"
+
+class SomeController < ApplicationController
+   # custom code goes here
+end
+```
+
+In that "custom code goes here", you can redefine certain methods (action methods or otherwise) to do something different.  You can also add new methods (again action methods or otherwise), etc. 
+
+It's kind of hard to call 'super' to call original functionality: 
+
+* the ruby language features here make 'super' unavailable, although you can work around that confusingly with the rails #alias_method_chain method. 
+* but more importantly, action methods in particular don't really suit themselves to being over-ridden and called by super, because the original implementation often does something you'd want to change but there's no easy way to 'undo' -- calling 'render', which can only be called once. 
+
+So basically, if you find yourself wanting to access some functionaltiy in the original implementation of a method that you also want to over-ride -- the best solution is probably to refactor Blacklight core code to put that functionality in a subsidiary method, so you can over-ride the action method entirely but call that logic from core.  Action methods should be short and sweet anyway. 
+
+
+## Custom View Helpers
+
+(This is accurate for Blacklight 3.1.1 and subsequent. Before that, things were messier). 
+
+One of the most common things you might need to do is create a view helper -- especially to override some Blacklight behavior implemented in it's own view helpers. The first step is looking at Blacklight source to determine what view helper method you want to override. 
+
+Blacklight comes packaged with several view helper modules. There is a BlacklightHelper in (blacklight source) app/helpers/blacklight_helper.rb , and several others that correspond to specific controller. (Note, depending on version of Rails and configuration, all helpers may get loaded for every request, even ones that are named to correspond only to a particular other controller). 
+
+If you simply created a local helper with the same name as a helper in Blacklight, that will end up preventing the Blacklight helper from being loaded at all though, which is not what you want to do to override. 
+
+We've structured each Blacklight view helper module into two parts to make it easy to selectively over-ride methods. For instance, here's Blacklight's app/helpers/blacklight_helper.rb:
+
+```ruby
+module BlacklightHelper
+  include Blacklight::BlacklightHelperBehavior
+end
+```
+
+Now, the actual methods will be found in app/helpers/blacklight/blacklight_helper_behavior.rb instead. 
+
+If you want to over-ride a helper method, copy the wrapper blacklight_helper into your local app, with the 'include' line, and now you can individually over-ride methods from BlacklightHelperBehavior, and the other methods you don't over-ride will still have their default implementation. 
+
+YOUR `app/helpers/blacklight_helper.rb`
+
+```ruby
+module BlacklightHelper
+  include Blacklight::BlacklightHelperBehavior
+
+  def application_name
+    "Bestest University Search"
+  end
+end
+```
+
+One helper you might want to over-ride for customization is #render_document_partial (currently defined in [[blacklight_helper|https://github.com/projectblacklight/blacklight/blob/master/app/helpers/blacklight_helper.rb]]), which you can over-ride to choose differnet local partial views to display a document on search results or detail page, possibly varying depending on type of document according to your own local logic. 
+
+## Adding in your own CSS or Javascript
+
+Within your local application, you can use the [[Rails Asset Pipeline|http://guides.rubyonrails.org/asset_pipeline.html]] to manipulate javascript and css documents.
+
+**todo??** better instructions for over-riding BL's built in CSS using SASS? (jrochkind thought jamesws wrote such already, but can't find them now)
+
+The Blacklight generator added a file to your app at `./app/assets/stylesheets/blacklight_themes/standard.css.scss`, elements of the BL default theme can be customized or over-ridden there. If there's something you want to do but aren't sur e the best way, feel free to ask on the listserv.