Add forms with actions to Sierra WebPAC.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
app
cache
public
src
templates
.gitignore
LICENSE
README.md
composer.json
composer.lock
config.yaml.example

README.md

sierra-actions

Add forms with actions to Sierra WebPAC.

Background

The unique materials in the special collection libraries at BGSU (Music Library and Bill Shurk Sound Archives, Browne Popular Culture Library, and the Center for Archival Collections) contain treasure troves of materials for researchers. Until recently, all collection use was tracked using paper registration forms but with the advent of the ACA/PCA's (American Culture Association/Popular Culture Association) Popular Culture Summer Research Institute at BGSU in 2016, closed stack special collections experienced intensive use in conjunction with the Institute that overwhelmed the paper processes of the past and were unsustainable!

The special collections departments worked with Access Services and Library Information Technology Services to find a way to use Sierra and enhancements to the local OPAC to improve patron experience, automate collection of usage statistics, strengthen security, and streamline service point workflows. This project expanded to support collaboration between the Curriculum Resource Center and the BGSU Firelands Library.

The resulting code from the project is shared in this repository. While it is specific to BGSU's catalog and collections, it can be altered to suit the needs of other libraries as described below. There are two primary parts: a Javascript file which adds buttons to items in the bib display of Sierra WebPAC, and a PHP web application which provides forms to handle the actions of those buttons.

Javascript

The PHP application generates a Javascript file based on the configuration described below. This file is available in the public directory at /button.js. For example, if the application is installed on a path named actions on the server example.edu, the Javascript may be referenced with:

<script src="https://example.edu/actions/button.js"></script>

The Javascript file depends upon jQuery being available, and must be loaded after jQuery is loaded. At BGSU, this Javascript is added to the screens/botlogo.html file for the Sierra WebPAC. Since it looks for particular information only available on detailed item records, it should be safe to include on other pages.

BGSU's Javascript as Example

You may want to use your own application to handle applications instead of the version offered by this project. In that case, you may be interested in reviewing BGSU's copy of the Javascript file for adaption to your own system. It is online at: https://lib.bgsu.edu/catalog/actions/button.js

PHP Application

Installation

The package can either be installed by cloning the repository or downloading and extracting an archive from the releases page. The resulting directory should be placed outside of the document root for the web server.

Dependencies

Dependencies are included with the archives provided by the releases page. When installed by cloning the repository, dependencies must be installed via Composer by running a command like the following from the application's directory:

php composer.phar install

Permissions

Write permissions must be granted to the webserver for the cache/ directory. If you configure the application to store a log file below, that directory must also be writable by the webserver.

Configuration

Configuration is stored in the config.yaml file. An example based on what BGSU uses is provided in the configy.yaml.example file, and you can begin by copying it over:

cp config.yaml.example config.yaml

The file uses YAML to store configuration values.

Application Settings

The setting app.debug is primarly enabled when developing the application, and provides additional details with error messages. app.log specifies the full path to a log file to store error messages generated by the application.

app.redirect should be configured to redirect users to your catalog or another site if they access the application directly instead of via the buttons added to the catalog.

Template Settings

These settings are primarly included to enable the use of a centralized collection of templates. If left as the default, you may edit the file templates/page.html.twig to configure the standard template used for each page. See below for further details about templates.

SMTP Settings

smtp.host and smtp.port should be configured with the details for your SMTP server.

Actions

actions is a hash specifying the individual actions that are handled by the application, specific to the locations and statuses of items. The key of each hash item may be used within templates. The value is itself a hash specified as so:

  • action: The full name of the action. Besides being displayed to the user, this also defines the URIs to the form (after lowercased and replacing whitespace with dashes) and the file names of the action classes and templates (after removing whitespace).
  • location: A Javascript-style regular expression that matches the location of the item within the WebPAC display. If you only want to match one location, you can just pin that location to the begginning and end of the regular expressions, ie. ^Location$.
  • status: A Javascript-style regular expression that matches the status of the item within the WebPAC display. If you only want to match one status, you can just pin that status to the begginning and end of the regular expressions, ie. ^Status$.
  • button: HTML to be included within the anchor element used within the WebPAC. If left undefined, the action will be used. An example usage is for specfying an image element for the button.
  • email: The email address that submissions to this action will be sent to.

Web Server

The public/ directory is what needs to be served by your web server. BGSU accomplishes this by creating a soft link to public/ within the server's document root, for example:

cd /path/to/htdocs
ln -s ../path/to/application/public actions

You may also consult the documentation of you server for alternative ways of serving specific directories.