Koha Blog

The Athens County Public Libraries have been using Koha 3 since February 2009. Since that time there has been a feature available to patrons which hasn’t really been used: tags.

The Koha 3 OPAC offers feature where users can “Tag” records with keywords. Tags are generally used as a sort of user-generated subject heading, sometimes called a “folksonomy” because it’s a taxonomy created by regular folks.

Some might be familiar with two sites which were among the first popularize the idea of tags: Flickr.com and Del.icio.us. We used Flickr recently to share pictures of the Wells library reconstruction following a fire in June 2008.

Flickr tags list

If you browse around Flickr you’ll find that on each photo page there is a list of keywords found in the right column, labeled “Tags.” Take a look at one example, a picture of the New York Public library. The photo has been tagged with “New York City,” “Spring Break,” “vacation,” “Manhattan,” “New York Public Library,” and “architecture.” If you click on one of those tags,  you’ll see all the other photos by that user which were tagged with the same keyword. Then you can click the link to “See all public content tagged with newyorkcity”

The nice thing about tagging is you don’t have to pick from a preselected set of categories. As you can see from the above example, you can categorize things not just by what they are in and of themselves, but what they are to you. The picture must have been taken during Spring Break vacation, and the user tagged it that way so that he could find all those vacation pictures at once.

Del.icio.us is a “social bookmarking” site. After creating a free account you can bookmark sites for later use, and add tags to help categorize them. Take a look at one of the other common features of systems which allow tagging: the tag cloud.

A tag cloud is both a menu and a visual representation of all the tags (or at least the most popular tags) in a system. In the Delicious example, “blog” and “design” are the largest terms in the list because they’re the most popular (with 6,769,771and 9,195,968 entries each, respectively!).

Koha 3 has this same functionality. If a non-logged-in user pulls up the details of a record in the OPAC, they’ll see “No tags from this library for this title. Log in to add tags.”

No tags yet!

Tags in the OPAC have have critical, practical difference from tags on Flickr or Delicious: tags aren’t being used to categorize user-generated content. On Flickr, the user has a vested interest in tagging photos as they’re created, because it will help them keep track of their photos in the long run.

In the OPAC, records are created by catalogers, and patrons are accustomed to using standard methods (e.g. keyword searches) for finding them. I’m not sure what would motivate an OPAC user to take an active role in tagging items. The example I used of a book for which the “official” category didn’t match the user’s understood category is the one I would think would be most common.

Is that enough? For tags to be beneficial not just to the individual but to the general audience of OPAC users, the pool of existing tags may have to reach “critical mass.” Users clicking through to the tag cloud are sure to lose interest fast when they see nothing! I’m hoping to enlist the staff here to brainstorm about some useful tags and maybe get the ball rolling.

Have you ever been unable to find something in the library because it was categorized differently than you expected?

Koha uses the Yahoo! UI Library Grids CSS framework for both the OPAC and the staff client. When we revamped the Koha interface for 3.0 the Grids framework was chosen because it would simply the process of structuring pages while giving us a pretty good selection of possible layouts.

A nice feature of the Grids framework is that you can control the layout of your page with relatively minor changes in markup. Here’s an example for one of the basic layouts:

<div id="doc">
<div id="bd">

<div id="yui-main">
<div class="yui-b">
<p>Main Content</p>
</div>
</div>

<div class="yui-b">
<p>Sidebar</p>
</div>

</div>
</div>

You can see that YUI’s Grids framework suffers from the same problem a lot of CSS frameworks  have: the class names are pretty nonsensical if you’re not used to them. I consider this to be par for the course: Better that they be nonsensical than have semantic-sounding names which aren’t appropriate for your actual page structure.

How does the framework make it easy for us to change page layouts? I’ve put together a simple example. This example uses JavaScript to swap out one class name. Try it and see how much can change based on one class name:

Click to try the demo

The above example shows how the “primary” page structure can be changed. I say primary because you can only choose one of those layouts at a time. If you want to have additional columns or blocks within that layout you can use “grids” and “units” within that main page structure:

Just like with the page structure, there is a set of pre-defined grid structures you can use within your page. The simplest is a set of two equal-width containers:

<div id="doc">
<div id="bd">
<div class="yui-g">

<div class="yui-u first">
<p>First grid unit</p>
</div>

<div class="yui-u">
<p>Second grid unit</p>
</div>

</div>
</div>
</div>

Just like with the page structure example, a change to the grid’s class name can affect the layout of the units within it. Notice that the grid/unit structure is changing within the page structure we defined before: a single main block with a left-hand sidebar:

Click the try the demo

The power of the framework’s grid/unit structure really comes into play when you start nesting grids within grids. Start with a grid which creates two equal columns, and then nest the same two-column grid within each of those columns:

<div id="doc">
<div id="bd">
<div class="yui-g">

<div class="yui-g first">

<div class="yui-u first">
<p>Unit one, sub-unit one</p>
</div>
<div class="yui-u">
<p>Unit one, sub-unit two</p>
</div>
</div>

<div class="yui-g">

<div class="yui-u first">
<p>Unit two, sub-unit one</p>
</div>
<div class="yui-u first">
<p>Unit two, sub-unit two</p>
</div>
</div>
</div>

</div>
</div>

In the markup above, instead of nesting a unit (‘<div class=”yui-u”>’) inside a grid (‘<div class=”yui-g”>’), we’re nesting a grid inside a grid. The containing grid can still be altered to change the layout of the units inside it:

Click to try demo

The Koha OPAC’s grid structure

How is this implemented in the Koha OPAC? Koha has to take advantage of  the Grids framework’s flexibility when obeying different conditions in the OPAC. Take, for example, the main page of the OPAC. There are four possible layouts the user might see based on state and system preferences:

No OpacNav, not logged in

No OpacNav, logged in

OpacNav, not logged in

OpacNav, logged in

Using some logic in the Koha templates, the layout can be easily altered based on each of those conditions. And because the Grids framework makes it so easy to switch between those different layouts, the template can be much simpler:

<!-- TMPL_IF NAME="OpacNav" -->
<div id="doc3" class="yui-t1">
<!-- TMPL_ELSE -->
<div id="doc3" class="yui-t7">
<!-- /TMPL_IF -->

The template logic can check one condition (whether the OpacNav system preference is populated) and alter the page layout accordingly.

What does this mean to me?

Unless you’re hacking Koha templates you won’t many opportunities to build your own grids. However, there are a couple of instance where you might want to try it, and I’ll talk about that in my next post.

One of the nice things about using an open, web-based OPAC is it’s really easy to share and reuse links to stuff in your catalog. One great way to promote aspects of your collection is to share a link to a specific search. The Athens County Public Libraries do this with a button on our OPAC. Try it:

When you click that image you’re taken straight to search results for new DVDs. We didn’t have to create a new collection code or shelving location, we just use built-in options for performing advanced searches. Here are the steps we took to come up with that result set:

1. Go to the advanced search page.
2. Check boxes to limit the search to DVD collection codes.
3. Choose Sort by: Dates -> Acquisition Date: Newest to Oldest.
4. Search.

The URL of the search results page is the one to copy and re-use.

The “Newest to Oldest” search guarantees that the most recently added items are at the top of the list. True, this isn’t as fine-grained as a search that would let us put in a specific date range (“DVDs acquired in the last 7 days”). And it may not meet every patron’s expectations because it shows returns recently acquired items, meaning if you add a new copy to an existing record it will show up in those results. But for patrons hungry for the newest DVDs it will works very well.

The nice thing about promoting your collection this way is that you don’t have to maintain a hand-picked list. Want to promote the anniversary of the moon landing? How about a link to a search for the subject “manned space flight?” It’s a great quick way to draw your users into the catalog with timely, topical points of interest.

If you like my “new DVDs” image, you’re welcome to use it. It uses a DVD icon found on Wikimedia Commons. Here are a couple additional choices:

You might want the above image if you’re using the “Bridge” icon set in your OPAC already.

The above image uses a modified version of an icon from the Tango Icon Library. Check out the other Bridge and Tango icons for more choices that might inspire your own material-specific promotions.

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">
<input type="hidden" value="opac" name="koha_login_context"/>
<label for="userid">Login:</label><input type="text" name="userid" id="userid"/>
<label for="password">Password:</label><input type="password" name="password" id="password"/>
<input type="submit" value="Log In"/>
</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">
<input type="hidden" value="intranet" name="koha_login_context"/>
<label for="userid">Username:</label><input type="text" id="userid" name="userid"/>
<label for="password">Password:</label><input type="password" id="password" name="password"/>
<input type="submit" value="Log in" />
</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.

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. [Edit: The link no longer works, sorry.]

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!