Tag Archives: Koha

Showing item type counts on the checkout screen

Does your library limit your patrons to a certain number of checkouts for certain item types? At the Athens County Public Libraries, for instance, we limit patrons to 10 audio books, 10 music CDs, 10 videos, and 5 DVDs at a time. If a patron tries to check out more than 5 DVDs, Koha will show a warning. But what if you want to be able to tell at a glance how many a patron has?

This functionality was available to us in our 2.x installation, but when we upgraded to 3.0 our support company at the time told us it wasn’t a customization they would support. This wasn’t a feature we were willing to give up, so I set out to duplicate it using the tools available to me: system preferences and JavaScript.

Information there for the taking

All the information we need can be found on the patron checkout screen, we just need to figure out how to get it. The page lists all the items checked out to the patron, and it shows the item type for each:

List of items checked out on the checkout screen

With this available to us we can use jQuery to count each instance of each item type. We need to build a count for each item type in our system, so the script isn’t very portable. It looks for table cells (“<td>“) containing the description of each of our item types:

[sourcecode language=”javascript”]

var itypes = {‘circ’: 0, ‘avid’: 0, ‘avbk’: 0, ‘avmu’: 0, ‘advd’:0 };
$(“#issuest td:contains(‘Circulating’)”).each(function(){
itypes[“circ”]++;
});
$(“#issuest td:contains(‘Videos’)”).each(function(){
itypes[“avid”]++;
});
$(“#issuest td:contains(‘DVDs’)”).each(function(){
itypes[“advd”]++;
});
$(“#issuest td:contains(‘Audio Books’)”).each(function(){
itypes[“avbk”]++;
});
$(“#issuest td:contains(‘Music CDs’)”).each(function(){
itypes[“avmu”]++;
});

[/sourcecode]

The script starts by setting up an array of all my item types (“circ,” “avid,” etc.) and giving each a value of zero. Then the script looks for instances of each item type description on the page,  “Circulating,” “Videos,” etc., using jQuery’s :contains selector. Each time it finds an instance of one of those text strings the script increments the count for that item type. At the end of the process the script will have the count for each item type.

Displaying the counts on the page

In order to show the item type counts on the page we need to lay some groundwork by adding some markup. I want to add the count information right after the “Checking out to…” heading, so I’ll find that element’s ID using FireBug and jQuery’s after() function:

[sourcecode language=’javascript’]

$(“#circ_circulation_issue label[for=’barcode’]”).after( … );

[/sourcecode]

The HTML I’m going to add is the default state, so it shows a zero count for everything:

[sourcecode language=’html’]

0 Music CDs out, 10 More Allowed

0 Audio Books out, 10 More Allowed

0 Videos out, 10 More Allowed

0 DVDs out, 5 More Allowed

[/sourcecode]

I’ve  included unique IDs for the “count” spans so that I can easily update them with my script:

[sourcecode language=’javascript’]

$(“#avidout”).html(String(itypes[“avid”]));
$(“#advdout”).html(String(itypes[“advd”]));
$(“#avbkout”).html(String(itypes[“avbk”]));
$(“#avmuout”).html(String(itypes[“avmu”]));

$(“#avidok”).html( 10 – itypes[“avid”] );
$(“#advdok”).html( 5 – itypes[“advd”] );
$(“#avbkok”).html( 10 – itypes[“avbk”] );
$(“#avmuok”).html( 10 – itypes[“avmu”] );

[/sourcecode]

In the first of the two sections above I take the count I got earlier, itypes['avid'] and set the content of the corresponding <span> using the html() function. I also want to show how many more the patron can check out, so I subtract the count from the limits I’ve set in my Koha installation.

If you have patrons who have exceeded their checkout limit you’ll see a problem: The page will tell you they’re allowed to check out a negative number more items. We can correct the script to accommodate:

[sourcecode language=’javascript’]

$(“#avidok”).html((10-itypes[“avid”] > 0) ? 10-itypes[“avid”] : 0);
$(“#advdok”).html((5-itypes[“advd”] > 0) ? 5-itypes[“advd”] : 0);
$(“#avbkok”).html((10-itypes[“avbk”] > 0) ? 10-itypes[“avbk”] : 0);
$(“#avmuok”).html((10-itypes[“avmu”] > 0) ? 10-itypes[“avmu”] : 0);

[/sourcecode]

Final version

Here’s what the results look like:

The final version includes proper escaping of the HTML content and wraps the whole process into a function (“itemTypeCount”). This function will be called on page load only if jQuery finds that the table of checkouts, which has an ID “issuest” is being displayed. The whole script goes into Koha’s intranetuserjs system preference.

[sourcecode language=’javascript’]

function itemTypeCount(){
$(“#circ_circulation_issue label[for=’barcode’]”).after(“

0 Music CDs out, 10 More Allowed

0 Audio Books out, 10 More Allowed

0 Videos out, 10 More Allowed

0 DVDs out, 5 More Allowed

“);

var itypes = {‘circ’: 0, ‘avid’: 0, ‘avbk’: 0, ‘avmu’: 0, ‘advd’:0 };
$(“#issuest td:contains(‘Circulating’)”).each(function(){
itypes[“circ”]++;
});
$(“#issuest td:contains(‘Videos’)”).each(function(){
itypes[“avid”]++;
});
$(“#issuest td:contains(‘DVD’)”).each(function(){
itypes[“advd”]++;
});
$(“#issuest td:contains(‘Audio Books’)”).each(function(){
itypes[“avbk”]++;
});
$(“#issuest td:contains(‘Music CDs’)”).each(function(){
itypes[“avmu”]++;
});
$(“#avidout”).html(String(itypes[“avid”]));
$(“#advdout”).html(String(itypes[“advd”]));
$(“#avbkout”).html(String(itypes[“avbk”]));
$(“#avmuout”).html(String(itypes[“avmu”]));
$(“#avidok”).html((10-itypes[“avid”] > 0) ? 10-itypes[“avid”] : 0);
$(“#advdok”).html((5-itypes[“advd”] > 0) ? 5-itypes[“advd”] : 0);
$(“#avbkok”).html((10-itypes[“avbk”] > 0) ? 10-itypes[“avbk”] : 0);
$(“#avmuok”).html((10-itypes[“avmu”] > 0) ? 10-itypes[“avmu”] : 0);
}
$(document).ready(function(){
if(document.getElementById(“issuest”)){
itemTypeCount();
}
});

[/sourcecode]

Caveats

This system works very well for my library, but it comes with a few caveats:

It requires that you hard-code, in the script, handling for each of your Koha item types.

Besides being tedious, it also requires that you modify the script each time you change your item types.

It requires that you hard-code the correct item type limits.

Also tedious, and requires that you modify the script each time you change your circulation rules.

It creates a potential collision with both call numbers and titles.

If my item type description is “DVD” and my call number includes the text “DVD” as well I’ll get an inaccurate count. If my item type description is “Audio Books” and a patron has checked out a print book entitled Audio Books for long trips I’ll get an inaccurate count.

For us the disadvantages are not unwieldy and the collision problem has never caused a problem. The advantage we get is being able to tell at a glance whether the patron is going to be able to check out that stack of DVDs or whether we need to ask them to put some back. Better to ask them to pick their favorites up front rather than after we’ve already checked out some of them.

Customizing the staff client login logo: Addendum

I left something out of my post on Customizing the staff client login logo that I wanted to be sure to add: Once you’ve changed the logo you may want to change where it links to as well. By default it links to the Koha web site (or the deprecated version if your installation is an older one). We can use a little snippet of jQuery to change that link.

Using jQuery to change the URL to which the staff client logo links

[sourcecode language=’javascript’] $(“#login h1 a”).attr(“href”,”https://www.myacpl.org”);
[/sourcecode]

That looks for an <a> tag inside an <h1> inside <div id="login">, which is specific enough to only catch the login form. This snippet goes inside your intranetuserjs system preference. Assuming the only thing you’ve added to intranetuserjs is the code I covered in the previous post, this would be the revised version:

[sourcecode language=’css’] $(document).ready(function(){
$(“#login h1 a”).attr(“href”,”https://www.myacpl.org”);
});
// ]]>


// <![CDATA[
//

Interface test: Placing a quick hold

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.

Koha bugs workflow

As the Koha project has grown our workflow has evolved to meet the demands of a wider pool of developers. We’re better today at collaborating thanks to Git, our version control system. We’re better at communicating with each other through the Koha wiki and Koha’s Bugzilla database. It has helped a lot that we’ve worked to establish some consistent steps to handle both bugs and new features.

Filing a bug report

When you’ve discovered a bug in Koha the first stop is Bugzilla. Bugzilla is an open-source bug-tracking system developed by the folks who brought you Mozilla Firefox. We have our own installation of Bugzilla, generously hosted on a donated server. Anyone can file a bug, whether you’re a Koha developer or a Koha user.

If you find a bug the first step is to report it. Even a developer intending to immediately fix a bug should file a bug report. Doing so will mean others won’t duplicate your efforts in isolating the bug. When you file a bug report Bugzilla will offer to assign the bug by default to the person who has volunteered for bugs of that category. For instance, I am assigned by default any OPAC bugs. That doesn’t mean I’ll be able to fix them all, but I’m notified of each one and I can always reassign them if I find they’re beyond my capabilities.

You can also assign the bug a “severity” setting. If you’re not sure, use the “normal” severity for bugs, and “enhancement” if you’re asking for a feature to be added. There are brief descriptions of Bugzilla’s severity levels for review if you’re not sure how to classify something.

There are much more detailed bug reporting guidelines on the Koha Wiki.

Now the bug is in the database. With any luck, anyone else who discovers the same bug will search Bugzilla first before reporting it. If you find an existing report for a bug you’re experiencing, review it to make sure all the pertinent details are there. Feel free to leave comments expressing in specific terms how the bug is affecting your library’s workflow. Understanding the impact of a bug might help others prioritize efforts to fix it.

What happens to your bug?

What happens to a bug report after it gets filed? If the report was filed without any plans to address it (that is, if you’re not a developer filing the bug, with plans to fix it right away), nothing may happen for a while. Ideally the default assignee of the bug will review it and take some action if necessary: Correcting the bug’s severity, asking clarifying questions, reassigning if necessary. Unfortunately there is no guarantee that anything will happen with a bug report once it is filed. If no one else is affected by (or cares about) the bug, there won’t be any incentive to fix it. Developers are often working on projects assigned to them by their customers, and if they’re not getting paid to fix a particular bug they may not choose to work on it.

Your bug finds acceptance

If someone decides to work on your bug report, the first thing they should do is “accept” the bug in Bugzilla. If the bug isn’t already assigned to them, they edit the bug to assign it to themselves and update the status of the bug from “New,” the default for all new bugs, to “Assigned.” This tells anyone browsing Bugzilla that someone has agreed to work on the bug. Careful use of bug assignment and the use of the “assigned” status helps prevent duplication of effort: I won’t spend time working on a bug if I think someone else is actively working on it already.

If the developer who took on your bug discovers a fix for it, the next step is to submit a patch. A patch is a special file which can be understood by our version control system. Just as a patch on a piece of clothing is just a small piece of cloth to fix a hole, a software patch is just a small piece of code which can be applied to a whole file (or even multiple files). The patch includes instructions to add certain lines or remove certain lines of code.

The developer who has come up with a patch will do two things with it: First, the patch gets submitted to a special Koha mailing list for all Koha patches. Koha’s Release Manager monitors this list and evaluates each patch and evaluates it for inclusion in the next version of Koha. The second place the patch will go is into the Bugzilla bug report. The developer will attach the patch to the bug report so that others can see that a patch was submitted and maybe review the patch themselves. Since the patch file is easily understood by the Git version control system, anyone running an installation of Koha from a Git repository can apply patches and test bug fixes. A bug in Bugzilla which has has a patch filed for it will be marked with a special priority, “PATCH-sent.”

Your bug found acceptance, but what about the patch?

Galen Charlton, the Koha 3.2 Release Manager, has the task of evaluating each patch that is submitted for inclusion in 3.2. He reviews patches, tests them, and approves them if he finds them worthwhile. If a patch refers to a specific bug report, Galen will usually also update the bug report with a note that the patch was “pushed.” If a patch doesn’t seem to work, or if it includes mistakes which should be corrected before inclusion he will let the patch submitter know so they can rework the patch.

Right now we’re getting so close to the release of 3.2 that we’re under both a “feature freeze” and a “string freeze.” A feature freeze means that no new features are being accepted for inclusion in 3.2: only bug-fixes. Rejecting new features at this point in the process reduces the possibility that major new bugs will be introduced. The “string freeze” means that patches submitted for inclusion in 3.2 should no include changes to any text in the interface. These text strings must be painstakingly translated. The Koha translation-tracking system Pootle lists 63 different languages which have at least begun to have translations done. Putting on a string freeze means that translators preparing for the release of 3.2 will have a fixed target.

The patch for your bug made the cut. It’s going into 3.2!

You reported the bug, so your job isn’t done yet. It’s time to test the fix. Update your test installation and try to follow the same steps that led to the bug before. Is the bug still there, or is something still left undone? Then update the bug and explain what you found.

On the other hand, if you find the bug has been fixed then you can mark it as such in Bugzilla. Change the status of the bug from “Assigned” to “Resolved (Fixed).”

Congratulations, and welcome to the team.

Bean counting

One of the many things I love about Koha is the easy access I have to statistics. I’m a do-it-yourselfer, so I seldom use Koha’s built-in reports. Instead I go directly to the source: Koha’s statistics table.

Field Type Null Key Default Extra
datetime datetime YES MUL NULL
branch varchar(10) YES NULL
proccode varchar(4) YES NULL
value double(16,4) YES NULL
type varchar(16) YES NULL
other mediumtext YES NULL
usercode varchar(10) YES NULL
itemnumber int(11) YES NULL
itemtype varchar(10) YES NULL
borrowernumber int(11) YES NULL
associatedborrower int(11) YES NULL

The statistics table is long-term memory storage for circulation transactions: checkouts, check-ins, renewals, and payments. The kind of reports we depend on most are circulation reports, so I usually focus on checkouts and renewals.

Just a few of these fields are relevant to most of my circulation reports:

  • datetime stores the date and time of the transaction.
  • branch stores the three-letter code for the branch where the transaction took place.
  • type records whether the statistic is a checkout (“issue”), check-in (“return”), renewal (“renew”), payment (“payment”), or write-off (“writeoff”).
  • itemnumber, which records the id of the item in Koha’s catalog.

Using these pieces we can put together a query which counts circulations per branch for a given month:
[sourcecode language=”SQL”] SELECT branch,count(*) FROM statistics WHERE year(datetime) = 2009 AND month(datetime) = 12 AND (type = ‘issue’ OR type = ‘renew’) GROUP BY branch ORDER BY branch;
[/sourcecode]

branch count(*)
ALB 2762
APL 21475
COV 1746
CPL 616
GPL 2725
NPL 5475
PPL 5391

7 rows in set (37.16 sec)

One important thing to note about the results of that query: It took over thirty-seven seconds to execute. That’s ages in MySQL terms, and a cause for caution. We’ve been using Koha since 2003, so our statistics table is huge: almost nine million rows. For that reason I don’t run my statistics queries directly on our production Koha server. I back up the statistics table to a separate database where it won’t interfere with the performance of our Koha operations.

Getting fancy

Querying MySQL directly can get you many of the numbers you want, but if you want to aggregate data and manipulate it in fun ways you have to add a scripting layer to the process. For Koha that’s Perl, for me it’s PHP. The end result that I want to share is a report of circulations per month for all branches. This report shows not just the raw numbers from Koha but also formats them as a graph using Google’s Chart API.

This was just a quick look at the kind of work I’ve been doing recently. There are a lot of pieces of the puzzle that I’ve glossed over. I hope at the very least it’s an interesting glimpse of what is possible when you have easy access to your data and the tools to manipulate it.