February 28, 2012

Receipt Editing in Evergreen 3

This post is the last of a series.

There is, of course, at least one more consumer of receipts in a library setting: library staff. If items are pulled from the shelf to fill a hold they'll have receipts printed, the same if an item can fill a hold when it's checked in. Many libraries will only hold an item for a limited time before returning it to the shelf or letting another person have it, so you might want to write an expiration date on it. Also, if you have any  holds volume to speak of, the items on the hold need to be kept in some kind of order or no one can find anything - so that's more writing, highlighting, or circling names on receipts.

If only it were possible to simplify and automate this stuff.

Route item to Holds Shelf:
The Title of The Item
Barcode: 31234000000032
Request date: 2012-01-15


Hold for Boyer, Jason
Barcode: 21234000000041
Notify by phone: 555-876-5309

Item checked by Jason

YRLIB 2012-02-22 13:42

Oh, right.

Only 3 more CSS trigger classes are needed for this. Here are the rest of the classes defined in my custom_format.js, and below you can get a copy to add to, remove from, etc., along with templates if you're interested.

If there's a date in the tag, N days (by default) or weeks are added to it. If the tag is empty, N days or weeks are just added to the current date.

<span class="mod-DateAdd-7">2012-02-22 11:32 AM</span>2012-02-29

Maybe you don't want the full text of item or patron information. A substring of the tag's contents are taken starting from N1 (begins at 0), going either to the end of the string, or N2 characters long.

<span class="xf-SubStr-3-4">BigTextTime</span>Text

This takes a date and returns a month/date format. If there isn't a date in the tag, it uses today. It's not currently zero padded, if you care about that.

<span class="xf-DateToMonthDate">2012-03-07</span>3/7

Having seen all of those transform classes, it might be nice to be able to actually use them. A generic copy of my custom_format.js is available that you can download and customize. The receipt templates are also available. A reminder: you need to save after changing each template. If you think you'll make changes to multiple templates and then only click Save Locally at the end, you're just going to get upset. I have been upset before; learn from that.

February 24, 2012

Receipt Editing in Evergreen 2

Alternate title: Yo dawg, I heard you like spans…

So what is the deal with all of those spans and their seemingly useless CSS classes? To answer that, we'll have to take a brief detour into how receipt editing used to work in Evergreen before 2.1.

Ine Ye Olde Paste
It used to be that you could simply in-line JavaScript whenever necessary to achieve an effect that wasn't possible with simple HTML and substitution. Such as:

Your item is due:
<script type="text/javascript">
var dt = new Date("%date_due%");
document.write(dt.getUTCMonth() + "/" + dt.getUTCDate() + "/" + dt.getUTCFullYear());

Which would print Your item is due 02/29/2012.

While it may not be great practice on a web page to inline a bunch of document.write()'s all over the place, it worked just fine in this case. It's not as if we had to worry about how Internet Explorer would render it or a screen reader; if it worked in the preview, it worked, the end.

At any rate, these heady times have come to a close, any script tags are stripped out as of 2.1. There is a new method for running JavaScript in receipts, but it's well hidden since there was no documentation when this hit me and the setting required to enable custom scripts didn't even exist by default. There's a little work to do, so let's leave the past behind and get back to the future.

It is possible that the setting oversight has been corrected by the time you read this; to check, log in to the Evergreen client, click the Admin menu, Server Administration, and Organization Unit Setting Types. Click next a dozen or so times, until you reach the types beginning with 'p'. If there is a setting type with the name of print.custom_js_file, remember its name and rejoice, the hard part is finished. If not, create one with that type, give it a name you can remember and give it a description (the other options aren't required). To actually set the option, go to the Admin menu, Local Administration, Library Settings Editor. Edit the setting with the name matching the print.custom_js_file type, and set it to a URL you control. http://example.com/receipt/custom.js or something similar would be great. Keep the location in mind because this is where you'll be putting your javascript file with all of your custom code. Now, to the heart of the matter.

What is the point of this? Instead of inline JavaScript, you get 1 file in which to work your magic, its URL stored in the above setting, and one function in it that will be called: print_custom(type). This means that whatever you're going to do has to be based on element ids, DOM inspection, or CSS class names.

I had a few requirements with regard to the effects I wanted to achieve. As of 2.1, receipt replacements still aren't global, so if you have two %PATRON_FIRSTNAME% replacements, only one of them is replaced with a name. Not great. So I needed a way to signal that one value should be copied to another location. And because a value that is repeated may need additional processing, the method used needed to allow multiple effects to be specified. Adding the fact that you can't easily use ids in the line item section (you could append %LINE_NO% to an id if you must, but only to one of them!), the simplest method then is using CSS classes. Because you can't tell the difference between placeholder and template text, each replacement that requires any modification is best wrapped directly in a tag. That's why there are so many of those spans running around, any effect or transformation requires a tag directly around its target.

So, here are the CSS classes that trigger the transforms and modifications that I use to bend receipts to my will. A copy of this custom_format.js will be available in another post; use them as they are, or bend your receipts a different way.

This doesn't actually do anything, it's only a signal. All of the elements that need further processing are grabbed and then tested for the remaining classes.

src-(NAME) and dest-(NAME)
Classes that begin with src- have their contents copied into a dictionary keyed with the rest of the class name. Classes beginning with dest- signal that the dictionary should be checked for a key that matches the rest of it's name, and if a value exists, it's put into that tag. Fortunately, these tags are only temporary, because multiple receipt replacement is supposed to be fixed in Evergreen 2.2. I can't wait to get rid of them; they're irritating and incapable of handling certain situations. (not so easy to use in a URL, for instance.)

<span class="rcpt src-author">Petroski, Henry.</span><br/><span class="rcpt dest-author"></span>Petroski, Henry. Petroski, Henry.

The default representation of a circulation modifier is code : name : description, which can range from book : book : book to  book : Book : A monograph item. No, sir.

<span class="rcpt mod-CircModToCode">book : Book : monograph</span>book

Sometimes you don't want the extra punctuation that AACR2 or ISBD demand. (Some might argue that you never want it in this day and age, but that's for another time.) Extra hanging spaces are particularly maddening if you're adding your own punctuation, though, so this strips them out.

<span class="rcpt xf-Trim">To Engineer Is Human </span>;To Engineer Is Human;

Bring patron information into the Title Cased Future, with only a minor chance of mangling their names. Since we only use first names on our receipts, I could avoid the whole "What to do about Mc and O'?" question entirely.

<span class="rcpt xf-TitleCase">SUZIE</span>Suzie

I don't believe I've ever bragged about my skill at picking names… Anyway, when was the last time you told someone that your favorite author was King, Stephen? Never? Then it shouldn't be printed that way either. This transform also removes any silly vestigial punctuation used for printing catalog cards. ("Stephen. King," isn't any great improvement.)

<span class="rcpt xf-LastFirstToFirstLast">King, Stephen.</span>Stephen King

This is just how we get by using 1 set of templates for multiple locations and different phone numbers. It obviously requires customization before it will help anyone else.

<span class="rcpt xf-ShortNameToPhone">YRLIB</span>867-5309

This will take a date of the form YYYY-MM-DD (etc.) and change it to "DayName, MonthAbbrv Date, Year" form, dropping any time component.

<span class="rcpt xf-DateToLongDate">2012-02-29 11:59:59 PM</span>Wednesday, Feb 29, 2012

Here's one that takes a little explanation. Our receipts print "Title, circ mod by Author" but if the circ modifier or author is blank, it turns ugly. So, the best way to fix that is to remove any unnecessary punctuation and spacing. Because you can't really use ids in line items, that means the simplest thing to do is to make use of relative DOM nodes, so this one requires 2 span tags, one that includes the punctuation and still within that, the one that contains the placeholder.

Title<span>, by<span class="rcpt mod-EmptyHideParent"></span></span>Title

So that's what is required to put together the updated checkout receipt I've shown, but there is one more receipt that sees a lot of use inside the library, and I think improving it makes a major difference behind the checkout desk. It's coming up next.

February 21, 2012

Receipt Editing in Evergreen 1

I've worked at a library for over 10 years. For most of that time, the receipts we've given people that check out our items have essentially been plain text, dot-matrix printouts of barely more than a title and date. In late 2008 we joined a consortium running the Evergreen Integrated Library System. Suddenly everything was different! This was better, that was worse, no one knew what this thing was, and those features weren't even there yet. The receipts, though, were very similar.

Something about them is very different though. Now there is an option to change the templates for the receipts and mold them into whatever shape or style you might want. It doesn't require using any bizarre forms processing language or choosing from one or two equally bad layouts in an options file, these templates are made of regular HTML with a few placeholders for the patron or item specific information.

Think about the other items given to your patrons as they walk out the door. Your program fliers probably aren't just a short paragraph typed up in Word's default font are they? Is your website a single page with dark Times New Roman on a light background? I thought not. (I hope not.)

Update 4/17/2012: I didn't see it until today, but Aaron Schmidt wrote a great article for the User Experience blog on LibraryJournal's site, explaining more about the reasons you might care about improving the looks and information usability of your receipts. He does a much better job of explaining the why; after you've read his article (go on, it's a short post) come back here for some how.

So, what is the default, anyway?

Welcome to Your Library Branch!
You checked out the following items:

  1. Reading: the bookening
    Barcode: 31234000000014 Due: 2012-01-21 4:52 PM
  2. Watching: the movening
    Barcode: 31234000000023 Due: 2012-01-14 4:53 PM

YRLIB 2012-01-07 16:53
You were helped by JASON

The basic information is here; the book is due back in 2 weeks, the movie in 1, and the barcode is included in case you have cause to need it. You can parse out what you need, but aside from the subtitles you wouldn't know one is a book and the other a movie. The dates are also absolutely tape-on-the-glasses nerdstyles; I mean, I love me some ISO 8601 (this approximation, less so), but I don't know anyone that uses it for non-computer things. You can also see from the last line that we still enter all of our user information IN ALL CAPS. HELLO FROM 1985. (Don't tell me about postal this or that, I don't care.)

At JCPL, anything handed to a patron or frequently used by staff is based on the following layout.

LOGO!Jackson County
Public Library
Your Library Branch

Suzie checked out:
  1. Reading: the bookening, book by Author McWriter
    Due: Saturday, Jan 21
    Barcode: 31234000000014
  2. Watching: the movening, dvd
    Due: Saturday, Jan 14
    Barcode: 31234000000023
Call us at (555) 876-5309
Visit us online at http://Example.com/

You were helped by Jason

YRLIB 2012-01-14 16:53

Plenty of changes here, if you look closely at the second item there's obviously some kind of textomancy happening, the dates are also written in an easier to read manner, and there's almost nothing left that's in all caps (no database changes, for better or worse). There's also local library branding and the patron's first name. That adds a nice little touch of personalization and will really help those families where each child wants to check out their own items. To try to preserve my sanity, the branch name and phone number are workstation aware, so one set of templates is used at all of our locations without edits. Neat.

Since Evergreen receipt templates are just HMTL, that's all you really need to know to make changes, but adding CSS is an easy way to up the attractiveness. To try to stay below LD50 levels of dull, I'll assume that everyone has a passing familiarity with both and I'll largely ignore that. You can make your receipts look however you want, or you can just borrow from my example. It's the Javascript that I'll get to later that will really make it shake.

So, here's the template for that default receipt:

Welcome to %LIBRARY%!<br />
You checked out the following items:<br />
<hr />

----Line Item----
<li>%title%<br />
Barcode: %barcode% Due: %due_date%

<hr />
You were helped by %STAFF_FIRSTNAME%

Templates have header, line item, and footer sections. The line item section is repeated for each item checked out, renewed, etc. The text between percent signs are the library/patron/item text placeholders. Generally speaking the upper case placeholders work anywhere and the lower case only work in the line item. The good news is that there are many more than the ones we see here; to see them all, there's a Macros button in the template editor. Keep in mind that each receipt type (checkout, checkin, holds, etc.) has a different list, so check it out.

So I upgraded the look of our checkout template, what does it look like now?

<style type="text/css">
  body { font-family: Verdana, Arial, sans-serif; font-size: 10pt; margin: 0px; }
  .smaller { font-size: 90%; }
  #footerdata { font-size: 80% }
  #bbox { border: 2px solid black; border-right: 0px; border-left: 0px; margin: 4px 0px 4px 0px; padding: 4px 0px 4px 0px;}
  #list { margin: 0in 0in 0in -.125in; }
<table style="margin:auto;">
<tr><td rowspan="2"><img style="width: 64px; height: 64px; border: 0;" src="http://example.com/receipts/Logo.gif" /></td><td style="font-size: 16pt;">Jackson County</td></tr>
<tr><td style="font-size: 16pt;">Public Library</td></tr>
<div style="text-align: center;">%LIBRARY%</div>
<br />
<span class="rcpt xf-TitleCase">%PATRON_FIRSTNAME%</span> checked out:
<div id="bbox">
<ol id="list">

----Line Item----
<li style="padding-bottom:2px;">
<span style="font-weight: bold;" class="rcpt xf-Trim">%title%</span><span>, <span class="rcpt mod-EmptyHideParent mod-CircModToCode">%circ_modifier%</span></span><span> by <span class="rcpt mod-EmptyHideParent xf-LastFirstToFirstLast">%author%</span></span><br />
<span class="smaller">
Due: <span style="font-weight: bold;" class="rcpt xf-DateToLongDate">%due_date%</span><br />
Barcode: %barcode%

<div style="text-align:center;" class="smaller">Call us at (555) <span class="rcpt src-ShortName xf-ShortNameToPhone">%SHORTNAME%</span><br />
Visit us online at http://Example.com/</div>
<br />
<span id="footerdata">
You were helped by <span class="rcpt xf-TitleCase">%STAFF_FIRSTNAME%</span><br/>
<br />
<span class="rcpt dest-ShortName"></span> %TODAY_TRIM%<br/>

Witchcraft! What are all of these spans doing up in here? And whither these false CSS classes? The answers require a little backstory

February 15, 2012

Who? What?

Everyone has opinions, these are mine. Opinions on libraries, software, whisk(e)y, those weird little ridges on the F and J keys, damn near anything. Feel free to enjoy them, or don't; I'm told it's a big internet.