Tag Archives: Customization

Customizing your additional search options: future reference

Update: Nicole recently submitted a patch which will make this entry obsolete. Read on if you’re curious about the jQuery involved, but otherwise look forward to custom further searches in Koha 3.2.

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

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

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>", "gi");
var title = orig.replace(regexp,"");
$("#furtherm ul").append("<li class="yuimeuuitem"><a class="yuimenuitemlabel">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

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!

Customizing your additional search options

Note: This article applies to Koha 3.x installations. Nicole recently submitted a patch which add custom further searches to Koha 3.2.

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. search-for-this-title-in 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

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

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

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

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!

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>", "gi");
var title = orig.replace(regexp,"");
$("#further ul").append("<li><a>Paperbackswap.com</a></li>");

});

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

Add a Koha login form to your web site

opac-login-on-library-site

This question came up on the Koha mailing list today: How can I add a Koha login form to my library’s web site? Luckily it’s really simple. The image here is of the one we added one to our site.

Everything you need to know about how to do it is right on your Koha OPAC home page. Just view the source for the login box and copy it! Here’s the simple version, adapted right from the source:


<form method="post" action="http://path.to.your.opac/cgi-bin/koha/opac-user.pl">

<label for="userid">Login:</label>
<label for="password">Password:</label>

</form>

The only thing you’d need to change to make that snippet work for you is the path.to.your.opac part. Replace that with the full URL of your Koha OPAC, e.g. http://acpl.kohalibrary.com.

You could even do the same for the staff client, for instance if you wanted your users to be able to log into the Koha staff client from your library’s intranet:


<form method="post" action="http://path.to.your.staff.client">

<label for="userid">Username:</label>
<label for="password">Password:</label>

</form>

Of course I wouldn’t recommend putting a login form for your staff client anywhere in public view. Note that using that form will log you in to your default library. If you wanted to give your users the option of logging into a different library you’d have to reproduce the full <select> tag from your staff client’s login page.  View the source to find it.

Interface Test: Editing from the additem table

One of the custom reports I’ve been using recently is one that shows me the most expensive items in the catalog. I’m not trying to figure out which book to sneak out under my coat, I’m trying to find data-entry errors which might cause problems for the patrons.

You lost that paperback? That’ll be $4399.00.

The trouble is, once I’m cruising through this report making corrections I’m quickly frustrated by the interface for adding items.additem-interface

The list of items is in its own container with the css property “overflow:auto” so that if it exceeds the constraints of the container it’s in it will display scrollbars. It always displays scrollbars. You have to scroll to the right to see the item’s replacement price, then back to the left to find the Edit link. And it’s hard to be sure you clicked the Edit link in the correct row, because once you’re at the Edit link you can’t see the price anymore!

What if we could access the Edit and Delete functions from anywhere in the row? Inspired by WordPress’s inline edit menu I worked up this example:

additem-inline-edit

Try navigating anywhere in the table of item details and clicking a table cell. You’ll see Edit/Delete links appear for that row. Implementing this change would allow the user to jump to the Edit or Delete functionality from anywhere in the table eliminating the need to scroll back and forth for the static links.

The advantage to the method used in this example is that it’s simple: no generating tooltips or modal dialogs, just a simple append of the Edit|Delete links to the table cell which gets clicked.


$("td").click(function(event){
var $tgt = $(event.target);
if($tgt.is("a")||$tgt.is(":first-child")||$tgt.is(":nth-child(2)")){ return true; } else {
var rowid = $(this).parent().attr("id");
num_rowid = rowid.replace("row","");
$(".linktools").remove();
$(this).append("<span class="linktools"><a>Edit</a> | <a>Delete</a></span>");
}
});

The disadvantage to the resulting UI is that it could suggest to the user that clicking Edit or Delete will edit or delete just the contents of that cell, which is of course incorrect. It wouldn’t be good for a librarian to expect a click on “Delete” to delete, for instance, only the value contained in the replacementprice field and find that the entire item had been deleted.

I’m not sure how to mitigate that confusion while retaining the script’s simplicity.

Update: Here’s an alternate, slightly more verbose version.

Interface test: Collection code groups

Does your library have too many choices on the OPAC’s advanced search page? From the point of view of our librarians we don’t, but I think from the point of view of the patrons we do. 43 choices? And many of those categories encompass the same materials or genres. You could easily group our categories using format, audience, or other criteria:

  • DVDs: DVD, DVDJ, DVJN, DVDN
  • Videos: AV, AVJ, AVJN, AVNF
  • Movies: DVD, DVDJ, DVJN, DVDN, AV, AVJ, AVJN, AVNF
  • Books for adults: AF, MYS, SCI, WES, LP, LPNF, PB, BIO, NF
  • Large Print: LP, LPNF

It’d be great if you could define “category groups” in Koha to allow patrons to easily search multiple categories at once. Until that comes about, how can we approach the problem from the front end?

Selecting Multiple Categories with JavaScript

Here’s a little experiment I worked up. This is just a static example page to demonstrate the selections.  Some parts of the OPAC omitted for simplicity.

opac-cccode-groups

Try clicking the links at the top of the category table. Clicking “Books” will select all collection codes which I’ve defined as a book for adults. Clicking “Audio Books” will select any category which could be defined as an audio book, whether it be on CD, cassette, or Playaway.

All the functionality of this example could be layered on top of the OPAC using existing avenues for customization like the opacuserjs system preference. It’s not very efficient to set up, however, because you have to hard-code all your collection codes within the JavaScript. That means that you have to update your script any time you add a category.

var books = "#ccode-1,#ccode-5,#ccode-12,#ccode-13,#ccode-14,#ccode-15,#ccode-16,#ccode-17,#ccode-18,#ccode-19,#ccode-27";
var movies = "#ccode-2,#ccode-3,#ccode-4,#ccode-6,#ccode-23,#ccode-39,#ccode-40,#ccode-41";
var lp = "#ccode-13,#ccode-14";

Defining your “supercategories” could be as difficult as defining your original categories in Koha. What criteria do you use? Audience? Format? Content? In my example I mix all three. Would that be confusing to patrons? I may yet add this to our OPAC, but I’ll have to ponder these issues a little more.