Versions Compared

Old Version 3

changes.mady.by.user James English

Saved on

compared with

New Version Current

changes.mady.by.user James English

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The Circulation Patron Web (CPW) Catalog is a web application that displays the libraries eBook and audio-book collection as published by the circulation manager.  The circulation-patron-web application supports the following features:serves as a way for libraries to view their collections on the web. A library must be part of a Circulation Manager and can be registered to a Library Registry. Currently, in order for a library to be part of Library Simplified and show up in the SimplyE application, they must register with NYPL's Library Registry. A Library Registry provides details about a library, and a Circulation Manager provides a library's collection of eBooks and audiobooks in OPDS format.

The circulation-patron-web app can be used to host multiple libraries, either from a single Circulation Manager or from multiple Circulation Managers. The most common scenario may be for a single-library, where the app renders the main library of a Circulation Manager, but it is also often used to serve the catalogs of many libraries at different URLs. 

The web application supports the following basic features:

  • Browsing a catalog - The lists and lanes configured in the Circulation Manager will show up in the web catalog and be publicly browsable.
  • Viewing Book Details - A user can click on a particular book to view the full details for that book.
  • Authentication and Log in to Library Account (SAML and ILS)
  • Links to Library Web websites and pages (links configured in the Circulation Manager Library Admin Interface)
  • Primary and Secondary colors and Logo (Configured in the Circulation Manager Library Admin Interface)
  • Browsing Lists and Lanes
  • Viewing Book Details
  • Viewing Read-a-likes and Recommendations - Read- a- likes are same author and same series grouped feeds published by the circulation manager (Recommendations require a Novlesit Novelist account configure in teh the Circulation Manager). These show up when viewing a book details page to aid the user's discovery of new content.
  • Authentication and Log in to Library Account via Barcode and Pin, SAML, OAuth, Clever and FirstBook.
  • Borrowing Books
    • Borrowing available books
    • Placing holds on unavailable books
    • Returning or revoking a loan - This is available in most situations, but it depends on whether the content vendor provides this ability for us.
  • Reading Books - How the user chooses to read a book depends on the formats available
    • Download Book - For
      • Placing Holds
    • Downloading EPUBs, PDFs, Mobi and Mobi8 (including as well as Adobe ACSM files)
    • Opening Web Reader (if available from content hosts)
    Viewing Book Shelf
    • Read Online - Some content hosts offer the ability to read the book in a web reader. We will provide the option when available.
    • Read in SimplyE - For some formats, it is preferred that the user reads the book in the mobile app. One example of this is the Adobe ACSM file. For these formats, the app can be configured to direct the user to read the book in the SimplyE mobile app instead of downloading an ACSM file, which may be difficult to use.
  • Viewing Bookshelf - Users can see their loans and holds on their bookshelf.
  • Accessibility - The web catalog interface is built with web accessibility in mind, which means full support for screen readers, sufficient color contrast, support for zoom, and more. 
  • Responsive design - The interface is built to adapt fluidly to different screen sizes so that it can be used on anything from a phone to a desktop computer without issue. 

CPW Repositories

Github: https://github.com/NYPL-Simplified/circulation-patron-web

CPW Technology and Framework

CPW is a React application built using the Next.js framework. It uses server-rendering and incremental cacheing of pages in order to provide fast page loads. The application is unit tested on every pull request, with currently about 90% test coverage. Development is a concerted effort made by multiple organizations including Lyrasis, The New York Public Library, Amigos Library Services, and others. The code is fully open-source and can be contributed to by anyone. 

CPW Configuration and Deployment

Every time a change is merged into the beta or master (production) branches of the github repository, a new Docker image is built and pushed to the Docker Hub Repository. In addition, every PR contains a few preview links to Vercel deployments, which are useful for testing new functionality and sharing it with the community before merging it into the codebase.

You can see the current beta version deployed at ebooksbeta.lyrasistechnology.org, which is automatically updated anytime code is pushed to the beta branch. Because the application can host multiple libraries, the root url will show a list of the available libraries to choose from. This is not meant to be a patron-facing page, but simply used by the maintaining community to see and navigate between the different libraries on a deployment. Each library home page is available at its own url path, for example ebooksbeta.lyrasistechnology.org/howard for the Howard County Library System beta version. 

There are two main places that configuration is set for CPW. The first is settings for each library configured in their respective Circulation Manager interfaces. These settings are sent to CPW from the circulation manager to configure how the app will run. The second place is the config file for an entire CPW instance. Recall that CPW can host catalogs for multiple libraries, so the settings in a CPW config file would apply to every library on that instance.

1. Setting up a library for CPW in the Circulation Manager

There are a few configurations in the Circulation Manager that are important for setting up a CPW deployment. 

  1. CORS Settings: Web applications can only access servers that are specifically configured to allow requests from that domain. For example, if CPW is running on ebooksbeta.lyrasistechnology.org, and you would like it to host a library in a Circulation Manager running on circ-manager.library.org, then the Circulation Manager needs to be configured to allow access from ebooksbeta.lyrasistechnology.org.
  2. Primary and Secondary Colors: Both the primary and secondary colors for the library can be configured in the Circulation Manager interface. Both of these colors need to have sufficient contrast with the color white, so that white text is legible on top of this color background and vice-versa. The Circulation Manager interface will check the contrast of your selected colors and will show an error if there is not sufficient contrast.
  3. Logo - The logo to display in the web catalog interface for this library. It will be shown in the upper left corner.
  4. Header links - These links will be displayed in the header of the web catalog. It may be useful, for example, to provide a link back to the main library home page.
  5. Other - The other standard Circulation Manager settings also apply to the web catalog, such as authentication setups, lanes, library name, help links, etc.

2. Setting up a CPW Config File

Some configuration settings apply to the entire CPW instance, whether there are 1 or 1000 libraries being hosted on it. These settings are set in a YAML config file, which is then hosted somewhere on the internet. The URL to that file is then provided to CPW when running the application. The configurable settings are:

  1. bugsnag_api_key - The optional API key to your Bugsnag account for error tracking (more below).
  2. gtm_id - The optional id for your Google Tag Manager account for web analytics (more below).
  3. show_medium - Whether or not to show medium indicators on books. If you expect your library to only have ebooks, for example, you may want to set this to "false". The default is "true".
  4. media_support - The media types supported by the library, and how they are supported. You can choose to hide some formats, or redirect users to read certain formats in the mobile app.
  5. libraries - This is where you set either a dictionary of libraries the app will host, or a url to a single library registry.

More info on setting up a CPW config file can be found in the Github Repo README. 

Deploying via Docker

To deploy via Docker, simply pull the public docker image from Docker Hub, and run the docker image with a provided config file. More info can be found in the README.

CPW User Analytics (Optional)

An optional option for capturing Web Analytics events is to use Googles Tag Manager service to needed analytics events that can then be hosted to a host providers reporting database solution for providing more detailed analytics for a library using SimplyE or managing a CPW instance for Libraries.

Future CPW Analytics Development Work

https://jira.nypl.org/browse/SIMPLY-2178 analytics events to be initiated by clients

https://jira.nypl.org/browse/SIMPLY-3306  Performance Analytics

https://jira.nypl.org/browse/SIMPLY-2686  CPW circulation-patron-web the same level of analytics support found in SimplyE mobile

https://jira.nypl.org/browse/SIMPLY-3164  Server Initiated Analytic Events

https://jira.nypl.org/browse/SIMPLY-1868 Detect Incoming Cleint Agent on CM request to enable improved device analtyics

CPW Application Error Reporting (Optional)

An optional Big reporting tools can be configured into an instance of the CPW using Bugsnag.