February 28, 2012

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.

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.

mod-DateAdd-N(-d|w)
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.

Template

Becomes

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

2012-02-29

xf-SubStr-N1(-N2)
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.

Template

Becomes

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

Text

xf-DateToMonthDate
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.

Template

Becomes

<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.

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.

rcpt
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.)

mod-CircModToCode
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.

Template

Becomes

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

book

xf-Trim
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.

Template

Becomes

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

To Engineer Is Human;

xf-TitleCase
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.

Template

Becomes

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

Suzie

xf-LastFirstToFirstLast
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.)

Template

Becomes

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

Stephen King

xf-ShortNameToPhone
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.

Template

Becomes

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

867-5309

xf-DateToLongDate
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.

Template

Becomes

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

Wednesday, Feb 29, 2012

mod-EmptyHideParent
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.

Template

Becomes

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

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.

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.

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:

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

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?

February 15, 2012

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.