blacklight 5.9.4 → 5.10.0

data/doc/Blacklight-on-Heroku.md

@@ -1,100 +0,0 @@
-> As of March 2014, the directions from the Heroku [Getting Started with Rails](https://devcenter.heroku.com/articles/getting-started-with-rails4) guide can be followed as-is with an existing Blacklight application.
-
-<hr />
-
-Blacklight can be deployed on [Heroku](http://heroku.com/), a Platform-as-a-Service (PaaS) provider that supports Ruby. This walkthrough assumes some familiarity with Heroku, that you have a Solr server running somewhere, and that you already have a Heroku account. For more information on working with Heroku, please see [Getting Started with Heroku](https://devcenter.heroku.com/articles/quickstart).
-
-## Create a new Blacklight app
-
-* Use the Blacklight [[Quickstart]] to create a new Rails application:
-
-    ```bash
-    $ rails new blheroku      
-    #      create  
-    #      create  README
-    #      create  Rakefile
-    #      create  config.ru
-    #      create  .gitignore
-    #      create  Gemfile
-    #      [...]
-    
-    $ cd blheroku
-    $ rm public/index.html
-
-* Append this line to your application's `Gemfile`:
-
-    ```ruby
-    gem 'blacklight'
-    ```
-
-* Install the gems using Bundler:
-
-   ```bash
-$ bundle install
-   ```
-
-* Call the Blacklight generator (in this case, without Devise for authentication):
-
-   ```bash
-$ rails generate blacklight
-   ```
-
-## Change Gem dependencies for Heroku deployment
-
-* Change the database-related gems in your `Gemfile` from:
-
-    ```ruby
-    gem 'sqlite3'
-    ```
-
-    * to the following:
-
-    ```ruby
-gem 'sqlite3', :groups => [:development, :test]
-gem 'pg', :group => :production
-    ```
-
-* Move all gems in the asset block of `Gemfile` to the main block [see here for more info](http://stackoverflow.com/questions/9629620) (still needed? - 2/1/2014).
-
-## Configure Solr for your application
-
-* While untested, you may want to look at [Websolr](http://websolr.com/), which provides Solr as a Service.
-* Add a line `config/solr.yml` to point to your production instance of Solr:
-
-   ```yaml
-production:
-  url: http://my.solr.host:8983/path/to/solr
-   ```
-
-## Index some test records
-
-   ```bash
-$ RAILS_ENV=production rake solr:marc:index_test_data
-   ```
-## Set up Heroku
-
-   ```bash
-$ git init
-$ heroku create --stack cedar
-Creating vivid-winter-2427... done, stack is cedar
-http://vivid-winter-2427.herokuapp.com/ | git@heroku.com:vivid-winter-2427.git
-Git remote heroku added
-$ git add .
-$ git commit -m"Initial import"
-   ```
-
-* Take note of the URL reported back by Heroku (in this case, http://vivid-winter-2427.herokuapp.com/)
-
-## Deploy to Heroku
-
-   ```bash
-$ git push heroku master
-[...]
-$ heroku run rake db:migrate
-[...]
-   ```
-
-## Try opening up your app
-
-* Go to URL reported by Heroku above (in this example, http://vivid-winter-2427.herokuapp.com/).
-* Does it work? If it doesn't, try running `heroku logs` to see where problems are cropping up.

data/doc/Blacklight-out-of-the-box.md

@@ -1,47 +0,0 @@
-# Bootstrap 3 / Responsive Design
-![Responsive Design](https://f.cloud.github.com/assets/111218/2058435/e31f4314-8b71-11e3-9cac-dd4feff588d9.png)
-
-# Search
-#### Global Search Bar
-![Global Search](https://f.cloud.github.com/assets/111218/2058442/e336ebb8-8b71-11e3-8995-27c85b33a1f1.png)
-#### Sortable Results
-![Sorting](https://f.cloud.github.com/assets/111218/2058444/e33f6234-8b71-11e3-83a6-b3c65a96d6c2.png)
-#### Fielded Search
-![Fielded Search](https://f.cloud.github.com/assets/111218/2058437/e327c084-8b71-11e3-8438-cdc7f2263158.png)
-
-## Pagination
-#### Sorting options
-![Sort and Per Page](https://f.cloud.github.com/assets/111218/2058433/e2ee32c4-8b71-11e3-929c-76eb693723e4.png)
-
-#### Deep pagination
-![Pagination](https://f.cloud.github.com/assets/111218/2058438/e32a5c22-8b71-11e3-8979-e3afd961daed.png)
-
-## History
-![Search History](https://f.cloud.github.com/assets/111218/2058439/e32c8312-8b71-11e3-9e67-424e586e15dd.png)
-
-# Facets
-#### Facets
-![Facets](https://f.cloud.github.com/assets/111218/2058447/e34cc12c-8b71-11e3-940e-3eba736a0577.png)
-
-#### Selected Facet
-![Facets](https://f.cloud.github.com/assets/111218/2058443/e33a7634-8b71-11e3-9f46-6861325b19a3.png)
-
-#### Constraints
-![Constraints](https://f.cloud.github.com/assets/111218/2058446/e34504a0-8b71-11e3-9188-7cd87d08efdb.png)
-
-#### Query Facets
-![Query Facets](https://f.cloud.github.com/assets/111218/2058448/e34e61c6-8b71-11e3-8905-f72ff12a95d0.png)
-
-#### Constraints
-![Query Constraints](https://f.cloud.github.com/assets/111218/2058434/e305c146-8b71-11e3-8d2b-8e5b7760dfcb.png)
-
-# Results
-
-#### Index view
-![Index View](https://f.cloud.github.com/assets/111218/2058445/e341d4f6-8b71-11e3-97f1-4e21e5ed1034.png)
-
-#### Show view
-![Show View](https://f.cloud.github.com/assets/111218/2058436/e322543c-8b71-11e3-90a3-6744cb6628c7.png)
-
-#### Tools
-![Tools](https://f.cloud.github.com/assets/111218/2058441/e33395d0-8b71-11e3-98e4-fe794e2ba63b.png)

data/doc/Bookmarks.md

@@ -1 +0,0 @@
-If a User implementation is provided, Blacklight can provide a "bookmarks" or "selected items" feature. Blacklight ships with a devise-based example, but it should be portable across authentication framework.

data/doc/Code4Lib-2014.md

@@ -1,94 +0,0 @@
-# Preconference Planning
-
-## "Half-Day [Morning]" (3 hours)
-Contact: Chris Beer, Stanford University, cabeer@stanford.edu
-TA: Bess Sadler, Stanford University, bess@stanford.edu
-This session will be walk-through of the architecture of Blacklight, the community, and an introduction to building a Blacklight-based application. Each participant will have the opportunity to build a simple Blacklight application, and make basic customizations, while using a test-driven approach.
-For more information about Blacklight see our wiki ( http://projectblacklight.org/ ) and our GitHub repo ( https://github.com/projectblacklight/blacklight ). We will also send out some brief instructions beforehand for those that would like to setup their environments to follow along and get Blacklight up and running on their local machines.
-
-### Welcome and Introductions (15m)
-
-### Intro to Blacklight (25m)
-
-* History
-* Development methodology (github, mailing list, irc)
-* Roadmap (?)
-* Demos: searchworks, frda, spotlight, uohull, cornell, https://scholarsphere.psu.edu/ ? (some of these may show up below in the configuration section..)
-
-### Installfest (40m)
-
-* Vagrant with everything pre-installed
-* Rails Application Template
-
--- break (10m) --
-
-### Indexing (30m; hopefully less)
-
-* MARC data
-* digital collections data  (github.com/tategallery/collection ?)
-
-### Configuration (1h)
-
-* Index fields
-* Thumbnails
-* Facet configuration
-* Search fields
-* other search options (sort, per page, etc)
-* Show fields
-
-* Custom partials
-* CSS + Bootstrap
-
-### Q & A
-
-
-## "Half-Day [Afternoon]" (3 hours)
-This afternoon hackfest is both a follow-on to the Intro to Blacklight morning session to continue building Blacklight-based applications, and also an opportunity for existing Blacklight contributors and members of the Blacklight community to exchange common patterns and approaches into reusable gems or incorporate customizations into Blacklight itself.
-For more information about Blacklight see our wiki ( http://projectblacklight.org/ ) and our GitHub repo ( https://github.com/projectblacklight/blacklight ).
-
-### Welcome and Introductions (30m)
-
-* Introductions
-* Project planning
-
-### Work (2h)
-
-
-### Demos (30m)
-
-
-# Code4Lib table volunteers
-
-## Tuesday
-
-- Tuesday (8:00 - 9:00): 
-      barmintor
-- Tuesday (Break #1; 10:00 - 10:20): bess
-
-- Tuesday (Lunch-ish; 12:10 - 13:10): bess
-
-- Tuesday (Break #2; 14:15 - 14:30): bess
-
-- Tuesday (Breakout; 14:30 - 15:40):
-      cbeer
-
-## Wednesday
-
-- Wednesday (8 - 9am): 
-      barmintor
-- Wednesday (Break #1; 10:35 - 11:00): ksprague, ejames
-
-- Wednesday (Lunch-ish; 12:00 - 13:00):
-
-- Wednesday (Break #2; 14:25 - 14:40):
-
-- Wednesday (Breakout; 14:40 - 15:30):
-      cbeer
-
-- Wednesday (Break #3; 15:30 - 15:50):
-
-## Thursday
-
-- Thursday (8 - 9am): 
-      barmintor
-- Thursday (Break #1; 10:15-11:00):

data/doc/Configuration---Facet-Fields.md

@@ -1,130 +0,0 @@
-Faceted search allows users to constrain searches by controlled vocabulary items.
-
-Note that these must be INDEXED fields in the Solr index, and are generally a single token (e.g. a string).
-
-By default, Blacklight will handle creating the Solr requests to handle the different configuration options below. For performance or other reasons, this behavior can be disabled by removing or commenting out: 
-
-```ruby
-config.add_facet_fields_to_solr_request!
-```
-
-Note: When disabled, you are responsible for ensuring Solr returns the necessary values to drive the Blacklight interface.
-
-## Basic Configuration
-
-```ruby
-config.add_facet_field 'format_facet'
-```
-
-* label
-
-```ruby
-config.add_facet_field 'format_facet', label: "Format"
-```
-
-* sort
-
-Note: setting 'index' causes Blacklight to sort by count and then by index. 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'
-```
-
-* collapse
-
-```ruby
-config.add_facet_field 'format_facet', collapse: true  # the default
-```
-
-```ruby
-config.add_facet_field 'format_facet', collapse: false 
-```
-
-* show
-
-```ruby
-config.add_facet_field 'format_facet', show: false # don't display the facet, but configure it in case it displays in the constraints (or e.g. a saved search)
-```
-
-* helper_method
-
-```ruby
-config.add_facet_field 'format_facet', helper_method: :render_format_with_icon
-```
-
-```ruby
-module ApplicationHelper
-  def render_format_with_icon value
-    content_tag :span do
-      content_tag :span, '', class: "glyphicon glyphicon-#{value.parameterize}" +
-      content_tag :span, value
-    end 
-  end
-end
-```
-
-* partial
-
-```ruby
-config.add_facet_field 'format_facet', partial: 'custom_format_facet'
-```
-## Single-value facets
-
-* single
-
-Only one value can be selected at a time. When the value is selected, the value of this field is ignored when calculating facet counts for this field.
-
-```ruby
-config.add_facet_field 'format_facet', single: true
-```
-
-## Tag/Ex Facets
-
-Single-select facets (above) are one example of Solr's tag/ex functionality. More advanced uses of tag/ex can be done using the `tag` and `ex` configuration.
-
-```ruby
-config.add_facet_field 'some_field', tag: 'xyz',ex: 'xyz'
-config.add_facet_field 'mutually_exclusive_with_above', tag: 'xyz', ex: 'xyz'
-```
-
-## Query Facets
-
-```ruby
-config.add_facet_field 'a_query_field', query: {
-  a_to_n: { label: 'A-N', fq: 'some_field:[A* TO N*]' }
-  m_to_z: { label: 'M-Z', fq: 'some_field:[A* TO N*]' }
-}
-```
-
-## Pivot Facets
-
-```ruby
-config.add_facet_field 'a_pivot_facet', pivot: ['first_field', 'last_field']
-```
-
-## Date Facets
-
-
-If you have date facets in Solr, you should add a hint to the Blacklight configuration to trigger date-based solr querying, and ensure the values are displayed using a localized date format provided by the Rails date helpers:
-```ruby
-config.add_facet_field 'date_format', date: true
-```
-
-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 }
-```
-
-## Range Facets
-
-blacklight_range_limit
-
-## Advanced Configuration
-
-You can also use this facet configuration to inject field-specific configuration
-
-```ruby
-    config.add_facet_field :my_field, solr_params: { 'facet.mincount' => 15 }
-```

data/doc/Configuration---Results-View.md

@@ -1,224 +0,0 @@
-Note that Solr fields you configure for display must be STORED fields in the Solr index.
-
-# Index View
-
-![Index View](https://f.cloud.github.com/assets/111218/2058436/e322543c-8b71-11e3-90a3-6744cb6628c7.png)
-
-## Basic configuration
-
-The index view is configured from your CatalogController's blacklight configuration. Here is a listing of the configuration parameters Blacklight uses and their default values:
-
-```ruby
-
-configure_blacklight do |config|
-   ...
-
-   config.index.title_field = unique_key
-   config.index.partials = [:index_header, :thumbnail, :index]
-   config.index.display_type_field = 'format'
-   config.index.group = false
-
-   ...
-end
-```
-
-The configuration keys are not limited or restricted, so plugins or applications that need additional index configuration may add additional parameters directly.
-
-```ruby
-config.index.my_custom_parameters = "some value"
-```
-
-#### title_field
-
-The title field setting determines the Solr field that Blacklight will use to display the record title. 
-
-If you need additional customization (e.g. to concatenate two fields, etc), you can provide your own implementation of the `#document_heading` partial method, e.g.
-
-```
-module ApplicationHelper
-  def document_heading document = nil
-    document ||= @document
-    document.first(:main_title) + " - " + document.first(:sub_title)
-  end
-end
-```
-
-#### Partials and display_type_field
-
-You can configure the partials that Blacklight will assemble to display a search result.
-
-By default, Blacklight will render these three basic partials when displaying a document. The partial names are a combination of two configuration settings. The base name of the partial is given by the `partials` setting. The suffix is based on the type of document given by the value of the `display_type_field`. If a partial is not found with the given `display_type_field` value, it will attempt to render a default version of the base partial. If no matching partial is found, nothing will be displayed for that document.
-
-For example, using the default values and a document without a `format` field, these partials will be rendered:
-
- * `index_header_default.html.erb`: The document title and document actions
- * `thumbnail_default.html.erb`: A representative thumbnail (from the `thumbnail_field` configuration below)
- * `index_default.html.erb`: A list of document fields
-
-However, if the document had a format field with the value `book`, Blacklight would attempt to render these partials:
-
-* `index_header_book.html.erb`; if that doesn't exist, it will fall back to `index_header_default.html.erb`
-* `thumbnail_book.html.erb`; fall back to `thumbnail_default.html.erb`
-* `index_book.html.erb`; fall back to `index_default.html.erb`
-
-Blacklight only provides default partials for these three base partials. If you were to provide an `app/views/catalog/_index_book.html.erb` partial, Blacklight would render that partial instead of the default.
-
-
-#### (Advanced) Result Collapsing / Grouping
-
-Blacklight can use Solr's result collapsing feature. To use this feature, set the `group` parameter to the name of the field that Blacklight should use to render collapsed result sets. 
-
-#### Respond_to
-
-You can also affect which search results response formats are available, in addition to the out-of-the-box HTML, JSON, Atom and RSS feeds.
-
-Options include:
-
-- use the Rails default rendering options:
-  ```ruby
-  config.index.respond_to.yaml = true
-  ```
-
-- don't render the format (e.g. for overriding defaults):
-  ```ruby
-    config.index.respond_to.yaml = false
-  ```
-
-- options for render
-  ```ruby
-    config.index.respond_to.yaml = { layout: 'custom-layout' }
-  ```
-
-- custom proc to render
-  ```ruby
-    config.index.respond_to.yaml = lambda { render text: "stuff" }
-   ```
-
-- controller method to call to render
-    ```ruby
-    config.index.respond_to.yaml = :my_custom_yaml_serialization
-    ```
-
-### Fields
-
-The fields the `index_default` template uses to render fields are configured using `add_index_field`:
-
-```
-config.add_index_field 'title_display'
-```
-
-This will add a field to the display that will pull values from the Solr field 'title_display'. If the field is multivalued, Blacklight will concatenate them using a separator (", " by default). This value can also be configured:
-
-```
-config.add_index_field 'multivalued_title', separator: '; '
-```
-
-Additional configuration options can be also be used:
-
-#### Labels
-
-By default, Blacklight will calculate a default label by `humanizing` the Solr field (which is rarely desirable, but convenient for initial configuration). To customize the label, a `:label` option can be provided.
-
-```ruby
-config.add_index_field 'title_display', label: "Title"
-```
-
-Or, using i18n syntax, may look something like:
-
-```ruby
-config.add_index_field 'title_display', label: I18n.t('my.application.index.title_display')
-```
-
-The given label is also passed through an i18n filter for adding e.g. prefixes and suffixes. By default, Blacklight will append a ":" to the field value.
-
-#### Model Accessors
-
-If the value you wish to display is defined on the model, instead of in a single solr field, you can configure Blacklight to use an accessor on the SolrDocument instance:
-
-```ruby
-config.add_index_field 'title_display', :accessor: 'title'
-```
-
-This will call `document.title` to get the value of the field, e.g.:
-
-```ruby
-class SolrDocument
-  def title
-    first(:main_title) + " - " + first(:sub_title)
-  end
-end
-```
-
-will concatenate the main and sub titles.
-#### Highlight
-
-Solr supports query hit-highlighting. Blacklight can display the highlighted version of the field:
-
-```ruby
-config.add_index_field 'my_highlighted_field', highlight: true
-```
-
-#### Helper Method
-
-When preparing a value for display, Blacklight can be configured to call a custom helper method. 
-
-```ruby
-config.add_index_field 'some_field_with_an_external_link', helper_method: 'make_this_a_link'
-```
-
-```ruby
-module ApplicationHelper
-  def make_this_a_link options={}
-    options[:document] # the original document
-    options[:field] # the field to render
-    options[:value] # the value of the field
-
-    link_to options[:value], options[:value]
-  end
-end
-```
-
-#### Link To Search
-
-Some display fields are also facet fields, and often it makes sense to link the displayed value to the corresponding facet selection.
-
-```ruby
-config.add_index_field 'genre', link_to_search: true
-```
-
-Or use the value in a link to a different field (e.g. if your display field is not indexed)
-
-```ruby
-config.add_index_field 'genre', link_to_search: 'genre_facet'
-```
-
-#### Schema.org configuration
-
-```ruby
-config.add_index_field 'genre', itemprop: "genre"
-```
-
-The genre values will be marked up as schema.org genre values.
-
-### View Types
-
-Blacklight provides a default "list" view of results.
-
-### (Advanced) Results Grouping
-
-# Show view
-
-![Show view](https://f.cloud.github.com/assets/111218/2058440/e32f32a6-8b71-11e3-9bd5-20b0a3af2fea.png)
-
-
-## Advanced Configuration
-
-You can also use the field configuration to inject field-specific configuration
-
-```ruby
-config.add_index_field 'an_index_field', solr_params: { 'hl.alternativeField' => 'field_x'}
-config.add_show_field 'a_show_field', solr_params: { 'hl.alternativeField' => 'field_y'}
-# provided you also use: config.add_field_configuration_to_solr_request!
-```
-
-This will add field-specific parameters to the solr request.