a unified search box

SoCal Code4Lib Meetup
Decemember 15, 2015

R. S. Doiel, rsdoiel@caltech.edu / rsdoiel.github.io
Application Development for Caltech Library

Project: http://caltechlibrary.github.io/unified-search-box

backstory

I am relatively new to Caltech Library and modern library systems (since April 2015). But I have been building things for the web for about 20 years. I am still learning (and that is what makes it fun).

a walkthrough in three acts

1. the problem, constraints, finding the right solution path
2. protoypes, discoveries and revisions
3. implementation, benefits and what’s next

1. the problem

• The library has many search systems
• Useful for Librarians or to bookmark
• But many patrons prefer a one-box search approach

The starting point: Catalog Searchbox

a solution?

Our Librarians spotted a solution

MIT Library has a nice implementation close to what we need

• MIT Library
  • Implemented in Wordpress
  • Relies on jQuery

But not exactly suited to the current evolution of library.caltech.edu

some starting constraints

• we were planning a complete website re-design
  • this project is interum, we’re managing legacy
• our infrastructure is rather organic
  • this suggested an evolutionary approach
  • so I couldn’t assume Wordpress/Drupal at this stage
• I didn’t know what browsers variations to expect for our visitors
• I did know I needed to support browsers which may have JS turned off
• I might need to support ones that were really stale (I’m looking at you IE 6)

initial technical choices

• given legacy nature of current website
  • I was skipping a responsive approach
  • but wanted to take a progressive enhancement approach (more on that)
• simple enhancement from no-JS to evergreen browsers
  • Default links to individual search pages in NOSCRIPT element for no-JS
  • Use JS to load MIT like implementation
    • put configuration into the HTML data attributes (more on that)
  • rely on CSS as much as possible
  • build staticly and iterate through prototyping

browsers and content

Our legacy website implementation dated from the IE 6 era. I realize it was unreasonable to use normal progressive enhancement (e.g. test for features, polyfils, etc). I did recognize website was designed when graded browser support was the best practice.

graded browser support

• Approach was made popular at Yahoo many years ago
• It lets you breakdown the browser support challenges into something manageable
• It can be revised moving forward
• Historically based on the browser versions/types identified accessing your website

a feature oriented variation

Inspired by progressive enhancement

• Picked a baseline (minimal feature set)
• Decided what was needed for enhanced features
• Verified browsers supporting those features (caniuse)
• Avoided explicit browser sniffing
• Still had the option of feature detection if necessary

This lead to a ultra simple graded browser system use case.

three browser grades

• Our Grade A browsers have to support
  • document.querySelector() and document.querySelectorAll()
    • Desktop: IE 10/Edge 13, Firefox 42, Chrome 47, Safari 9
    • Mobile: iOS Safari 9.2, Chrome for Android 47
• Grade B, browsers have JS disabled (or not available, e.g. Lynx)
• Grade C, everything else to be addressed as time permits

Grade A was testable with the help of others (e.g. people who had iPhones)

the planned approach

Implement from lowest grade browser and progresses to highest

1. Grade C, I punted (a highly technical software engineering fete)
2. Grade B, implemented first
   • Quick and easy, just HTML (a NOSCRIPT element) and a dusting of CSS
3. Grade A, this is where I spent most of my time
   • start with one browser, moved to the next in the list
   • make time to revisit each browser with each new version released
   • this takes a while

2. prototypes, why prototype?

“Fail early when the costs are low”, Silicon Valley ethos

1. Gives you, the developer, space to learn and work the problem
2. Gives you permission to really find out what the requirements are
3. Provides a sense of progress and discovery for your client

I went through five prototypes before focusing on implementation.

GOTCHAS!

Browser side

• My original plan to use data attributes to pass configuration was not reasonable
  • I switched to a JavaScript data structure, could have used a JSON blob
• CSS can still be really painful thing to debug
  • Implementing the production version required re-working the CSS to work with the rest of the page
  • This left me with some ugly, long id and class names (CSS lacks namespacing)
  • In the future I’ll take the SMACSS approach
• Each Browser security release triggers another round of browser testing
  • It would be good to automate as much of this as possible
  • I relied on a human readable test list

GOTCHAS!

Server side

• CORS now widely supported but not necessarily configured in systems
  • wrapping pages in PHP to generate appropraite CORS header was easy short term fix
• I wanted SSL everywhere vs. non-SSL for some searches in legacy implementation
• But this required strategy for our SSL Certs
  • without that some CSS and JavaScript inclusion was broken
  • that change impacted other systems that also used the proxy
  • that required coordination

Thank you Betsy for coming to the rescue!!!

3. implementation

• Configuration moved from data attributes in HTML to JavaScript data structure
• Used a web components approach but implemented as old-school HTML+CSS+JS
• Deployed in phases

working code

• v1 has been in use since early Fall
• v2 EDS support being tested now
  • Scheduled for general deployment Dec 21st after finals but before Winter break

Benefits

• Very minimal JavaScript, CSS and HTML foot print added to homepage
• Limited what had to be tested to a managable set of browsers
• Can easily be re-factored for when we do go responsive via progressive enhancement
• Fit as well with prototyping as with eventual retrofit of library’s homepage

road map

• V2 Beta becomes production version
• V3 adding some requested features (e.g. sticky search option selection)
• V4? turn into a Web Component?

thank you

Presentation:
caltechlibrary.github.io/unified-search-box/presentation.html
R. S. Doiel, rsdoiel@caltech.edu
rsdoiel.github.io