Koha Blog

I was thinking about ease of use, and what we could to to improve the Koha OPAC from the point of view of the patrons, and the first thing my mind jumped to was the process of placing holds. For many patrons placing a hold is the goal of their visit to the OPAC. They’re looking for something they want, they find it in the catalog, and they want to get it. On Amazon.com the next step would be to buy it. In the OPAC they can place a hold.

What’s the first thing they see when they click one of those “place hold” links? Potentially this:

Place hold interface with all options turned on

I hate it. It’s an ugly table with too many options. True, you can turn off some of those options for a simpler process. Turn off the OPACItemHolds system preference to eliminate the option of choosing a specific copy. Turn off OPACAllowHoldDateInFuture to hide the Hold Starts on Date column. Turn off OPACDisplayRequestPriority to hide the hold request’s rank in the queue. Now it’s a little simpler:

With optional settings turned off

I’m still not crazy about it, and that’s why holds came to mind when I thought about what we could do to improve interactions in Koha. How can we make that interaction simpler? How about [almost] one-click “ordering?”

Click the "Place hold" link in the right sidebar

When you click the “Place hold” link you can see my idea demonstrated. Clicking the link would use JavaScript to display a simple form: Place hold? Yes/No. Embedded in the HTML would be all the required form fields, hidden, for placing a single hold with no options set, using the patron’s home library as the destination for the hold. If the patron wanted to set additional options they could click the “more options” link and be taken to the standard form.

How hard would this be to implement? It depends how far you want to take it. I could see  this being a JavaScript-only enhancement, assuming all the information we need is found on this page. In this version clicking the “Yes” button would submit the form to the same script the standard form does, but bypass the hold confirmation screen. The user would be redirected to their summary page showing current holds.

A fancier version would submit the form in the background. Clicking the “Yes” button would triggers a sequence of events:

1. The hold would be submitted in the background.
2. The interface would display some kind of “Working” indicator.
3. Upon completion of the background submission, the interface would indicate success.

This is more complicated because the reserve script would have to be modified to work in new way. Error-handling would have to be incorporated so that if for some reason the hold couldn’t be processed the user could be warned. The advantage to this interaction is that the user never leaves the page, making it easier for them to find their way back to their original search–something which, incidentally, is also on our to-do list of ways to make things easier for the user.

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.

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.

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:

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 href=\"/path/to/additem/script.pl?op=edititem&amp;amp;biblionumber="+biblionumber+"&itemnumber="+num_rowid+"\">Edit</a> | <a href=\"/path/to/additem/script.pl?op=delitem&amp;amp;biblionumber="+biblionumber+"&itemnumber="+num_rowid+"\" onclick=\"confirm_deletion("+biblionumber+","+num_rowid+"); return false;\">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.

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.

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.

The OPAC’s Cart and Lists buttons are an unusual construction. Their appearance is the result of a rather convoluted combination of CSS and HTML designed to give nice anti-aliased, rounded corners and flexibility when the text is resized.  Try increasing the font size in your browser (Ctrl +).

The technique to create these buttons was adapted from Scalable CSS Buttons Using PNG and Background Colors.  If you’re interested in understanding the real nuts and bolts of the technique I suggest you read through that article. I’m going to cover just the details we need to look at for customizing the default appearance in Koha.

There are several options we need to cover when changing the buttons’ appearance:

1. The link and link hover color
2. The button background-color (default and hover)
3. The button border

The Cart and Lists buttons each have their own ID in the HTML for reference in the CSS: #cartmenulink and #listsmenulink. Let’s look at the Lists button for simplicity’s sake.

1. The link color

The link color is the most straightforward one: Target the A element with the #listsmenulink ID:

a#listsmenulink { color: #E5CCE6; }
a#listsmenulink:hover { color: #FF99FF; }

2. The button background-color (default and hover)

The buttons have both a default background color and a hover background color. Set them by targeting the #listsmenulink ID:

#listsmenulink { background-color : #6600CC; }
#listsmenulink:hover { background-color : #9900CC; }

If we’re just changing background colors, and not images, on the button, how is it possible that we get a nice gradient? The answer is in this part of the default CSS:

#listsmenulink[class] {
background-image : url(../../images/button-background-gradient.png);
background-position : left top;
}

That’s a PNG file with alpha transparency. It overlays the solid background color and softens it with a gradient. If you like the gradient you can leave this part of the CSS without overriding it in your custom stylesheet. It will work with whatever background color you specify. If you want to turn it off to have a solid-color button, use this:

#listsmenulink[class] {
background-image: none;
}

3. The button border

Changing the button border is the trickiest step because it requires an image editor. The button border consists of a single background-image:

How the button would appear if the border image had transparent corners

The image gives the button its border color. The center of the image is transparent. The corners are opaque, colored to match the blue of the default background of the search bar. The corners have to be opaque because they have to mask the square corners of the HTML element behind them.

Changing the background color means the corners no longer match what is behind them

The fact that the corners are colored to match the default background means that if you try to change that background color your buttons will no longer match.

At the moment the only solution for those wishing to make changes to the button background is to recreate it from scratch. I’d like to share the source files I’m using so that in the future it’s easier for Koha users to make this change themselves. I use Photoshop 7 much of the time (yes I know it’s old), so I’m offering that version. I also recreated the graphic in Fireworks MX (again, old) and Inkscape .046 (yay, up to date!).

Whatever program you use to edit these files, there are two basic steps to achieve the right look:

1. Edit the stroke of the button shape (the border color).
2. Change the color of the opaque corners.

Our edited button background image gives us corners that blend perfectly with our custom background color.

After your file is edited to your satisfaction the next step is to export it in a web-friendly format:

• If you’re using Photoshop use File > Save for Web and choose PNG-24 with the Transparency option checked.
• In Fireworks, your Optimize setting should be PNG32 with the transparent matte option chosen.
• In Inkscape, use the Export Bitmap option to export the Drawing only. In my tests Inkscape exported the 32-bit version (the version with alpha transparency) by default.

What About Internet Explorer 6?

Users of Internet Explorer 6 will see a solid-color button with square corners.

One major downside of this method of styling the buttons is that it doesn’t work properly in Internet Explorer 6. IE6 doesn’t support PNG files with alpha transparency. The good news is that users of IE6 will still get a usable button. The bad news is that it won’t be very pretty.

Options Going Forward

If we’re already excluding users of Internet Explorer from the rounded button experience, why not use pure-CSS rounded corners? We could eliminate all the time and effort demonstrated in this article with some simple [if proprietary] CSS. Something like this:

#cartmenulink,#listsmenulink {
color: #336600;
padding: .7em .9em .7em .8em;
margin: .5em .5em .5em 1.5em;
text-decoration:none;
-moz-border-radius: 7px;
-webkit-border-radius: 7px;

}
#cartmenulink {
border:1px solid #336699;
background: #93d869 url("../../images/cart-button-background.png") top left repeat-x;
}
#listsmenulink {
border:1px solid #006699;
background: #9FBFFF url("../../images/lists-button-background.png") top left repeat-x;
}

This works fairly well in Firefox, Safari, and Chrome. Unfortunately, it fails not only in Internet Explorer 6, 7, and 8, but all versions of Opera too. For the time being, our more-complex process gives the desired result to a wider audience.

Using *-border-radius to style rounded corners. Click to view full-size.

I got a question yesterday on the Koha IRC channel about changing the background of message which appear onscreen during check-in operations. Aparently librarians were not noticing the messages, and the questioner wondered if those messages could be styled in a different way.

Koha prompts the user to return an item to its home library with a message box

It’s possible to customize Koha’s staff client just like it’s possible to customize the OPAC. At the moment, though, the staff client lacks one useful option: a means of injecting custom inline CSS as we can with OpacUserCSS. The staff client does have intranetuserjs, and that gives us an opportunity to get around the shortcoming.

PLEASE NOTE: As the manual says, “IMPORTANT: This system preference is an advanced option. If you enter a value with incorrect syntax you can make it very difficult to access the staff interface.”

Here’s how intranetuserjs gets added to the markup. From the template:

<!-- TMPL_IF NAME="intranetuserjs" --><script type="text/javascript">
//<![CDATA[
<!-- TMPL_VAR NAME="intranetuserjs" -->
//]]>
</script><!-- /TMPL_IF -->

IF the intranetuserjs system preference has anything in it, the template will include it, wrapped in the appropriate <script> tags. Here’s how we’ll bend the rules to get our custom CSS in: Add this to the intranetuserjs pref:

//]]>
</script>
<style type="text/css">
/* Insert custom styles here */
</style>
<script type="text/javascript">
//<![CDATA[

When we add that to the intranetuserjs preference, Koha generates this markup in the template:

<script type="text/javascript" >
//< ![CDATA[
//]]>
</script>
<style type="text/css">
/* Insert custom styles here */
</style>
<script type="text/javascript">
//<![CDATA[
//]]&gt;
&lt;/script&gt;

The first thing we do is close the <script> tag which was automatically opened by the template, which expected us to add JavaScript content. We add our custom <style> tag, then re-open the <script> tag. The template is going automatically add a closing <script> tag, so we’ve got to add an opening one or risk breaking things.

With that in place we can add our custom CSS. The message box gets its background from an image. The simplest way to customize its appearance is to remove the image and add a custom color:

div.message { background: #CCFF00 none; }

Remove the background image and add a custom color

Or use your own background image:

div.message { background:white url(http://www.myacpl.org/koha/wp-content/uploads/2009/07/squidfingers-pattern_141.gif) scroll left 0;
}

Eye-catching but not very readable!

If you’re going for really eye-catching, you’ll have to go for an animated background image!

If you find a background image you like, remember: copy the image to your own server. Don’t hot-link it from someone else’s. Nefarious webmasters are likely to swap out the image for something you don’t want to see!

Of course I don’t really recommend that you use an animated background. As you’re approaching this kind of change, please remember: changing the style of Koha’s default message box will change all instances of that style box. Koha re-uses that style for displaying informational messages throughout the interface. The staff at the circulation desk may like it, but the cataloger doing MARC imports may not!

I often hear people ask if they can have their book covers on the left-hand side of the search results list. This is one of the aspects of Koha 2.x that some people miss. Because the search results are in a table, you can’t simply change something in the CSS to move the images to the other side of the screen. Without changing the template itself, what can we do?

Usually my response is live with it, but it occurred to me yesterday that jQuery could handle this:

$(document).ready(function(){
$(".searchresults tr td:last-child").each(function () {
$(this).prependTo($(this).parent());
});
});

After the standard leading “(document).ready” stuff, the script starts by looking for elements inside anything with a class “searchresults.” That’s a <div> that surrounds the search results table. We’re looking for any <td> which is the “last child” of a <tr>. That is, the last table cell in each table row. jQuery’s each() function lets us loop over each instance of those last-child <td>’s that we find and perform some action on it.

$(this).prependTo($(this).parent());

This is the action we’re performing for each <td> our script matches. “$(this)” is how we identify the matched <td>. Then we use the prependTo() function to “cut” that <td> and “paste” it at the beginning of the row. Notice the element we’re prepending to is “$(this).parent().” parent() selects the element which “contains” $(this): <tr> contains <td>, so we’re moving our <td> to the beginning of the row.

Paste the script into your opacuserjs system preference and try a search. It works in my test, but don’t take my word for it. Test carefully and let me know if you see any problems with it.

This post was my way to “talk out” the issues I wanted to cover for my presentation at KohaCon 2009. Some of it consists of condensed versions of other posts already on the site, so please take a look around at the other stuff I’ve posted. — Owen

(more…)

On of the options we have for customizing Koha’s OPAC is to add a custom menu to the left-hand column. Just like with the opacheader preference, this is done by adding HTML markup to a system preference: OpacNav (Koha has an annoying lack of consistency when it comes to system preference capitalization).

If you’ve just installed Koha for the first time there is probably some default text in your OpacNav preference, “Important links here.” This bit of example content might lead to questions like “Important links where?,” but it’s just a way to point out one of your customization options. If you delete the contents of OpacNav, the left-hand column will go away on most pages. The exception is the facets column on the search results page and menus on user pages when you’re logged in.

The Athens County Public Libraries OPAC has no OpacNav content for a couple of reasons: First, our site-wide navigation is in the horizontal menu in the OPAC header; Second, having a resident left-hand sidebar takes up valuable screen real estate. I’d rather be able to give plenty of room for the content the user is looking for.

Other libraries choose to add content to the OpacNav preference because it fits their users’ expectations (as it did ours in our previous designs). Luckily OpacNav is just as flexible as opacheader in terms of creating the look and feel you want.

Creating the custom menu

OpacNav is even easier than opacheader because its position in the template doesn’t lead to any float/clearing problems like we saw in the opacheader article. Let’s start again at Listamatic for a good self-contained vertical list design. I’m going to pick a fairly simple one: Bieler Batiste’s list. The HTML gets pasted into the OpacNav preference:

<div id="navcontainer">
<ul id="navlist">
<li id="active"><a href="#" id="current">Item one</a></li>
<li><a href="#">Item two</a></li>
<li><a href="#">Item three</a></li>
<li><a href="#">Item four</a></li>
<li><a href="#">Item five</a></li>
</ul>
</div>

Paste the CSS into your custom stylesheet (specified in opaccolorstylesheet) or paste it into the OPACUserCSS preference:

#navlist li
{
display: inline;
/* for IE5 and IE6 */
}

#navlist
{
width: 7em;
/* to display the list horizontaly */
font-family: sans-serif;
margin: 0 0 0 3em;
padding: 0;
border-top: 1px #000 solid;
border-left: 1px #000 solid;
border-right: 1px #000 solid;
}

#navlist a
{
width: 99.99%;
/* extend the sensible area to the maximum with IE5 */
display: block;
background-color: #fff;
border-bottom: 1px #000 solid;
text-align: center;
text-decoration: none;
color: #000;
}

#navlist a:hover { background-color: orange; }
#navlist a:visited { color: #000; }

Easily done. The next thing you have to consider, though, is how your custom menu is going to interact with the other menu users will see when they’re logged in and looking at their account pages.

The User Menu

The user menu is the menu you’ll see on some pages if you’re logged in. The menu links you to your account summary page (your checkouts, overdues, and holds), your fines, user tags, etc. The user menu, when it appears, will appear underneath the menu you added to OpacNav.

After you’ve added a custom menu, log in to your OPAC and see how it looks on the user pages.

It looks fine, but why not take a few extra steps to integrate it better with the look of the existing menu. I’m going to tweak these properties to help match the user menu:

1. border color
2. margin
3. padding
4. width

Here’s the updated CSS:

#navcontainer {
margin-right:0.5em;
padding-top:1em;
}
#navlist li {
display: inline;
/* for IE5 and IE6 */
}

#navlist {
width: 9em;
/* to display the list horizontaly */
font-family: sans-serif;
margin: 0 0 0 1em;
padding: 0;
border-top: 1px #979797 solid;
border-left: 1px #979797 solid;
border-right: 1px #979797 solid;
}

#navlist a {
width: 99.99%;
/* extend the sensible area to the maximum with IE5 */
display: block;
background-color: #fff;
border-bottom: 1px #979797 solid;
text-align: center;
text-decoration: none;
color: #006699;
}

#navlist a:hover { background-color: #D4E2FF; }

That’s the basics. Browse through the Listamatic site for more ideas. And remember, you’re not limited to just navigation links when you’re customizing OpacNav. You can add any kind of static content. The Rockingham Free Public Library lists their hours. The Polytechnic Institute of NYU’s Bern Dibner Library has a Meebo widget for instant chatting between OPAC user and library staff [edit: At least they used to. 7-15-2010].

It’s a narrow canvas, but it’s open for just about anything you can think of.