blacklight 4.9.0 → 5.0.0.pre1

data/doc/Blacklight-3.8-release-notes-and-upgrade-guide.md

@@ -1,11 +0,0 @@
-This is primarily a release to bring the Blacklight 3.x line up to feature-parity with the upcoming bootstrap release, and contains backports of features and bugfixes from the bootstrap work.
-
-Highlights include:
-
-- pulling bookmark data from solr (rather than a database-backed title cache)
-- clean-up of some pagination code 
-- pruning dead code around folders (removed in the 3.7 release)
-
-And more:
-
-[[https://github.com/projectblacklight/blacklight/compare/v3.7.2...v3.8.0]]

data/doc/Blacklight-4.0-release-notes-and-upgrade-guide.md

@@ -1,135 +0,0 @@
-# Blacklight 3.6 Release Notes And Upgrade Guide
-
-## Release Notes
-
-- Remove dependency on RSolr::Ext. In this first stage, some RSolr::Ext code is now maintained in Blacklight, e.g.:
-     - RSolr::Ext::Response::Facets => Blacklight::SolrResponse::Facets
-     - RSolr::Ext::Doc => Blacklight::Solr::Document
-     - etc
-
-- Bootstrap-based view templates and default stylesheet; removed compass/susy 
-- Drop support for Ruby 1.8; add support for Ruby 2.0 
-
-And the usual bug-fixes (some of which are backported into 3.8.x):
-
-- fix #64, show MoreLikeThis titles on record show page if available
-- fix #422; show prev/next options even when not linked
-- fix #450; support Solr 4.x and use it by default.
-- fix #484, use top-level constant BLACKLIGHT_VERBOSE_LOGGING (uninitialized by default) to log the full solr response with each solr query
-- fix #495 Remove blacklight_config.rb template
-- fix #496, removing hard-coded 'id' field reference in BookmarksController
-- remove unicode as an explicit Blacklight dependency, but use it if it is available
-- fix #499 When document_heading is an array, don't draw the array bracket…
-- fix #502, Endnote action tries to render partials and gives error
-- update per_page widget to use i18n strings; don't require echoParams
-- use 1.9-style string interpolation for template path lookups
-- consolidate solr pagination information lookup.
-
-## Plugins Compatibility
-
-As of 11/26:
-
-### Tested/Compatible
-
-* blacklight_advanced_search
-* blacklight_cql
-* blacklight_range_limit
-* blacklight_browse_nearby
-
-
-
-
-## Upgrade Guide
-
-When approaching the Blacklight 3.x => 4.0 upgrade, we'd strongly recommend adopting the bootstrap templates, update local overrides to use bootstrap, and do your own bootstrap stylesheet customization. 
-
-That said, it should be possible to do a fairly straightforward in-place upgrade if you so choose. Most of the Blacklight 4.x work was limited to views, javascript and stylesheets. If you want to keep the old Blacklight theme, you should be able to grab them from Blacklight and drop them into your application directly. We wouldn't recommend it though.
-
-To upgrade your application to Blacklight 4.x:
-
-- Update your application's gem dependency to use Blacklight 4.0:
-
-```ruby
-gem 'blacklight', "~>4.0"
-```
-
-- Add the unicode gem to your application's Gemfile (if you want to use it to normalize character encoding for refworks integration):
-
-```ruby
-gem 'unicode'
-```
-
-- Remove compass/susy references; replace with bootstrap-sass:
-
-```ruby
-# REMOVE:
-gem 'compass-rails', '~> 1.0.0', :group => :assets
-gem 'compass-susy-plugin', '~> 0.9.0', :group => :assets
-
-# ADD:
-gem 'bootstrap-sass'
-```
-
-- (Remember to ```bundle install```)
-
-- Add the following into your stylesheets directory (possibly as ```app/assets/stylesheets/blacklight.css.scss```):
-
-```scss
-@import 'bootstrap';
-@import 'bootstrap-responsive';
-
-@import 'blacklight/blacklight';
-```
-
-You no longer need the ```blacklight_themes directory``` and can remove ```require 'blacklight_themes/standard'``` (and the jquery UI css) from your application.css
-
-In ```app/assets/javascripts/application.js```, you can also remove
-
-```javascript
-//= require jquery-ui
-```
-
-- If you have local overrides of stylesheets, javascript or view templates, you should update them appropriately. Be warned that some of the bootstrapped Blacklight HTML element classes and IDs may have shifted slightly, and the previous susy-grid and YUI class names have been removed.
-
-In your `ApplicationController`, you need to tell your application which layout to use:
-
-```ruby
-# completely Blacklight 3.x-backwards compatible
-layout :choose_layout
-
-# if you don't need dynamic layout switching, just do the Rails-standard:
-layout 'blacklight'
-```
-
-- If you are using devise-guests, you probably want to update to devise-guests ~> 0.3. After doing so,
-
-```bash
-$ rails g devise_guests
-$ rake db:migrate
-```
-
-If you've already chosen a different layout for your application, you don't need to do anything at all.
-
-Here are some minor differences elsewhere:
-
- - Some i18n strings have been updated to read better in the new UI
- - the helper `#render_document_heading` returns an h4 instead of an h1.
- - the helper `#document_show_fields` returns a hash instead of a list of keys
-
-## Document partial paths
-
-The default naming convention for format-specific partials was changed. In Blacklight 3.1, the default format-specific path was changed to `catalog/_index_[format_name].html.erb`, but support for the Blacklight 2.x style was left in place. In Blacklight 4, the Blacklight 2.x style was removed from the list of defaults.
-
-So, if you have partials in a directory like:
-
-```ruby
-catalog/_index_partials/[format_name].html.erb
-```
-
-they should be moved to
-
-```ruby
-catalog/_index_[format_name].html.erb
-```
-
-Or, alternatively, you may override the helpers [document_index_path_templates](https://github.com/projectblacklight/blacklight/blob/master/app/helpers/blacklight/blacklight_helper_behavior.rb#L382) and [document_partial_path_templates](https://github.com/projectblacklight/blacklight/blob/master/app/helpers/blacklight/blacklight_helper_behavior.rb#L423) with a custom naming convention.

data/doc/Blacklight-4.1-release-notes-and-upgrade-guide.md

@@ -1,17 +0,0 @@
-## Release Notes
-Bug fixes include:
-
-- #529 Responsive facet collapsing is not JS degradable
-- #528 Reset "page" param on "per_page" change
-
-And some minor feature enhancements, highlights include:
-- #523 Pass the document object into helper methods so local overrides can make rendering decisions based on the current document
-- #522 Make it easier to add custom SolrField fields in the Blacklight config
-- add a #blacklight_solr accessor (intended to replace the global Blacklight.solr)
-- a French locale translation for Blacklight (thanks @biblimathieu!)
-
-There's a handful of Rails 4 deprecation warnings and improvements that still need to happen, but this release fixed all major blockers and relaxes the Rails version dependency.
-
-## Upgrade Guide
-
-No known issues.

data/doc/Blacklight-4.2-release-notes-and-upgrade-guide.md

@@ -1,25 +0,0 @@
-## Release Notes
-### 4.2.0
-Bug fixes include:
-
-- jQuery 1.9 compatibility (#545 and others)
-- #548 remove duplicate favicon link tag
-- #546 more straightforward testing (deprecating the test_support/bin/* scripts in favor of just 'rake')
-- #549 add :helper_method to add_facet_field (similar to add_index/show_field) documented in [1]
-
-### 4.2.1
-Bug fixes include:
-
-- Rails 4 support
-- #554 enable users to update bootstrap-sass to the latest version
-- #557 add the post route for sending email
-- #559 Remove unnecessary require of 'mash' which was causing "uninitialized constant HashWithIndifferentAccess"
-- Fixed issue with refworks exports [156e76](https://github.com/projectblacklight/blacklight/commit/156e7680630fcbae2defa4d07f1e1c0aabc67944)
-
-### 4.2.2
-
-Minor fixes for Rails 4.0 final release.
-
-## Upgrade Guide
-
-No known issues.

data/doc/Blacklight-4.3-release-notes-and-upgrade-guide.md

@@ -1,21 +0,0 @@
-## Release Notes
-### 4.3.0
-Bug fixes include:
-
-- #556 	check that a highlight field exists before trying to render it.
-- #561 	Redirect to home page on a missing document 
-- #569 	Applies header style to `#header-navbar-fixed-top .brand` in order to avoid trumping other Bootstrap navbars.
-- use `#facet_configuration_for_field` to render search history constraints for consistency and configuration-independence
-
-Other changes:
-- deprecate `#sidebar_items`, and stop populating it with content.
-- provide a `SOLR_URL` ENV variable to set the location of the development solr core
-- fix Rails 4-related deprecation warnings
-
-[[Changes|https://github.com/projectblacklight/blacklight/compare/v4.2.2...v4.3.0]]
-
-## Upgrade Guide
-
-Application overrides that used the CSS selector `.navbar .brand` to change the navbar styling should use `#header-navbar-fixed-top .brand` instead.
-
-Applications that used content from `#sidebar_items` must populate that content themselves (by rendering it directly in their partial, or in some other application-specific way). 

data/doc/Blacklight-4.4-release-notes-and-upgrade-guide.md

@@ -1,41 +0,0 @@
-## Release Notes
-### 4.4.0
-
-
-Features
-- [#598](https://github.com/projectblacklight/blacklight/issues/598) Show thumbnails (if available) for documents in search results
-- [#594](https://github.com/projectblacklight/blacklight/issues/594) Provide Blacklight configuration support for linking field values to facets
-- [#589](https://github.com/projectblacklight/blacklight/issues/589) Support Rails 4.x-style turbolinks (Blacklight-provided javascript should be loaded on document ready or the page:load  event)
-- [#588](https://github.com/projectblacklight/blacklight/issues/588) Provide an (experimental) JSON API for search and show
-- [#577](https://github.com/projectblacklight/blacklight/issues/477) Add Solr Field Collapsing feature, if the Solr response includes a grouped element.
-
-Bug Fixes
-- [#640](https://github.com/projectblacklight/blacklight/issues/640) Fix the solr query Blacklight generates when the query contains Solr "local parameters" containing digits (e.g. $pf2_value)
-- [#590](https://github.com/projectblacklight/blacklight/issues/590) Fix transferring unregistered guest user bookmarks to a newly registered user
-- [#587](https://github.com/projectblacklight/blacklight/issues/587) Fix Zotero support, where ampersands in the context object were being double escaped
-- [#534](https://github.com/projectblacklight/blacklight/issues/534) Blacklight::CatalogHelperBehavior#paginate_params values of first_page? and last_page? incorrectly set?
-- [#525](https://github.com/projectblacklight/blacklight/issues/525) Add i18n support to Bookmarks javascript replacement
-- [#585](https://github.com/projectblacklight/blacklight/issues/585) Add keyboard accessibility to the facet expanders
-- [#563](https://github.com/projectblacklight/blacklight/issues/563) Login page should have focus in the email field, not the search field.
-
-Other Improvements
-- [#600](https://github.com/projectblacklight/blacklight/issues/600) Decomposing blacklight generator
-- [#599](https://github.com/projectblacklight/blacklight/issues/599) Improving speed of blacklight generator
-- [#597](https://github.com/projectblacklight/blacklight/issues/597) Rewrite document_counter logic in header
-- [#596](https://github.com/projectblacklight/blacklight/issues/596) Don't generate devise views by default
-- [#595](https://github.com/projectblacklight/blacklight/issues/595) Support kaminari pagination helpers in Blacklight::SolrResponse (kaminari can now work with our SolrResponse objects natively).
-- [#591](https://github.com/projectblacklight/blacklight/issues/591) Remove cucumber. All features have been ported to rspec feature tests.
-- [#584](https://github.com/projectblacklight/blacklight/issues/584) Move onload_text out of layouts/blacklight.html.erb
-- [#515](https://github.com/projectblacklight/blacklight/issues/515) Ensure we run bundle install after generating bootstrap-sass into the Gemfile
-- Update lightbox_dialog.js - Adding an event for DOM change when modal is already shown
-- [#607](https://github.com/projectblacklight/blacklight/issues/607) Refactor catalog#email and catalog#sms methods
-- [#609](https://github.com/projectblacklight/blacklight/issues/609) The solr facet :ex local parameter should work with pivot and facet
-field configurations.
-- Convert some bare strings to i18n strings
-- [#608](https://github.com/projectblacklight/blacklight/issues/608) Use ActiveRecord query methods in Blacklight::User mixin
-
-[[Changes|https://github.com/projectblacklight/blacklight/compare/v4.3.0...v4.4.0]]
-
-## Upgrade Guide
-
-If you've overridden the `catalog/sms.html.erb` template or `RecordMailer#sms` action (e.g. to add custom SMS provider mappings), you should look at the changes in [this patch](https://github.com/projectblacklight/blacklight/pull/607), which moved the mappings and validation into the controller.

data/doc/Blacklight-Add-ons.md

@@ -1,28 +0,0 @@
-## Stable Add-ons
-
-A few add-ons are are more or less 'officially supported', and all Blacklight developers have commit rights on them. (although some may not have received attention in a while if developers have been busy. Feel free to ask on the list for current status):
-
-* [Advanced search](https://github.com/projectblacklight/blacklight_advanced_search) plugin
-* [CQL search](https://github.com/projectblacklight/blacklight_cql) plugin
-* a fancy GUI [date range limit](https://github.com/projectblacklight/blacklight_range_limit) plugin.  
-
-
-
-[RSolr Footnotes](https://github.com/cbeer/rsolr-footnotes) is useful for debugging, to see the request/response sent to Solr via RSolr: [[Integration with Rails Footnotes]]
-
-(Not all 'stable' add-ons neccesarily need to be in Blacklight github areas; if others come to exist that the community deems stable, feel free to add them here.)
-
-
-## Unstable/Experimental
-
-* [[Blacklight Sitemap Generator|https://github.com/jronallo/blacklight-sitemap]]: Rake task for generating sitemaps.
-* [[Blacklight Highlight|https://github.com/cbeer/blacklight_highlight]]: Expose Solr fulltext highlighting.
-* [[Blacklight OAI provider|https://github.com/cbeer/blacklight_oai_provider]]: Adds an [[OAI-PMH|http://www.openarchives.org/pmh/]] provider using the [[oai|http://rubygems.org/gems/oai]] gem for harvesting records within Blacklight.
-* [[Blacklight unAPI|https://github.com/cbeer/blacklight_unapi]]: Adds an [[unAPI|http://unapi.info]] endpoint for records within Blacklight.
-* [[Blacklight User Generated Content|https://github.com/cbeer/blacklight_user_generated_content]]: Adds user generated content to SolrDocument objects using acts_as_commentable, acts_as_taggable and acts_as_rateable directly against a SolrDocument object. 
-* [[Blacklight oEmbed|https://github.com/cbeer/blacklight_oembed]]: [[oEmbed|http://oembed.com]] endpoint that provides framework for allowing third-party sites (Wordpress, Facebook, etc) to embed content given a URL. 
-* [[Blacklight More Like This|https://github.com/cbeer/blacklight_mlt]]: Solr more like this results
-* [[Blacklight Google Analytics|https://github.com/jronallo/blacklight_google_analytics]]: Quick start for setting up Google Analytics for a Blacklight site, including Event Tracking of Blacklight-specific page elements like facets.
-
-# Deprecated
-* [[Blacklight Facet Extras|https://github.com/cbeer/blacklight_facet_extras]]: Exposes new faceting features present in Solr 3.1 and 3.4, such as facet queries, facet range requests, pivot facets, and tagged/excluded facets

data/doc/Blacklight-configuration.md

@@ -1,411 +0,0 @@
-# Configuring Blacklight to work with your Solr index
-
-In order to fully understand this section, you should be familiar with Solr, ways to index data into Solr, how to configure request handlers, and how to change a Solr schema.  Those topics are covered in the official [Apache Solr Tutorial](http://lucene.apache.org/solr/tutorial.html).
-
-The Blacklight example configuration is a (simplified) way to work with library data (in the MARC format), it is (hopefully) easy to reconfigure to work with your Solr index. In this section, we will describe most of the Blacklight configuration settings that determine how the Blacklight interface works with your data. Later sections demonstrate how to modify the Blacklight user experience and templates, etc.
-
-> Note: In most of this section, we will show how to configure Blacklight to request data from Solr. While this works, and makes it easy to rapidly develop an application, we recommend eventually configuring your Apache Solr request handlers to do this instead.
-
-
-## Connecting to Solr: config/solr.yml
-
-Your Blacklight-based application will interact with your Solr index. Although Blacklight does distribute a sample jetty-based Solr instance, you will likely want to connect Blacklight to your own Solr index. The Solr index to use is specified in a configuration file, ```config/solr.yml```. If you open this file in a recently generated Blacklight application, you’ll see a default solr configured to use a single-core Solr running under jetty:
-
-```yaml
-development:
-  url: http://127.0.0.1:8983/solr
-
-test:
-  url: http://127.0.0.1:8888/solr
-```
-
-When you run your Rails application in the ```development``` environment, it will try to connect to Solr at ```http://127.0.0.1:8983/solr```, and, likewise, in ```test```, it will try to connect to Solr at ```http://127.0.0.1:8888/solr```. 
-
-This URL should point to the base path of your Solr application, and includes e.g. Solr core names (see below), but not request handler paths, etc.
-
-Blacklight uses the RSolr gem to talk to Solr. The parameters are passed to [RSolr.connect](http://rubydoc.info/gems/rsolr/1.0.6/RSolr.connect).
-
-### Using Blacklight with a Multicore Solr
-
-Here's an example of using a Multi-core Solr install with Blacklight:
-
-```yaml
-development:
-  url: http://127.0.0.1:8983/solr/development-core
-test:
-  url: http://127.0.0.1:8983/solr/test-core
-```
-
-### Running and Monitoring Solr with Foreman
-
-You can use [foreman](http://blog.daviddollar.org/2011/05/06/introducing-foreman.html) to start up and monitor the blacklight rails app and the solr server. Here is an example Procfile:
-
-    web: bundle exec rails s -p $PORT
-    solr: bash -c "cd ./jetty; java -jar -Djetty.port=$PORT start.jar"
-
-## Blacklight Configuration
-
-Now that you've connected to Solr, you probably want to configure Blacklight to display your Solr fields in the search results and facets, and also use your fields for search fields, sort options. This configuration goes in your CatalogController.  By convention, this is in your Rails application, and is located at [```app/controllers/catalog_controller.rb```](https://github.com/projectblacklight/blacklight/blob/master/lib/generators/blacklight/templates/catalog_controller.rb).
-
-The CatalogController includes functionality and templates for searching and displaying documents. The CatalogController needs to be configured so it knows about your Solr fields.
-
-> NOTE: While most applications use only a single controller for search, it is possible to have multiple controllers with different configurations. This documentation will only discuss the simple case.
-
-### default_solr_params
-
-The default_solr_params are parameters that will be sent to the Solr API on all search-like requests:
-
-```ruby
-    config.default_solr_params = { 
-      :qt => 'search',
-      :rows => 10 
-    }
-```
-
-This configuration would send the following for any request to solr:
-
-```
-http://localhost:8983/solr/select?qt=search&rows=10
-```
-
-While the default_solr_params are useful for rapid development, they are often moved into the Solr request handler for production deployments.
-
-A counter-part to default_solr_params is default_document_solr_params, which is sent when requesting only a single document from solr. In the Blacklight example solrconfig.xml, there is a `document` requestHandler to retrieve a single document at a time. We encourage you to adopt pattern as well, but with an existing Solr installation adding a single document requestHandler may not be an option. Instead, you can modify the `default_document_solr_params` to configure the appropriate defaults:
-
-```ruby
-    # See SolrHelper#solr_doc_params
-    config.default_document_solr_params = {
-      :qt => 'document',
-      ## These are hard-coded in the blacklight 'document' requestHandler
-      # :fl => '*',
-      # :rows => 1
-      # :q => '{!raw f=id v=$id}' 
-    }
-```
-
-Blacklight will add a query parameter called `id` containing the unique key for your document. It can be referenced as a Solr local parameter (as above) in your queries.
-
-
-### results views (index and show)
-
-
-You can configure the fields and labels that are display for search results on the search and document views.
-
-> Note: these must be STORED fields in the Solr index, and must be returned in the solr response or they will not be displayed.
-
-There's a set of configuration parameters for the title and Blacklight template handling (discussed elsewhere):
-
-```ruby
-    # solr field configuration for search results/index views
-    config.index.show_link = 'title_display'
-    config.index.record_display_type = 'format'
-
-    # solr field configuration for document/show views
-    config.show.html_title = 'title_display'
-    config.show.heading = 'title_display'
-    config.show.display_type = 'format'
-```
-
-This configuration will use the ```title_display``` Solr field as the link text for each document.
-
-There's a separate section for the additional fields to display:
-
-```ruby
-    # [from app/controllers/catalog_controller.rb]
-    # solr fields to be displayed in the index (search results) view
-    #   The ordering of the field names is the order of the display 
-    config.add_index_field 'title_display', :label => 'Title:' 
-    config.add_index_field 'title_vern_display', :label => 'Title:' 
-    config.add_index_field 'author_display', :label => 'Author:' 
-    config.add_index_field 'author_vern_display', :label => 'Author:'    
-
-    # ...
-    # And likewise for the show (single-document) view:
-
-    config.add_show_field 'title_display', :label => 'Title:' 
-    config.add_show_field 'title_vern_display', :label => 'Title:' 
-    config.add_show_field 'subtitle_display', :label => 'Subtitle:'
-```
-
-[[https://github.com/projectblacklight/projectblacklight.github.com/raw/master/images/index_fields.png|frame|alt=Index Fields]]
-
-#### Linking a value to a facet search
-
-When rendering the format value in the search results, link the value to a facet search for that value:
-
-```ruby
-config.add_index_field 'format', :label => 'Format:', :link_to_search => true
-```
-
-Or specify the field to facet against, explicitly:
-```ruby
-config.add_index_field 'author_display', :label => 'Author:', :link_to_search => :author_facet
-```
-
-More advanced configuration should use a custom helper method (see below) to render an appropriate value.
-
-#### Using a helper method to render the value
-
-You can use view helpers to render the Solr values, e.g.:
-
-```ruby
-    config.add_index_field 'title_vern_display', :label => 'Title:', :helper_method => :my_helper_method
-```
-
-When Blacklight goes to display the 'title_vern_display' field, it will call ```my_helper_method``` to get the value to display. You can implement any logic you want to manipulate the solr document to return the value to display.
-
-```ruby
-module ApplicationHelper
-  def my_helper_method args
-    args[:document][args[:field]].upcase
-  end
-end
-```
-
-Your helper method receives hash with (at least) two parameters:
-
- - :document => the SolrDocument object
- - :field => the solr field to display
-
-
-#### Solr hit highlighting 
-
-You can trigger automatic Solr hit highlighting of results:
-
-```ruby
-    config.add_index_field 'title_vern_display', :label => 'Title:', :highlight => true
-```
-
-This will cause Blacklight to look at the Solr highlight component response for the value of this field. This assumes you've configured the highlighting component elsewhere. The [Solr Highlighting Parameters](http://wiki.apache.org/solr/HighlightingParameters) documentation discusses the Solr parameters available to you. You could add these to your default_solr_params, request handler configuration, or elsewhere.
-
-You can have Blacklight send the most basic highlighting parameters for you, if you set:
-
-```ruby
-  config.add_field_configuration_to_solr_request!
-```
-
-This will enable the highlighting component and send 'hl.fl' parameters for the fields you wanted highlighted, but you will likely want to tweak this behavior further.
-
-### facet fields
-
-Faceted search allows users to constrain searches by controlled vocabulary items
-[[https://github.com/projectblacklight/projectblacklight.github.com/raw/master/images/search_facets.png|frame|alt=Search facets in action]]
-Note that these must be INDEXED fields in the Solr index, and are generally a single token (e.g. a string).
-
-```ruby
-    # [from app/controllers/catalog_controller.rb]
-    # solr fields that will be treated as facets by the blacklight application
-    #   The ordering of the field names is the order of the display
-    config.add_facet_field 'format', :label => 'Format' 
-    config.add_facet_field 'pub_date', :label => 'Publication Year' 
-    config.add_facet_field 'subject_topic_facet', :label => 'Topic', :limit => 20 
-    config.add_facet_field 'language_facet', :label => 'Language', :limit => true 
-```
-
-### Facet View Helpers
-
-You can supply a :helper_method argument to configure what you would like displayed for the facet's text, e.g:
-
-```ruby
-    config.add_facet_field 'format', :label => 'Format', :helper_method => :my_helper_method
-```
-
-With the above code Blacklight will pass the facet's value into the given helper method, with which you can do anything you'd like.
-
-```ruby
-module ApplicationHelper
-  def my_helper_method value
-    value.upcase
-  end
-end
-```
-### Facet Queries
-Blacklight also supports Solr facet queries:
-
-[[https://github.com/projectblacklight/projectblacklight.github.com/raw/master/images/query_facets.png|frame|alt=Query facets in action]]
-
-```ruby
-    config.add_facet_field 'pub_date_query', :label => 'Publication Year', :query => {
-      :last_5_years => { :label => 'Last 5 Years', :fq => "[#{Time.now.year-5} TO *]"}
-    } 
-```
-
-The first argument (which maps to the facet field for plain facets) is used in the Blacklight URL when the facet is selected.
-
-The :query hash maps a key to use in Blacklight URLs to a facet :label (used in the facet display) and an :fq to send to Solr as the `facet.query` and (if selected) the Solr `fq` parameter.
-
-You can also tell Solr how to sort facets (either by [count or index](http://wiki.apache.org/solr/SimpleFacetParameters#facet.sort)):
-If your data is strings, you can use this to perform an alphabetical sort of the facets.
-```ruby
-   config.add_facet_field :my_count_sorted_field, :sort => 'count'
-   config.add_facet_field :my_index_sorted_field, :sort => 'index'
-```
-
-
-If you want Solr to add the configured facets and facet queries to the Solr query it sends, you should also add:
-
-```ruby
-    config.add_facet_fields_to_solr_request!
-```
-
-### Date-based facets
-
-If you have date facets in Solr, you should add a hint to the Blacklight configuration:
-
-```ruby
-   config.add_facet_field :my_date_field, :date => true
-```
-
-This will trigger special date querying logic, and also use a localized date format when displaying the facet value. If you want to use a particular localization format, you can provide that as well:
-
-```ruby
-   config.add_facet_field :my_date_field, :date => { :format => :short }
-```
-
-### Tagging/Exclusion facets
-
-From the solr docs:
-
-> One can tag specific filters and exclude those filters when faceting. This is generally needed when doing multi-select faceting. [...]To implement a multi-select facet for doctype, a GUI may want to still display the other doctype values and their associated counts, as if the doctype:pdf constraint had not yet been applied. 
->
-> Example:
->
-> === Document Type ===
->
->  [ ] Word (42)
->
->  [x] PDF  (96)
->
->  [ ] Excel(11)
->
->  [ ] HTML (63)
-
-To configure this behavior in Blacklight, 
-
-```ruby
-   config.add_facet_field :document_type_facet, :tag => 'some-tag', :ex => 'some-tag'
-```
-
-### search fields
-
-Search queries can be targeted at configurable fields (or sets of fields) to return precise search results. Advanced search capabilities are provided through the [[Advanced Search Add-On|https://github.com/projectblacklight/blacklight_advanced_search]] 
-[[https://github.com/projectblacklight/projectblacklight.github.com/raw/master/images/search_fields.png|frame|alt=Search fields in action]]
-
-```ruby
-    # [from app/controllers/catalog_controller.rb]
-    # Now we see how to over-ride Solr request handler defaults, in this
-    # case for a BL "search field", which is really a dismax aggregate
-    # of Solr search fields. 
-    
-    config.add_search_field('title') do |field|
-      # solr_parameters hash are sent to Solr as ordinary url query params. 
-      field.solr_parameters = { :'spellcheck.dictionary' => 'title' }
-
-      # :solr_local_parameters will be sent using Solr LocalParams
-      # syntax, as eg {! qf=$title_qf }. This is neccesary to use
-      # Solr parameter de-referencing like $title_qf.
-      # See: http://wiki.apache.org/solr/LocalParams
-      field.solr_local_parameters = { 
-        :qf => '$title_qf',
-        :pf => '$title_pf'
-      }
-    end
-```
-
-### sort fields
-
-```ruby
-    config.add_sort_field 'score desc, pub_date_sort desc, title_sort asc', :label => 'relevance'
-    config.add_sort_field 'pub_date_sort desc, title_sort asc', :label => 'year'
-    config.add_sort_field 'author_sort asc, title_sort asc', :label => 'author'
-    config.add_sort_field 'title_sort asc, pub_date_sort desc', :label => 'title'
-```
-
-[[https://github.com/projectblacklight/projectblacklight.github.com/raw/master/images/sort_fields.png|frame|alt=Sort fields in action]]
-
-> TODO
-
-## Solr Document
-
-
-By default, Blacklight assumes the unique key field in your solr index is called `id`. You can change this by editing `app/models/solr_document.rb`:
-
-```ruby
-class SolrDocument
-  include Blacklight::Solr::Document
-
-  # self.unique_key = 'id'
-  ...
-end
-```
-
-If, for instance, your unique key field was 'uuid_s', this would read:
-
-```ruby
-class SolrDocument
-  include Blacklight::Solr::Document
-
-  self.unique_key = 'uuid_s'
-  ...
-end
-```
-
-This will instruct Blacklight to use your ```uuid_s``` field any time it needs an identifier for the document, e.g. when constructing document URLs. 
-
-Also in SolrDocument is a set of "field semantics", which may be used in some basic metadata mapping:
-
-```ruby
-class SolrDocument
-  ...
-
- field_semantics.merge!(    
-                         :title => "title_display",
-                         :author => "author_display",
-                         :language => "language_facet",
-                         :format => "format"
-                         )
-end
-```
-
-### Field Collapsing
-
-Blacklight 4.4 adds support for Solr Field Collapsing (aka results grouping). The initial implementation requires you to explicitly configure your solr request handler (or default solr parameters) to enable grouping. 
-
-Here are some solr request parameters to enable grouping on our demo index:
-
-```
-      :group => true,
-      :'group.field' => 'pub_date_sort',
-      :'group.ngroups' => true, # group.ngroups is REQUIRED.
-      :'group.limit' => 3
-```
-
-If you only define a single group.field, Blacklight will detect the grouped response and use it. If there are multiple fields defined, you have to configure Blacklight to detect the correct field, e.g.:
-
-```
-    config.index.group = "pub_date_sort"
-```
-
-### Thumbnails in results display
-
-Blacklight 4.4+ can render a representative thumbnail with a result on the search index page. 
-
-Blacklight can pull a URL to the thumbnail from a field in Solr:
-
-```ruby
-  configure_blacklight do |config|
-    config.index.thumbnail_field = :some_field_in_the_document
-  end
-```
- 
-Or using custom logic in a helper method of your own creation:
-
-```ruby
-  configure_blacklight do |config|
-    config.index.thumbnail_method = :xyz
-  end
-```
-
-With this configuration, the helper method `xyz` will be called with the `SolrDocument` document and a hash of caller-supplied image options.
-
-Given that configuration, Blacklight will render a thumbnail (by default, right aligned, under the bookmark button) as a link to the document page. If no thumbnail is available (missing data in solr, the thumbnail method returned nil), the thumbnail block is not displayed at all.