Koha Blog

I’ve made some changes to the links in the “Blogroll” over in the right column. I’ve taken out Koha.org and added an important new one: Koha-Community.org.

A little history

Koha.org has been around since the creation of Koha. It was initially owned and managed by Katipo Communications, the company which developed Koha 1.0 for the Horowhenua Library Trust. When Katipo’s Koha assets were acquired by LibLime, possession and control of the domain passed into LibLime’s hands. LibLime oversaw significant improvements to the site and appeared to have good intentions to improve access to authors from around the community.

Complaints

However, in recent months LibLime’s interest in conscientious stewardship of the site seems to have waned. Information on the site is, little by little, becoming out of date. The home page lists Koha 3.0.4 as the latest stable release, when Koha 3.0.5 was released two months ago now. It’s even worse on the “Download” page, which lists Koha 3.0.2 from June 4 2009 as the latest stable release. This kind of misinformation is irresponsible.

Besides providing information about Koha software, the site also provides users with information about commercial options for Koha support and hosting through its “Pay for Support” page. For months new companies offering Koha hosting and support have waited for their information to appear on the site. The submission form companies are asked to use is broken.

Remedies

The Koha community has attempted to communicate with LibLime about the situation without success. The Koha community has nominated the Horowhenua Library Trust to act as an independent steward of Koha-related assets like the Koha.org and the Koha trademark. We have proposed to LibLime that, given their lack of care and interest in Koha.org, transfer the domain and its management to HLT and let the Koha community take back control. LibLime has not responded to these requests.

The community was left with no choice:  we had to create a new home for the Koha project. We can no longer depend on the good will of LibLime. Koha-community.org came together quickly and beautifully thanks to all involved. Thanks are owed especially to Liz at the Northeast Kansas Library System for all her hard work.

If you want to share a link to the real open source Koha, please use http://koha-community.org

My library has a long and complicated history of how to deal with overdue notifications. We’ve tried a few different forms of printed notices, and at one time we even tried to telephone each patron with overdues. After we switched to Koha we got a new option: sending overdue notices via email. Koha didn’t have a built-in notification system at the time, but the open nature of the application meant we could create our own scripted process to query the Koha database and get the information we needed.

The script, written by our director at the time, Stephen Hedges, queried the Koha database for patrons with overdues and did a few things at once with the results of this query:

1. Send overdue notices via email.
2. Create a file of overdues data for patrons without email.
3. Restrict (“debar”) patrons with items overdue for more than 30 days.

In Koha 3, some of this work can be taken over by new built-in notification functionality. With the Overdue notice/status triggers feature we can define when overdue notices should be sent to patrons and when patrons should be restricted for their overdues (taking care of #3 above).

The drawback to Koha 3’s Notices feature is that it doesn’t give you much help when it comes to printed overdue notices. Koha will send an email notice to any patron who has an email address in their patron record (taking care of  #1 above). For patrons without email, Koha collects all of their overdue notices into a single email which is sent to the Koha administrator. Presumably the idea is that the messages can be printed out and mailed by hand.

Unfortunately this won’t work for us: We don’t want to send letters. It’s too much manual labor to stuff envelopes and stick stamps.  We want to send post cards. They’re cheaper. Of course for privacy reasons (not to mention space constraints) we can’t print out a list of a patron’s overdue items on a postcard. We want to send them a generic reminder which includes our web address (for online renewals) and phone numbers to our branches. So even with improvements in Koha 3 we need to do some work to take care of #2 from the list of tasks performed by the old overdues script.

Let’s take a look at how the old script worked. It began by performing this query:

SELECT issues.borrowernumber, firstname, surname, streetaddress, physstreet, city, zipcode, emailaddress
FROM issues, borrowers
WHERE returndate IS NULL
AND TO_DAYS( NOW( ) ) - TO_DAYS( date_due )
BETWEEN 8 AND 30
AND issues.borrowernumber = borrowers.borrowernumber
AND gonenoaddress < 1
AND borrowers.categorycode != 'HB' ORDER BY issues.borrowernumber

It limited the query to items which were between 8 and 30 days overdue, where the “gonenoaddress” flag was unset (less than one, meaning in this case zero), and where the patron didn’t have the ‘HB’ categorycode (our “homebound” category for home-delivery patrons).

As far as printed notices are concerned, the purpose of the old script was to create a CSV file containing the name and address of each patron with overdues.  Since we’re going to send a non-personalized postcard to each patron, we don’t want the output to include any other personal details. Here’s what the results looked like:

In updating this for Koha 3 we can make that query a little bit more portable by having it check whether the patron in question has a category that requires overdue notices:

SELECT issues.borrowernumber, borrowers.firstname, borrowers.surname, borrowers.address, borrowers.address2, borrowers.city, borrowers.zipcode
FROM issues, borrowers, categories
WHERE issues.returndate IS NULL
AND TO_DAYS( NOW( ) ) - TO_DAYS( issues.date_due )
BETWEEN 8 AND 30
AND issues.borrowernumber = borrowers.borrowernumber
AND borrowers.gonenoaddress < 1
AND borrowers.categorycode = categories.categorycode AND categories.overduenoticerequired = 1
AND borrowers.email IS NOT NULL
AND borrowers.email != ''
ORDER BY borrowers.surname,borrowers.firstname

I’ve added a check that categories.overduenoticerequired is 1, which eliminates the need to hard-code the ‘HB’ patron category. I’ve also added a check to make sure the patron email address field isn’t empty (the old script performed that check elsewhere).

Since I’m more comfortable in PHP than Perl, I use a PHP script to query MySQL and format the results to be saved as a CSV file just like the old script did.

Taking it to the Post Office

We’ve successfully pulled the data we need. What next? We use an online service called Click2Mail, a “trusted and accredited partner to the United States Postal Service.” Click2Mail allows us to define a custom postcard template with our own personalized message. We can then upload our CSV file containing the name and address information for each patron with overdues. The service parses that CSV file, prints one postcard for each patron, and delivers it to the USPS for delivery. Click2Mail even checks your mailing addresses for possible errors and lets you review them.

Their cost estimator puts the cost of sending 100 single-sided postcards at about $30. Considering the time, effort, and cost of stuffing and stamping 100 letters, Click2Mail seems to be a great value.

One of the promises of using Koha or any other Open Source ILS is that you’re not tied any one support company. “No vendor lock-in.” But it’s important to understand that this isn’t a promise that libraries can take for granted–in particular, libraries who contract with a support company for hosting of their Koha system. We need to be aware of what that means in practical terms and be prepared to put that promise to the test when the time comes. There are steps that we can take to make sure we’re protecting our own interests.

Insist on access to your database

We as libraries should own our data. That means the database of our patrons, the items in our collection, our authority records, etc. Everything stored by the ILS should belong to us. After all, we put it there. When we contract with another company to host our Koha system, we’re giving them the keys to the vault. We have to put our trust in them, but we can also protect ourselves.

It’s simple: our data is in the database. If we want to retain ownership of that data we need to have access to that database. In my opinion this should be part of any Koha hosting agreement. If you have read access to your database you can run your own queries and leverage your data in ways that Koha may not do out of the box.  Does Koha not include the kind of report you need? Hire a programmer to write a script to pull the data and manipulate it however you want. It doesn’t even matter what kind of scripting language you want to use: Perl, PHP, Ruby–anything that can connect to your database will work.

If you want to be prepared for disaster I also suggest you ask for access to regular database dumps, or ask for privileges to do the data dumps yourself. This should be in addition to whatever data backup plan your host has at their end.

Know what’s going on in the background

There is more to Koha than the database. If you ever decide to change to another Koha host/support company you’ll need to know some things about your Koha installation that aren’t stored in the database.  Your host will have set up cron jobs to run background scripts on a regular schedule. Communicate with your host about what these settings are. Know when things are running and how often.

Insist that any development you sponsor be released to the Koha community

If you’re interested in preventing being locked in to any one vendor this is very important. If you pay your Koha support company to develop a new feature for Koha and they don’t release it as open source, your Koha installation will be unique and potentially incompatible with Koha installations built from the official release. Your host will be able to say to you, “Sure you could switch hosts, but you’ll lose such-and-such feature and the data associated with it.” This is what vendor lock-in is all about.  Insist that your support company/host to be a  part of the Koha open source community. Insist that anything they develop for you gets released to the community as soon as it is complete. Or better yet, ask that they do this development out in the open, using public source repositories which can be accessed by other Koha developers. To insist on these conditions is to protect your organization and make sure you can freely make decisions about Koha support and hosting in the future.

The worst case scenario

In the worst case scenario your hosting and support company vanishes from the face of the earth and takes your data along with it. Because you’ve got a backup and details about other required settings, you can pick right up where you left off with a brand new host. Because the features you sponsored were released as open source, they’re either already in the standard Koha code or can be re-integrated by your new support company.

The best case scenario

In the best case scenario, you’re moving from one hosting and support company to another for reasons other than catastrophe.  Because you’ve taken ownership of your data and taken an active role in understanding your Koha configuration, you’re able to bring everything to the table your new host needs. Migrating from one standard Koha installation to another is so simple compared to ILS migrations of the past that you’ll be amazed.

In the cycle of Koha development there are slow times and there are busy times. Right now is a busy time. We’re in the run-up to a big release, Koha 3.2. It has been sixteen months since the release of Koha 3.0. Since that time developers have been working on two tracks: The first track is one devoted to bug-fixes and minor enhancements to 3.0.x. The fruits of those labors can be found in the realeases of Koha 3.0.1, 3.0.2, 3.0.3, 3.0.4, and most recently 3.0.5. Each of these releases reflects incremental improvements.

At the same time work on major new features has taken place along the other track, the track leading to Koha 3.2. Major new features will often include structural changes like new software dependencies or database structure changes.  For an interface designer like me this track is always the most interesting, because new features means new interfaces to help refine.

This is an exciting time because the Koha project has recently gotten a large contribution of code from BibLibre, a French Koha development and support company. BibLibre has a long history with Koha and a long history with the Athens County Public Libraries: When we were preparing to switch to Koha in 2002 BibLibre answered our RFP to add MARC support to Koha.  Eight years later BibLibre is still a major contributor to Koha. Included in their recent submission is the new acquisitions functionality which Paul Poulain discussed at KohaCon 2009.

Much of what I do when I work on Koha is to look at existing or new interfaces and try to do what I can to make them cleaner, improve their structure, and help the design however I can. Some of these changes are guided by standards, whether they be web standards or simply conventions we’ve adopted for markup and interaction design. When a big contribution like BibLibre’s comes along, I start the process of reviewing every template and every new interface to see if everything works well and looks good. This isn’t just a process about making things look pretty, it’s a perfect opportunity to do some informal usability testing, some bug-hunting, and some bug-fixing.

This is what working on an open-source project is all about: contributing our work to the project to make the best software we can. And the best thing about it is it’s a lot of fun.

Seems like lots of people hate the login form on Koha’s OPAC.  I understand many have a problem with it because their users look at and think they must log in to use the catalog. There’s no switch to flip to turn off display of the login form on the main page, but you can use a little custom CSS to hide it.

Add this to your OpacUserCSS system preference:

#login {
display: none;
}

One disadvantage to this technique is that it doesn’t allow your main page content to take up the whole width of the front page. The right-hand column of the OPAC’s main page remains pretty much inflexible in terms of content.

What if you don’t want to eliminate the option of logging in from the home page but you don’t like the big login form? Recently someone posed this question on the Koha mailing list.

Any thoughts on where to look to move the “Login to Your Account” and the Username and Password blanks to the top and replace the link there for “Login to Your Account” with Username and Password?

I started jumping in with some JavaScript when I realized this could be accomplished using just CSS. Here’s the result:

Click to enlarge image

Here’s a rundown of what’s going on in the custom CSS:

• Styling the form container with position: absolute and placing it in the top right corner. The form overlaps and hides the default login link in the top right corner.
• Styling all the form contents as inline instead of block.
• Adjusting margins, padding, font-size, and width.
• Hiding the login form’s title (“legend”).

Why did I hide the form’s title? It wasn’t for aesthetic reasons. I found that Internet Explorer 6 refused to display the title (which is a <legend> inside a <fieldset>) in line with the rest of the form. IE6 wanted to give the <legend> its own line. Some conditional comments could alleviate the problem if you wanted to deliver the title to browsers that can display it correctly.

To give the form some room there at the top of the page I added a little bit of margin to the top of the main search bar. If your OPAC design includes custom header content you might have to adjust that margin.

I’ve tested this in these browsers on Windows XP: Internet Explorer 6, Firefox 3.5, Safari 4, Opera 10, and Chrome 3. Below is the CSS in its entirety. Add it to your custom stylesheet or to your OpacUserCSS system preference.

#login {
background-color : #FFF;
position : absolute;
top : 0;
right : 0;
padding-top : 5px;
width : 22em;
}
#auth fieldset,
#auth fieldset.brief {
border : none;
display : inline;
margin : 0;
padding : 0;
}
#auth input {
font-size : 75%;
}
#auth legend {
display : none;
}
#auth label {
display : inline;
font-size : 85%;
}
#auth li,
#auth ol {
display : inline;
}
#login #userid, #login #password {
width:auto;
}
#auth fieldset.action input {
margin: 0;
padding : 0;
}
#auth fieldset.action {
margin-bottom : -5px;
}
#opac-main-search {
margin-top : 1.5em;
}

Someone posted an enhancement request today requesting a change to the way the patron entry form is arranged in the Koha staff client. By default the patron entry form is pretty long, and the request asks that required fields be grouped at the top.

It seems like a reasonable request, but there’s a big disadvantage to trying to solve this problem with a template-only change: Libraries can customize which fields are mandatory when entering patrons. The system preference for that is  BorrowerMandatoryField (“borrower” being the term used in place of “patron” at the time of the preference’s creation).

What alternatives might there be to a template-only solution?

1. Alter the script which generates the patron entry form so that any required fields (no matter which ones they are) are displayed at the top.
2. Create a “quick-add” form which shows only required fields.
3. Add a filter to the full patron entry form to toggle display of non-mandatory fields.

I like option two as a long-term solution, but option three could be implemented now with some custom JavaScript. Here’s a proof-of-concept script to show that using the markup which exists in the form now we can pull only required fields:

$(document).ready(function(){
var list = "<fieldset class=\"rows\"><legend>Quick Add<ol>";
$("label.required").each(function(){
item = $(this).parent().html()
item = "<li>"+item+"</li>";
list += item;
});
list += "</ol></fieldset><fieldset class=\"action\"><input type=\"submit\" value=\"Save\" onclick=\"return check_form_borrowers();\" name=\"save\"/><a href=\"/cgi-bin/koha/members/member.pl\" class=\"cancel\">Cancel</a></fieldset>";
$("#entryform").prepend(list);
});

Paste that into your intranetuserjs system preference or into Firebug’s command line to give it a try. Note that this solution assumes two things:

1. You’ve already specified a patron category (by choosing one from the “new” menu).
2. You’re adding patrons to the default branch for your logged-in user.

Of course the form could be customized to include these choices, but they’re probably safe assumptions for quick adds. A better implementation of this would probably allow you to toggle between either view: quick or standard.

Firefox’s Firebug addon has a feature that isn’t obvious at first glance, but can be very useful. I think it’s particularly helpful when writing jQuery because jQuery can do so much in just a few lines. It’s perfect for testing in Firebug’s command line. When you first start Firebug you’ll see something like this:

Click to enlarge screenshot

If you haven’t enabled the Console, you’ll get a message telling you so. Enable the Console before proceeding. The Console says “Reload to activate window console” because you turned on Firebug after the page rendered. Reload the page to get the Console ready for action.

Most obvious is the big blank space, but below that is what we’re looking at today: the command line, prefixed with “>>>.” Type some JavaScript on the command line, hit enter, and Firebug will execute that JavaScript on the current page.  Try:

>>> alert("Hello World");

When you type that in and hit enter, your browser should pop up a JavaScript alert. The command line can be used to enter sequences of JavaScript too, so it doesn’t always have to fit on one line:

>>> var x = "Hello World";
>>> alert(x);

But the coolest part is that you can test all your jQuery stuff here. One of the trickiest parts of jQuery can be writing the right selector, targeting just the right element[s] on the page. Firebug’s command line makes it easy, because you can do all your testing without having to go back and forth between your OPAC page and the opacuserjs system preference in the staff client. Get your script just right in the command line, then save it when its finished. Let’s try something really basic:

>>> $("a").hide();

The result:

Click to enlarge screenshot

Firebug even lists the affected elements in the console. Click any of them and you’ll be shown that element in the HTML tab.

What if one line isn’t enough?  Click that little red button in the lower right corner of the screen (see the screenshot above) to expand the command line into a “command box.”

Click to enlarge screenshot

Now you’ve got plenty of room to write and test longer, more complex scripts. Just enter your JavaScript and click the “Run” button to execute it. One nice aspect of this feature is that what you enter in the command line stays intact even after you refresh the page.

For a practical example, let’s take a look back at my post on adding an additional search option to the OPAC’s detail page. Here’s the script we ended up with:

$(document).ready(function(){
var orig = $("#catalogue_detail_biblio h1").remove("span").html();
var regexp = new RegExp ("<span[^.]*\/span>", "gi");
var title = orig.replace(regexp,"");
$("#further ul").append("<li><a href=\"http://www.paperbackswap.com/book/browser.php?phrase_k1="+title+"\">Paperbackswap.com</a></li>");
});

Copy that script and paste it right into the Firebug command line. Click “Run” and you’ll see the result right away. For testing purposes we don’t really need the “$(document).ready()” part, because we’re executing the script on an already-loaded page. But it seems to work either way.

It’s important to note that this feature of Firebug works on any site. You’re not interacting with the server on which the page is hosted, you’re just manipulating the HTML within your browser. If you want to test out some of the JavaScript tricks I’ve used in my posts here you don’t even need your own installation of Koha. You could test them on someone else’s OPAC.

In a previous post I talked about YUI Grids and how we use them to structure Koha pages–all very abstract unless you’re interested in designing Koha pages.  But there are some opportunities to use the Grids techniques in OPAC customization.

Two OPAC system preferences, opacheader and OpacMainUserBlock, are good candidates for some Grids experiments. Both let us add our own HTML markup to the Koha OPAC design, and both are placed within the default page structure defined by the Grids framework. That should let us use our own structure of grids and units to create containers for our content.

Let’s start with opacheader, and the basic grid/unit example of two equal-width containers, or columns:

<div class="yui-g">
<div class="yui-u first">
<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat.</p></div>

<div class="yui-u">
<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat.</p>
</div>
</div>

Add that to your opacheader system pref and you’ll get this:

Click to enlarge screenshot

If that doesn’t look terribly thrilling (or even practical), think of it this way:

Click to enlarge screenshot

Somewhat more practical, at least? And remember, you’ve got a selection of preset grids to choose from:

• .yui-g – Standard half grid (and nest again for quarters).
• .yui-gb – Special grid, 1/3 – 1/3 – 1/3
• .yui-gc – Special grid, 2/3 – 1/3
• .yui-gd – Special grid, 1/3 – 2/3
• .yui-ge – Special grid, 3/4 – 1/4
• .yui-gf – Special grid, 1/4 – 3/4

Quoted from the YUI Grids page

Customizing OpacMainUserBlock

OpacMainUserBlock is the place where it would be the most useful to leverage the Grids framework’s power. The main page of the OPAC is a blank slate for your library’s custom content. It would be great to be able to use the built-in grids system for laying out that content.

Let’s try the same sample markup from the previous example. Two easy and equal-width columns, right? Wrong:

Click to enlarge screenshot

What’s going on? That doesn’t make sense, does it? Well…It makes a certain amount of sense. We have to remember that when dealing with OpacMainUserBlock we’re already working within an existing grid:

The default structure of the OPAC main page, non-logged-in state

The OPAC template for the main page defines a grid with a 75% block (“yui-u first” in the diagram above) and a 25% block (“yui-u”). That means that when we add markup to OpacMainUserBlock, we’re adding that markup within a <div class=”yui-ge first”>. The YUI Grids documentation tells us that if we want to nest grids we should do so by nesting <div class=”yui-g”> directly. Try this in OpacMainUserBlock:

<div class="yui-g first">
<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat.</p></div>

<div class="yui-g">
<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat.</p>
</div>

This is the result:

Click to enlarge screenshot

Better. Usable, anyway. But why did we get another 75%/25% split? We didn’t add a grid with the “yui-ge” class. To be honest, I’m not sure whether there is any way to avoid getting the 75%/25% split when we nest a grid here.  It seems that any time we nest a grid inside a “yui-ge” grid, we get another “yui-ge” grid. In other words, it’s turtles all the way down:

Click to view example

Not freedom, only some flexibility

It seems were left with very limited choices if we want to try to leverage YUI’s Grids system in the context of OpacMainUserBlock. If you’re content with a 75%/25% split, then you’re okay. Otherwise you’re on your own to define a content layout your own way.

If you want to use tables, I won’t tell.

Now that you’re happily (or at the very least, somewhat tediously) customizing your additional search links, your future is bright and worry-free, right? Not quite. I submitted a patch recently to the Koha project which makes a change to the OPAC template, altering the way the additional searches are displayed. Instead of showing all the search links by default, in Koha 3.2 the links will be hidden and displayed in a drop-down menu.

Click "More searches" to display a menu

Why the change? To conserve screen real estate. Some libraries were finding that with lots of data in the holdings table, and lots of options in the menu which includes the additional search links, content was overlapping and becoming unreadable. Here’s an example from the Koha bug report:

Click to enlarge screenshot

My change to the template alleviates the problem in two ways: by collapsing the additional search links, and by hiding the left-hand navigation menu on this page. The latter decision may generate some heat. I felt it was a fair trade-off in order to have a non-broken display, but if others disagree I hope I’ll hear about it.

Coping with change

What does this mean for those of us who have customized their search links? Luckily, only a few changes to the code we covered previously:

$(document).ready(function(){
var orig = $("#catalogue_detail_biblio h1").remove("span").html();
var regexp = new RegExp ("<span[^.]*\/span>", "gi");
var title = orig.replace(regexp,"");
$("#furtherm ul").append("<li class=\"yuimeuuitem\"><a class=\"yuimenuitemlabel\" href=\"http://www.paperbackswap.com/book/browser.php?phrase_k1="+title+"\">Paperbackswap.com</a></li>");
});

There’s only a couple of changes to note:

First, the HTML element we’re appending a list item to has changed to “#furtherm ul.” That identifies the list which is being used to construct the menu.

Second, there are some additional classes being added along with our list item. The classes are there so that the additional list item is styled properly along with the other menu items. The new menu is being created using YUI’s Menu component.

If you’re running the most recent development version of Koha, you can try the revised JavaScript. Here’s the result:

Our custom link has been added to the menu

If you’re not running the most recent development version, bookmark this page for later reference. When your Koha installation gets updated, you’ll need to revise your script!

On every record’s detail page there is list of links in the right-hand sidebar for searching for that title on a few other sites: Worldcat, Google Scholar, and Bookfinder. These were chosen as reasonably generic choices for a wide audience. The trouble is, generic doesn’t work for everyone: For many libraries these links aren’t appropriate. They’d like to be able to take out one or more of them and/or add their own. Unfortunately these links are hard-coded in the template. Until someone contributes the time or money to develop a solution, we have to resort to JavaScript trickery to accomplish it.

JavaScript Trickery

jQuery to the rescue. If we use FireBug to inspect the page we can see that the “box” the links are in has a unique ID. That’s perfect as a place to tell jQuery to start looking.

Click for full screenshot

Let’s start by adding a custom link to this menu. We start our JavaScript by targeting the #further div. Since we want to add an item to the list contained within the #further div, we’ll add that to the selector:

$(document).ready(function(){
$("#further ul")...
});

And since we want to append some additional HTML, we’ll use append():

$(document).ready(function(){
$("#further ul").append("<li><a href=\"http://www.paperbackswap.com\">Paperbackswap.com</a></li>");
});

Okay, drop that into the opacuserjs system preference and refresh your OPAC page to see how it worked:

Updated list of links

Great! We’re done, right? Well… The trouble is, the link we added doesn’t include any means to pass the title to the search system on the other site. How are we supposed to do that? Luckily, many sites are very open in the way they perform search requests. You just have to do a little digging. Let’s go to Paperbackswap.com and do a search to see how they handle it. Since I know we’re going to pass a title to their search system, I’m going to look for a title-specific search. I found one on their advanced search page. Plug in a title and look at the resulting URL:

http://www.paperbackswap.com/book/browser.php?all_k=&not_k=&or_k[]=&or_k[]=&phrase_k1=cryptonomicon&all_ti=&not_ti=&or_ti[]=&or_ti[]=&phrase_ti1=&a=&i=&bd=&p=&g=0&b[]=Paperback&b[]=Audio+Cassette&b[]=Hardcover&b[]=Audio+CD&pd=&pd_type=e&r=n&s_type=a&l=10&sby=&oby=ASC

What a mess! But underneath all that junk there’s one bit of real functionality there:

http://www.paperbackswap.com/book/browser.php?all_k=&not_k=&or_k[]=&or_k[]=&phrase_k1=cryptonomicon&all_ti=&not_ti=&or_ti[]=&or_ti[]=&phrase_ti1=&a=&i=&bd=&p=&g=0&b[]=Paperback&b[]=Audio+Cassette&b[]=Hardcover&b[]=Audio+CD&pd=&pd_type=e&r=n&s_type=a&l=10&sby=&oby=ASC

It looks to me like phrase_k1=cryptonomicon is the meat of the search, and everything else is defaults. Let’s try the link this way and see if we get good results:

http://www.paperbackswap.com/book/browser.php?phrase_k1=cryptonomicon

Seems to work just as expected. Now we know that we can use a link like this to pass our own search term to the site:

http://www.paperbackswap.com/book/browser.php?phrase_k1=<title>

Using JavaScript to find the title

Click to enlarge screenshot

We’re building the custom search link with JavaScript, so we’ll have to find a way to leverage the same tool to grab the title.  Luckily there is a unique element on the page which contains the title, and we can grab it using jQuery: the <h1> tag. Okay, so there are two <h1>’s on the page, a little bit of a technical foul on Koha’s part. Using FireBug we can ispect the <h1> containing the title and we can see it is contained in a uniquely identified container. We can grab the contents of the heading this way:

$(document).ready(function(){

var title = $("#catalogue_detail_biblio h1").html();

});

Add this to code we wrote to add the custom link along with the search URL we puzzled out:

$(document).ready(function(){

var title = $("#catalogue_detail_biblio h1").html();
$("#further ul").append("<li><a href=\"http://www.paperbackswap.com/book/browser.php?phrase_k1="+title+"\">Paperbackswap.com</a></li>");
});

Notice we’re using + to concatenate the JavaScript variable with the markup that forms the link. Looks good, and the link works!

Our new link passes the correct title to the other site

…Until we come to a record which has a subtitle. For example, The return of the king: being the third part of The lord of the rings

You got markup in my content!

The problems arises because the subtitle is marked up with a <span> inside the
<h1>. When we grabbed the contents of the <h1> tag, we also got the <span>. We’ll have to do some more JavaScript trickery to drop the <span>. Here’s what I came up with, thanks in part to this demo:

$(document).ready(function(){

var orig = $("#catalogue_detail_biblio h1").remove("span").html();
var regexp = new RegExp ("<span[^.]*\/span>", "gi");
var title = orig.replace(regexp,"");
$("#further ul").append("<li><a href=\"http://www.paperbackswap.com/book/browser.php?phrase_k1="+title+"\">Paperbackswap.com</a></li>");

});

Now we’re getting just the title, and we’re getting the correct link. Success.