bpl-mapportal development guide

bpl-mapportal_development-guide.md

bpl-mapportal development guide

The goal of this project is to update the major dependencies for an existing Rails application currently in production.

This application is a digital library interface that provides access to historical maps from the Norman B. Leventhal Map & Education Center at the Boston Public Library. The application allows users to search the collection, view image content, download high-resolution files, sign up for an account, and create lists of favorite items, as well as other features.

URL: https://collections.leventhalmap.org/

Code: https://github.com/boston-library/bpl-mapportal/tree/develop/src/portal (private repo)

Current dependencies: Ruby: 2.2, Rails: 4.2, Bootstrap: 3.2, Blacklight 6.3.3

Desired dependencies: Ruby: 3.4, Rails 7.2, Bootstrap 5.3, Blacklight 8.11.0

Other major objectives for this project include:

1. Replace CASino-based login functionality with devise
2. Replace georeferencing functionality with blacklight-allmaps gem (https://github.com/bplmaps/blacklight-allmaps)
3. Remove unwanted models, controllers, views, routes, and specs for:
   • CurriculumMaterial
   • Exhibit
   • MapSet
4. Add puma as the application server
5. Dockerization for development (Dockerfile and docker-compose.yml)

The preference would be for the updated application to use:

• importmap-rails for JavaScript dependency management
• cssbundling-rails for CSS dependency management
• propshaft for asset fingerprinting

Overview

This project will not add new functionality or features to the application, the primary objective is updating the existing application code, graphic design, and tests to work with the latest versions of Ruby, Rails, and Bootstrap.

The visual design of the site should be maintained as close to the current appearance as possible; the HTML, CSS, and JS code will need to be refactored to use Bootstrap 5 components and styles. Some dependencies and functionality that are no longer desired will also be removed (see below).

The relevant Rails application code (./src/portal) is currently embedded in a larger code repository that includes development container configuration, other applications, and deployment playbooks -- it should be separated from these components and extracted to a new repository. Refactoring existing or creating new deployment code is not a part of this project.

Major dependencies

• Blacklight (https://projectblacklight.org/) - an open-source discovery framework for creating a discovery interface for any Solr (http://lucene.apache.org/solr) index. Blacklight is used by many major university libraries, including Stanford, Yale, Columbia, etc.

• commonwealth-vlr-engine (https://github.com/boston-library/commonwealth-vlr-engine) - a gem maintained by BPL for creating Blacklight apps that display content from BPL's digital repository, and include a number of feature-rich enhancements and modifications.

Environment variables

To get the existing application running in development, you will need to have a number of environment variables set. Some of these are for typical Rails enviroment settings (database), while others correspond to APIs maintained by BPL that are necessary for displaying search results and images.

You can see a guide to these in ./deployment.

And the values needed for the development environment are provided in: ./deployment/ansible/group_vars/development

Env vars starting with BPL_MAPPORTAL_WARPER* correspond to a different application (in ./src/warper) and should not need to be set.

Views that need to work in the final deliverable

/ (home page)
/advanced
/collections
/collections/:id
/search
/search/:id
/favorites
/favorites/new
/favorites/:id
/favorites/:id/edit
/login
/users/:id
/users/edit
/users/sign_up
/users/password/new
/search_history

Dependencies that can eventually be removed

These will no longer be needed in the final deliverable:

• geoblacklight
• jettywrapper
• activerecord-postgis-adapter
• hydra-role-management
• sir_trevor_rails
• paperclip
• spawnling

Building a new app

Make sure that ruby 3.4.* is running and the bundler and rails (7.2) gems are installed.

Note: The commonwealth-vlr-engine gem with compatibility for the target Ruby/Rails/Bootstrap/Blacklight dependencies is still under active development but able to be used. For now you should install it from Github rather than RubyGems.

Create the app:

$ rails new bpl-mapportal_v2 -a propshaft --css=bootstrap

Add to Gemfile

gem 'commonwealth-vlr-engine', github: 'boston-library/commonwealth-vlr-engine', branch: 'blacklight-8'
gem 'dotenv-rails', '~> 2.7' # makes setting ENV vars easier

Then:

$ bundle install

Run generators for several dependencies:

# blacklight and devise:
$ rails generate blacklight:install --devise

# installers for several blacklight-related gems and commonwealth-vlr-engine
$ rails generate commonwealth_vlr_engine:install

# NOTE: when prompted
# Overwrite /path/to/bpl-mapportal_v2/config/locales/blacklight.en.yml? (enter "h" for help) [Ynaqdhm] 
# Enter Y

Install font-awesome

$ yarn add @fortawesome/fontawesome-free # for CSS
$ ./bin/importmap pin @fortawesome/fontawesome-free # for JS

Edit config/initialiazers/assets.rb and add:

Rails.application.config.assets.paths << Rails.root.join("node_modules/@fortawesome/fontawesome-free/webfonts")

Edit app/assets/stylesheets/application.bootstrap.scss and add:

$fa-font-path: ".";
@import "@fortawesome/fontawesome-free/scss/fontawesome.scss";
@import "@fortawesome/fontawesome-free/scss/solid.scss";
@import "@fortawesome/fontawesome-free/scss/brands.scss";
@import "@fortawesome/fontawesome-free/scss/regular.scss";

Edit app/javascript/application.js and add:

import "@fortawesome/fontawesome-free"

Install Universal Viewer

$ yarn add [email protected] # for CSS

Edit config/initialiazers/importmap.rb and add:

pin "universalviewer", to: "https://cdn.jsdelivr.net/npm/[email protected]/dist/esm/index.js"

Edit app/assets/stylesheets/application.bootstrap.scss and add:

@import "universalviewer/dist/esm/index";

Edit app/javascript/application.js and add:

// universalviewer import MUST be after jquery and before blacklight-gallery
import "universalviewer"

Add asset references for locally installed commonwealth-vlr-engine:

Eventually there will be an NPM package for commonwealth-vlr-engine, but for now you should link to the locally installed gem for CSS assets. Run $ bundle info commonwealth-vlr-engine to get the path to your local install.

Edit package.json and add to "dependencies":

"commonwealth-vlr-engine": "link:/absolute/path/to/gems/commonwealth-vlr-engine-{SHA}",

Then:

$ yarn install

Edit app/assets/stylesheets/application.bootstrap.scss and add:

@import 'commonwealth-vlr-engine/app/assets/stylesheets/commonwealth-vlr-engine/commonwealth-vlr-engine';

Edit app/javascript/application.js:

import 'commonwealth-vlr-engine'

Configure ENV vars

$ cp /home/eenglish/.rvm/gems/ruby-3.4.2/bundler/gems/commonwealth-vlr-engine-{SHA}/spec/internal/.env.development.sample ./.env.development

Edit .env.development:

# change VLR_SITE_ID value to this:
VLR_SITE_ID=nblmc

# add this:
SOLR_URL=https://index-dc3dev.bpl.org/solr/curator_staging

Run the migrations:

$ rails db:migrate

Start the app:

$ bin/dev

The app should be running on localhost:3000. Try searching for map and you should get a list of results.

Add an image for the home page hero block

# start the rails console
$bin/rails c

CarouselSlide.create(context: 'root', image_pid: 'bpl-dev:kk91fm322', institution: 'Norman B. Leventhal Map & Education Center Collection', object_pid: 'bpl-dev:9g54xj476', region: 'pct:10,20,80,23', size: '1600,', title: "General map for artillery objectives up to the of 24th August 1918")