Advanced Receipt/Printing Features in Evergreen 2.2+

I had plans to post all kinds of things here, but it appears that only Evergreen software changes have been motivating enough to make me mash words together. Maybe someday I'll say something about OpenStreetMap, which is incredibly neat, but usually if I think about it at all I just end up nudging things around town because it has (had) some glaring errors and missing streets.

Today, however, it's going to be some of the weird and wonderful ways you can bend Evergreen 2.2+'s printing system to your twisted will. There are 3 big user-facing features that people need to at least be aware of, in increasing levels of import: the new %INCLUDE()% macro, new receipt templates, and user-selectable contexts for receipt templates.

Here they are again, in decreasing order of import:


User-Selectable Contexts for Receipt Templates
So you've mastered printer context setup, eh? One machine can print to your desktop, receipt, and label printers effortlessly? Well it could, now you may have some work to do.

Well, hello there.

You can see from the screenshot that I've selected receipt for the (obviously?) receipt-oriented Checkout template. Selected? Receipt wasn't the default? No! This option is initially blank, so after upgrading Evergreen to 2.2 or later, libraries may have receipts printing who-knows-where. Not ideal. In a panic to get things working as expected, perhaps you changed the default printer context to use your receipt printer, but by modifying the receipt templates directly you can correct this and receipts can use the receipt context as expected.

It occurs to me that after writing 100+ words about printer contexts that I've never actually written about them here, and don't currently know where to point anyone for more information about how to best make use of them. Rather than stretch this out with a lot of explanation, I'll just say that if things were working on Evergreen 2.1 or below and now that you've upgraded to 2.2 or above and people are freaking out about printers, just select each template, choose Receipt from the "Force Printer Context" drop down, click Save Locally, lather, rinse, repeat. You'll be much happier when you're finished.

With that said, being able to select a specific printer context for each receipt template really helps when paired with new receipt templates.


New Receipt Templates
In Evergreen 2.2 there are some receipt templates that are brand new: "holds_on_bib," "holds_for_patron," "holds_shelf," and "holds_pull_list" are some. There are others, but the only one that I know for certain is big-time fun is holds_pull_list. Much like it says on the tin, it's printed whenever you print a holds pull list for staff to pull items off the shelves to fill holds. Until Evergreen 2.2 it's been difficult to customize the layout of pull lists, but with this receipt template, and the previously mentioned context selector, you should be able to design exactly the pull list your staff wants, be it for 3 inch printers or 8.5 x 11 inch printers. There are still 3 print buttons on the pull list page (sigh); just plain "Print" uses this template.


Using %INCLUDE()% in Receipt Templates
Oh, man. Personally, this might be the most important printing-related change in Evergreen 2.2, but I'm trying to be realistic with regard to other people's expectations here. What this is is another difficult-to-discover text replacement placeholder, but it's one that takes arguments. If you don't know anything about programming or functions or whatever, don't worry, I just mean you can put different words between the parenthesis and get different results out of it. This is accomplished with Library Settings. For those unfamiliar, Library Settings are specified on the server and downloaded each time the client is logged in. To add one more (welcome) level of complexity, library settings can be defined at various (and multiple!) levels in your organizational unit hierarchy. I'll touch on that some more in a little bit.

There are 5 different text replacements defined by default for use with %INCLUDE()%: alert_text, notice_text,  event_text, header_text, and footer_text. Their names are just that: names; you could use notice_text for all of your headers and footer_text for all of your events, but don't; that would be terrible.

As an example, to use header_text, I replaced most (not all!) of the text in many of my receipt template header section with this: %INCLUDE(header_text)%. What that means is "Find the value of the header_text library setting, and put it here instead." So my header_text value is set to all of the HTML and CSS code that was common to all of the patron-facing receipts that we use. To do that, go to the Admin Menu, Local Administration, and then Library Settings Editor. To make it (much!) easier to find what you're looking for, type receipt into the text box at the top of the list, and click Filter. You should be left with a list of only 6 or 7 items that all include "receipt" somewhere in the name or description. The settings are named "Content of X include" where X is one of the 5 names above. A word of warning: Settings aren't allowed to have multiple lines, so you have to edit your HTML/CSS into one long line before pasting it into your setting. That's painful, but not a show-stopper.

I wouldn't recommend putting everything in your header section into header_text, because no matter what template you are editing, %INCLUDE(header_text)% will always return the same thing, so it would't be good to have the word "checkout" in it, for instance. The best thing to put in the header_text option is only what is common to every receipt that you want to have the same header. (Staff-only receipts probably don't need the same fancy header that the public gets, for instance.)

Maybe this makes more sense with an example.

I've made some changes since I last mentioned my library's receipts, so things will look a little different if you've read that series.

Here's what the new checkout receipts look like:

	Jackson County
	Public Library

Your Library Branch
876-5309 http://MyJCLibrary.org/

Jason checked out:

1. Pizza: award winning pies for the home kitchen, book by Pete Evans
   Due: Wednesday, Oct 31
   Barcode: 31234000000014

You saved $15.95 by using the library!

MyJCLibrary @MyJCLibrary

You were helped by Anne
YRLIB 2012-10-10 14:25

There's a fair bit of HTML behind that, but because of %INCLUDE()%, the receipt template itself has actually gotten shorter:

----Header----

%INCLUDE(header_text)%
<center id="alertinfo"><br/><b class="rcpt mod-EmptyHideParent">%INCLUDE(alert_text)%</b><br/></center>
<center id="noticeinfo"><br/><b class="rcpt mod-EmptyHideParent">%INCLUDE(notice_text)%</b><br/></center>
<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%
</span><span style="display: none;" class="rcpt add-price">%price%</span>
</li>


----Footer----

</ol>
</div>
<br/>
<span>You saved $<span class="rcpt total-price-2 mod-HideEmptyParent"></span> by using the library!</span>
<center id="eventinfo"><br/><span class="rcpt mod-EmptyHideParent">%INCLUDE(event_text)%</span><br/></center>

%INCLUDE(footer_text)%

You can also see that I've also stashed the alert_text, notice_text, and event_text includes in there just in case I have a good use for them later, such as putting upcoming events in a little table at the bottom of the receipts…

Then to complete the receipts, I have to just go to the Library Settings Editor, find the "Content of header_text include" and "Content of footer_text include" options and set them like so:

----Content of header_text include----
<style type="text/css"> body { font-family: Verdana, Arial, sans-serif; font-size: 10pt; margin: 0px; } .smaller { font-size: 85%; } #alertinfo { font-size: 85%; } #noticeinfo { font-size: 65%; } #eventinfo { font-size: 65%; } #eventinfo table { font-size: inherit; } #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; } </style><center><table><tr><td rowspan="2"><img style="width: 64px; height: 57px; border: 0;" src="http://www.myjclibrary.org/receipts/EvergreenLogo.gif" /></td><td style="font-size: 16pt;">Jackson County</td></tr><tr><td style="font-size: 16pt;">Public Library</td></tr></table>%LIBRARY%<br/><span style="font-size: 90%;"><img style="width: 8px; height: 11px; border: 0;" src="http://www.myjclibrary.org/receipts/handset.png" /><span class="rcpt xf-ShortNameToPhone">%SHORTNAME%</span> <img style="width: 10px; height: 10px; border: 0;" src="http://www.myjclibrary.org/receipts/pointer.png" />http://MyJCLibrary.org/</span></center>

----Content of footer_text include----
<center><img style="width: 12px; height: 12px; border: 0;" src="http://www.myjclibrary.org/receipts/facebook.png" />MyJCLibrary <img style="width: 12px; height: 12px; border: 0;" src="http://www.myjclibrary.org/receipts/twitter.png" />@MyJCLibrary</center><br/><span id="footerdata">You were helped by <span class="rcpt xf-TitleCase">%STAFF_FIRSTNAME%</span><br/><br />%SHORTNAME% %TODAY_TRIM%<br/></span>

Keeping in mind, of course, that both of those have to be entered as single lines. Eugh. Changes don't take effect until the next time staff clients log in. So if changes are made to includes late in the day, the next morning when staff log in everything will be updated.

An aside for multi-branch libraries, or tiny consortia: Library settings are assigned to org units, and if the particular org unit your workstation is at doesn't have a setting defined, in most cases it will then see if the parent org unit defines that setting, and so on, until it hits the top level of the org unit tree and gives up. This means that things like headers and footers can be set for whole systems or the entire consortium by defining them "high enough" in the org tree. Things like events, notices, and alerts can then be defined as generally or as specifically as needed.

Finally, if you are in a position where you manage your own server, it's possible to add additional include types. To do that, go to the Admin menu -> Server Settings -> Organization Unit Setting Types. Then click New Org Setting Type and fill in the fields like so:

name	circ.staff_client.NEW_INCLUDE_NAME
label	Content of NEW_INCLUDE_NAME include
datatype	String
description	Text/HTML/Macros to be inserted into receipt templates in place of %INCLUDE(NEW_INCLUDE_NAME)%
grp	receipt_template

Instead of NEW_INCLUDE_NAME just enter whatever the new include should be: item_detail, library_branding, whatever your receipts demand. The name field is important; everything up to the NEW_INCLUDE_NAME must be exactly that, but the label and description can be whatever you like, these are just what the other settings look like.


Hopefully there is something here that is useful to someone, there are too many ways to customize the printed output of an Evergreen Library System for me to even mention them all. If you want to do something and don't know if it's possible, poke around; you might stumble on something good.

Losing to Win

So how about that Olympic Badminton scandal, eh? Not having ever played in a tournament where it's advantageous to lose, the whole thing made no sense to me when I first heard about it.

Luckily someone out there (game designer David Sirlin) explains how this goes down.

It's an embarrassing time for Olympic badminton. But not because some players lost on purpose—because someone created horrificly bad tournament rules and then tried to blame the competitors for playing to win.

I also thought the explanations of kingmakers and lame-ducks was particularly interesting.

The 4 Flavors of iPhone Backup

There are four different methods to back up (or not) your iOS device, let's take a look at what each flavor of backup does. Android users may have more/fewer options; I don't know, but I really encourage you to find out, or if someone wants to give me an Android device I can look into those options as I have time. (I hear the Nexus 7 is nice, and it fits nicely into my Android buying guide)

Rocky Road
In ye olden days of cell phones, if you broke your device everything was gone and you were sad. If you had a GSM phone with a SIM card, perhaps some or all of your address book could be stored there if you 1, knew about the option and 2, bothered to do it (not just once!). Not backing up your iPhone at all is a callback to these heady days where every trip to the restroom or walk under cloudy skies was skirting danger. Except that losing everything will drive you up the damn wall because you put months or years worth of data, logins, media, etc. into that phone because they're computers now, and now all of that is gone. The only consolation is that you won't have to re-purchase your apps or media, but that is a cold comfort when composing your second or third "I lost my phone, please send me your #" status update on Facebook.

Vanilla
If you sync your iPhone to your Mac or PC iTunes can backup your device as part of the process. Since iOS 5 you can also sync wirelessly, so you don't even have to take it out of your pocket if you don't want. When your device is connected, click on it in iTunes' Devices section. On the Summary tab, make sure "Back up to this computer" is selected. Just remember to sync now and then (it's a fine way to charge, you know) and you're set.
There is a caveat though: by default the "Keychain" (where your email account, website, and most app passwords are stored) cannot be restored to a new device. This means that if you drop your phone into a bucket of water, when you bring home your new phone, all of the media, apps, etc. will be put back just as they were, but you will have to re-enter every password. To enable restoration of your Keychain, you need to select the "Encrypt local backup" option and supply a password. Don't forget your password, or you'll lose the entire backup rather than just your Keychain.

French Vanilla
Since iOS 5 was released, it is becoming less and less necessary to ever connect an iOS device to a computer to manage it, including backup. Once a day your device is just backed up to Apple's iCloud servers automatically (though you can also trigger backups on demand). There are some rules though, the device has to be: 1. plugged in and charging, 2. locked, and 3. connected to a wireless network (3G will not do, as it would rapidly wreck your data limit). This can be turned on either by connecting the device to a computer and selecting the option in iTunes, or by going into the iCloud option in the Settings app.
You can tailor what is and isn't backed up to iCloud in the Settings app, and you'll likely want to keep an eye on that because you only have 5GB of space unless you purchase some. If you take a lot of photos, that will disappear faster than you think, though only using PhotoStream and not backing up your photos will (almost!) be as good. It is also important to note though that the list of items backed up to iCloud is much smaller than the list of items backed up by iTunes, and there is no way to restore a Keychain to a new device. Bear in mind that if you do have convenient access to a laptop or desktop that may be a better option. Or perhaps…

Cookie Dough
You can have your Keychain and eat it too, something like that anyway. Selecting the iCloud backup option disables automatic iTunes backups, but it doesn't stop you from doing them yourself. All you have to do is plug in your device each night to automatically backup to iCloud, and then when you want to do a full backup, connect the device to your computer, let it sync, and then right-click on it in iTunes' Devices section. There will be a Back Up option that you can choose to do a regular iTunes backup, even if you have iCloud backups enabled. It's only really necessary to backup to iTunes after telling a new app to remember your password, or changing an existing password in an app. Should disaster strike, iTunes can give you back your most recent full backup and your Keychain, and iCloud can fill in the gaps.


I wrote this for two reasons: 1, Everybody should be backing up their computers, and modern smartphones are just as much computers as the ones on your desk or lap; and 2, I have had occasion to test this recently. I frequently hook my iPhone up to my Mac, so I just use the iTunes backup (it's inconvenient for me to charge it overnight) and that's fine. This is also the fastest and easiest way to get new episodes of podcasts on the phone until the Podcasts app works properly.
A few weeks ago though, I was going to be in northern Indianapolis and for some time I'd had some trouble with my Home button working properly (that's kind of a big deal on an iPhone). I just thought I'd go see if the Apple Store had any ideas or a way to clean it, but about a minute after explaining my problem a newly refurbished phone was staring me in the face. I wasn't expecting to replace my phone that day, but I had backed my phone up the night before and that home button was really bugging me. Shortly after getting home I hooked up the new phone and restored my latest backup to it. Short of setting up the notification options for a few apps (push notifications are weird for boring and off-topic reasons), it was as if my phone never had a problem. It was easy and I didn't have to ask for phone numbers on Facebook with my hat in my hands.

So, if you own an iPhone (or iPod Touch, iPad, etc.) check on your backup settings, you don't want to be learning about this stuff after your device is busted. For Android users I'm sure there's something similar, just look around, but be wary of anything that comes from the device manufacturer; the backup that Samsung software makes probably won't help you if you move to an HTC device later.

Lipstick on a Podcasts.app

Since Apple's World Wide Developer's Conference in early June, word has spread that iOS 6 will remove the Podcasts tab from the Music app, and in preparation, Apple has released a new app called Podcasts into the app store.

It's pretty. I'm pretty pissed off at it.

First things first, it has some reaslly nice features, you can: subscribe to podcasts using the built-in Catalog or radio-inspired "Channels" section; set varying subscription/auto-download settings per podcast; and most importantly, receive new episodes over the air automatically.

But.

There are some serious issues that honestly make me wonder if this wasn't an assignment given to an intern as a trial by fire; if that is the case, they have been burned.

There are … pauses
As soon as the app starts it shows you the Library and then … you wait. It's probably checking you Music app for un-synced podcasts or something over the network, but it's certainly not in any hurry to let you do things like scroll around, tap a podcast, or anything else. Occasionally it will just stop responding for seemingly no reason. It's like your brand new iPhone has changed into a 3+ year old HTC Frond.

Car integration is completey busted
What's a great place to listen to podcasts? In your car! Cars with "iPod integration" have a USB port (or more rarely, a dangling Apple 30-pin connector somewhere) that you can connect your iPod or iPhone to, and then use the car's play/pause, next and previous buttons to control playback. It's awesome, and in Apple's new Podcasts app, it only works for about 3-5 seconds, just about long enough for you to get on the road. Wretched. (I know it's busted for the 2010 Prius. Maybe another car works better? I can't really afford to test that.)

There is no indication of new episodes
The default view of your library is lists of podcast's album art in a scrollable list. Do new episodes show up as a badge, or is there maybe just a blue dot like in Mail.app? No! You get to poke around randomly and be dissapointed until you happen across one, or just give up and switch to the table view. The table view is also the only place to find a "playlist" of all unplayed episodes.

Episodes won't download over 3G if they're larger than 50 MB
This is greatly improved over the old limit of 10MB, but it's still stupid. If you stream the episode instead of downloading it, the whole thing still plays! Stop making me play games and download the damn thing.

As released this app is awful, but maybe they can throw a few more developer hours at it before iOS 6 and the new iPhone come out in October. If not, I guess I'll have to start sizing up the third party options. This is hugely annoying because I don't need any fancy features, if this app simply worked properly I'd be perfectly happy.

Get Your Classics On

A neat find from John D. Cooks' blog, The Endeavor: the organ works of JS Bach available from James Kibbie, and the Open Goldberg Variations from Kimiko Ishizaka. Free to download in a variety of formats.

What your smartphone's default email signature says about what manufacturers think of you

I would like to think that this is a fake, a joke, someone having a lark. But in the end I know it probably isn't. It got me thinking, though, about these things. I turned off the "Sent from my iPhone" signature on my phone because I have no interest in attaching tiny ads to my emails, but if you compare the two they send rather different messages; let's explore.

Sent from my iPhone
This is technically an ad, yes, but it also sounds somewhat personal. I sent this email to you from my iPhone; implied is a mea culpa for any typos in the message. Perhaps I was walking down the hall, at lunch, whatever I do when I reply to email away from my desk. Taken this way you could almost believe (though not quite) that I actually chose this as an email signature just to convey that message. At the very least, marketing or not, it's short.

Sent via the Samsung Galaxy S™ II Skyrocket™, an AT&T 4G LTE smartphone.
There is nothing technical about this; my default email signature is a blatant advertisement for both my phone and carrier, one of which likely exchanged large sums of money to be included in my every message in the hopes that my not caring or knowing how to change it will hopefully influence you into believing that one and/or the other of these companies offers a product/service worth a damn. I am unlikely to tell you face to face that I ever send anything via anything else. Neither am I likely to remember all 5 segments of my smartphone's full name if ever quizzed about it. Please, the next time we meet in person, tell me what the Menu button in Android does so I might be able to change this. I am more than happy to stand there and let a sales person tell me that Android 2.3.5 is "state-of-the-art" and neither crack a smile nor roll my eyes. I promise you I don't know how to type ™ on this keyboard. I wish I didn't sign a two-year contract for this. Finally, if there are typos I'm sorry, I sent this from my phone because I decided it couldn't wait until I got back to my desk.

I'll briefly drop the same advice here that I give to anyone that asks me in person:
So you want a smartphone? If you ever plan to ask me a question about it, you should get an iPhone. If you're going to ignore that sage wisdom, then the only Android phone worth owning at any time is whichever one has "Nexus" in the name this year. No, I don't know if you can get one at the Verizon/AT&T Store.

Does this mean I think you, gentle reader, have made a terrible error in buying whatever non-Nexus Android phone you might have? Not if you're a tech geek and knew full well ahead of time what you were getting into and decided "I really want this phone even though it will never be improved beyond its current state," or you plan to put CyanogenMod on it yourself. Have a good time with all of that (but don't ask me what's happening when it goes walkabout on you).

Evergreen Receipts Followup

This post is followup to a series.

At some point some of the modifications I wanted to preform on receipts were added as built-in text macros. The benefit of this is that if for some unfortunate reason you have to use text only receipts you can still modify them as you see fit - JavaScript customization only works in the "Mozilla" (browser) print mode. Thomas Berezansky was kind enough to mention them to me (over a month ago now, because I am terrible at following up on personal projects) and you can read how the built in date formatting, whitespace trimming, and substrings work at http://bstcon.com/receipts.txt . The last line - "Doesn't even cover the default set of features that exist without a custom JS file defined in Mozilla print mode. ;)" - is more than a reminder that there is a lot of flexibility available "for free" in the receipt editor; it's also a reminder that nothing is documented except for the placeholders. Currently you can learn what's available by looking through the source code for that part of the Evergreen client or you can do your own thing, possibly duplicating existing functionality (though perhaps with nicer syntax).

He also pointed out an available placeholder that I didn't notice: %shelf_expire_time%. This uses a library setting that you can configure in the client to determine your available hold expiration dates automatically. This is better than adding the date manually, and was either added sometime after I originally changed our receipts in 2008 or I just didn't know about it since I hadn't looked through most of the library settings at the time. Perhaps someone will find another use for mod-DateAdd, but it's not necessary for hold expiration dates.