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.