README

This repository contains a Blacklight instance that uses the Harvard LibraryCloud Item API as a backend in place of the standard Solr backend. It also allows adding items to the LibraryCloud collections using the Collections API.

Demo site: http://dcp-dev2.lib.harvard.edu:8080/

Deployment

Heroku

Create a new application on Heroku
If not already installed, install the Heroku command-line tools as per https://devcenter.heroku.com/articles/heroku-command-line and login to your Heroku account
On the "Deploy" tab for your application, select "Heroku Git" as the deployment method
Clone this repository
Add the Heroku repository as a remote

heroku git:remote -a [MY APPLICATION NAME]

Push the code to Heroku

git push heroku master

On the "Settings" tab add a new Config Variable named LC_API_KEY with the value of your LibraryCloud API key. (This is only required for the "Add to Collection" functionality)

RHEL

Install Postgres and the Postgres development libraries, if not already installed. Make sure the database is running
Install Ruby following these instructions: https://gorails.com/setup/ubuntu/17.10#ruby-rbenv

cd
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
exec $SHELL

git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
echo 'export PATH="$HOME/.rbenv/plugins/ruby-build/bin:$PATH"' >> ~/.bashrc
exec $SHELL

rbenv install 2.5.0
rbenv global 2.5.0
ruby -v

gem install bundler
rbenv rehash

Install Rails

gem install rails -v 5.1.4
rbenv rehash

Install Solr for Blacklight

(This may not actually be necessary, since we're not using Solr)

gem install solr_wrapper
rbenv rehash

Install the Application

git clone https://github.com/harvard-library/STLee-blacklight.git
cd STLee-blacklight/
bundle install

Configure the database connection

Edit config/database.yml with credentials that match the Postgres user and database that you are using. For example, change the 'development' section as follows, to add username and password configuration keys:

development:
  <<: *default
  database: mydatabase
  username: myusername
  password: mypassword

Initialize the database

bundle exec rake db:migrate

Start the application

rails server

Documentation of Code Changes

Use the LibraryCloud Item API

These changes allow Blacklight to use the LibraryCloud API as the backend data store, rather than a Solr index .

app/controllers/catalog_controller.rb

This is the main configuration file for an installation of Blacklight. Changes in this file are:

Swap out the Blacklight classes that interact with Solr for our own classes that interact with the LibraryCloud API

    ## Class for sending and receiving requests from a search index
    config.repository_class = Harvard::LibraryCloud::Repository
 
    ## Class for converting Blacklight's url parameters to into request parameters for the search index
    config.search_builder_class = Harvard::LibraryCloud::SearchBuilder
 
    ## Model that maps search index responses to the blacklight response model
    config.response_model = Harvard::LibraryCloud::Response

Set the relative path to be appended to the Base URL when making API queries. In a traditional Blacklight installation this will identify the Solr core to be used. In our case, we use it to identify the record format (JSON + MODS) to return

# Path which will be added to the API base url before the other API params.
config.solr_path = 'items.json'

Configure the fields that Blacklight uses for display, searching, sorting, and faceting. These need to match the fields returned by the LibraryCloud API. The methods and attributes used to set the fields are:

config.index.title_field
config.index.thumbnail_field
config.show.title_field
config.show.thumbnail_field
config.add_index_field()
config.add_show_field()
config.add_search_field()
config.add_sort_field()
config.add_facet_field()

Disable autocomplete. Since the LibraryCloud API does not support autocomplete, this will result in an error if enabled

config.autocomplete_enabled = false

app/helpers/application_helper.rb

Contains miscellaneous helper functions

app/models/solr_document.rb

Create a model for the document that will be used to display content in Blacklight on index and detail pages. Takes a MODS document from LibraryCloud and returns a flat list of fields with values.

config/application.rb

Allow the application to find the Harvard::LibraryCloud package in the lib directory

config/database.yml, config/environments/production.rb, and db/schema.rb

Changes to allow the site to be deployed to Heroku (use Postrgres instead of sqlite)

lib/harvard/library_cloud/repository.rb

This is the primary interface through which Blacklight interacts with Solr (or in our case, the API). It replaces lib/blacklight/solr/repository.rb which is distributed with part of the Blacklight gem. The code is mostly the same as that in the file it replaces, with the following changes:

build_connection() returns a Harvard::LibraryCloud::API rather than an RSolr connection
Some log statements and variable names are changed to clarify they reference the LibraryCloud API rather than Solr (for example solr_response is renamed to api_response)

lib/harvard/library_cloud/api.rb

This class handles the actual interaction with the LibraryCloud API. This includes:

Mapping the Blacklight request parameters to LibraryCloud API parameters. The parameters passed to this class are the same as those passed to RSolr in a standard Blacklight configuration, so they need to be altered to reflect the difference between Solr and LibraryCloud API syntax
Adding parameters to the LibraryCloud API query to limit results to public items in DRS
Making the actual HTTPS call to the LibraryCloud API

lib/harvard/library_cloud/response.rb

Parse the response received from the LibraryCloud API. Inherit from the response.rb provided by Blacklight, and override certain functions as needed to handle differences between the responses provided by LibraryCloud and Solr.

Including Harvard::LibraryCloud::Facets rather than the Blacklight facet module ensures that facet responses are parsed correctly based on the LibraryCloud format.

lib/harvard/library_cloud/facets.rb

Replaces lib/blacklight/solr/response/facets.rb which is distributed with part of the Blacklight gem. The code is mostly the same as that in the file it replaces, with the following change:

facet_fields() is changed to parse facets using the LibraryCloud format rather than the Solr format

lib/harvard/library_cloud/search_builder.rb

Blacklight defines a processor chain that can be used to add additional fields to the query. We use that here to add the 'search_field' parameter, which is required for the LibraryCloud API, but not Solr

Apply custom design

These change apply a custom design to the default Blacklight installation. The home, search, and item detail pages have been updated with the new design.

app/controllers/catalog_controller.rb

Configure the "actions" that we want to display for items in the results by removing unwanted actions using config.show.document_actions.delete()
Define the partials (_FILE.html.erb) that we want to include on the index and item detail pages, in the desired order

config.index.partials = [:thumbnail, :index_header, :index]
config.show.partials = [ :show_header, :show_original, :show]

Set the options for the pager

config.per_page = [12,24,48,96]

Additional steps to apply the design

Install the Foundation 5 framework using the foundation-rails gem
Create a master SASS file at app/assets/stylesheets/application.scss and additional SASS files under app/assets/stylesheets/_*.scss
Add icons for the different document types at app/assets/images/icons/*.svg
Add image assets for the home page at app/assets/images/*.png
Add helper class to support displaying images using the <picture> element at app/helpers/images_helper.rb
Create partials under app/views to override the default Blacklight layout

Add items to LibraryCloud Collections (Item Detail Page)

Create an action that allows adding items to collections through the LibraryCloud Collections API.

app/controllers/catalog_controller.rb

Include the Harvard::LibraryCloud::Collections module to handle the "Add to Collection" functinality, so Blacklight can find it

include Harvard::LibraryCloud::Collections

Add the "Add to Collection" action

add_show_tools_partial(:add_to_collection, define_method: false)

lib/harvard/library_cloud/collections.rb

Define method add_to_collection which is called by BlackLight when the 'Add to Collection' dialog is displayed
Define method add_to_collection_action which submits one or more items to be added to a LibraryCloud collection
Define method add_to_collection_solr_document_path which is called by BlackLight to define the URL to invoke the "Add to Collection" action
Define methd available_collections which retrives a list of collections to which an item can be added

app/views/catalog/add_to_collection.html.erb

Modal for displaying the "Add To Collection" form

app/views/catalog/_add_to_collection_form.html.erb

Partial that renders the "Add to Collection Form"

app/views/catalog/add_to_collection_success.html.erb

Modal for displaying the "Succes" message after an item is added to a collection

Add items to LibraryCloud Collections (Search Results Page)

Allow users to add items to the collections in bulk from the search results page.

app/controllers/catalog_controller.rb

Add the "Add to Collection" action to items in the search results

add_results_document_tool(:add_to_collection, define_method: false)

CSS and Javascript to handle selecting checkboxes

We use Javascript to dynamically update the form submit URL for the "Add to Collection" action in the app/views/catalog/_add_to_collection_index_action.html.erb partial. And a bit of CSS to make it look better. The relevant files are:

Known Issues

Not possible to select multiple choices within a single facet.
- Workaround: set “single: true” on the facet_field configuration
- Reason: LC API doesn’t handle queries on the same field correctly)
“More” option for facets is not enabled.
- Workaround: do not specify a “limit” on the facet_field configuration
- Reason: Not implemented
“Autocomplete” functionality does not work
- Workaround: disable it in the catalog_controller
- Reason: not supported by LibraryCloud API
Can only sort by relevance
- Workaround: Use “relevance” as the only sort option
- Reason: Sorting by date not supported by LibraryCloud API
When adding an item to a collection, all collections are displayed as options, including those that the current "user" (API key) doesn't have permission to change
- Workaround: Use an admin API key to allow adding to any collection
- Reason: Collections API does not allow filtering collections by owner

Name		Name	Last commit message	Last commit date
Latest commit History 108 Commits
app		app
bin		bin
config		config
db		db
deploy		deploy
lib		lib
log		log
public		public
solr		solr
test		test
tmp		tmp
vendor		vendor
.gitignore		.gitignore
.solr_wrapper.yml		.solr_wrapper.yml
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
README.md		README.md
Rakefile		Rakefile
config.ru		config.ru
package.json		package.json
release.txt		release.txt
stlee_dev		stlee_dev

harvard-library/STLee-blacklight

Folders and files

Latest commit

History

Repository files navigation

README

Deployment

Heroku

RHEL

Documentation of Code Changes

Use the LibraryCloud Item API

config/database.yml, config/environments/production.rb, and db/schema.rb

Apply custom design

Additional steps to apply the design

Add items to LibraryCloud Collections (Item Detail Page)

Add items to LibraryCloud Collections (Search Results Page)

CSS and Javascript to handle selecting checkboxes

Known Issues

About

Resources

Stars

Watchers

Forks

Languages