A quick Firebug tip for editing CSS

September 19th, 2014

I’ve talked before about Firebug’s inspector tool for examining the markup of a page and its associated style. When you inspect a particular element in the markup you can see the CSS rules that have been applied to it. But what if the styles applied to an element change based on user interaction? How do you “catch” the style of a hover interaction, or of an element which has focus?

For instance: In the Koha staff client there is a global style for the color of a link when you hover your cursor over it.

Koha link color on hover

This color is defined in the staff client’s main CSS file, staff-global.css:

a:hover, a:active {
    color : #538200;
    text-decoration: none;
}

However, if you use Firebug’s inspector to examine a link you won’t see that CSS:

Inspecting a link in the staff client

That’s because the Firebug inspector isn’t showing you the “hover” state of the link–at least not unless you’re mouse cursor is hovering over the link at the time:

Inspecting the link on hover

But what if we want to use Firebug’s Style tab to live-edit the CSS of the hover state? As soon as we move our mouse away from the link the hover state disappears from the style pane, so we can’t edit it. Luckily Firebug has an option built in for “activating” three different interaction states: Hover, Active, and Focus:

Firebug Style tab interaction options

By selecting “:hover” we can “pin” the hover state to keep it activated so that we can inspect and change it:

Edit the hover style in Firebug

We can test the “focus” option by inspecting the style of any standard text input in Koha, for example the barcode field on the check-in page:

Inspecting an element's :focus state in Firebug

This lets us see that there is a CSS rule defining a default border style for <input> and <textarea>

input:focus, textarea:focus {
    border-color: #538200;
    border-radius: 4px;
    border-style: solid;
}

And from there we can customize away:

input:focus {
    border-top: 5px solid #EF5959;
    border-bottom: 5px solid #FF975F;
    background-image: -webkit-gradient(linear, 0 0, 0 100%, from(#EF5959), to(#FF975F));
    background-image: -webkit-linear-gradient(#EF5959, #FF975F);
    background-image: -moz-linear-gradient(#EF5959, #FF975F),
-moz-linear-gradient(#EF5959, #FF975F);
    background-image: -o-linear-gradient(#EF5959, #FF975F),
-o-linear-gradient(#EF5959, #FF975F);
    background-image: linear-gradient(#EF5959, #FF975F),
linear-gradient(#EF5959, #FF975F);
-moz-background-size:5px 100%;
    background-size:5px 100%;
    background-position:0 0, 100% 0;
    background-repeat:no-repeat;
    border-width: 5px 0;
    padding: 5px;
}

A custom input border

A New OPAC Theme: Bootstrap

March 6th, 2014

As of Koha 3.14 the OPAC has a new default theme: Bootstrap. It’s a theme I developed with the intention of offering a flexible, modern, and responsive theme option for Koha libraries. It takes as its visual basis the CCSR theme, added in 3.10. However, it greatly expands the catalog’s mobile-friendliness over the CCSR theme.

The Bootstrap theme is so named because it uses the Bootstrap framework, a set of JavaScript and Cascading Style Sheet tools for use by web developers to quickly and easily add functionality to sites. Bootstrap helps web developers do things like add menus, dialogs, tooltips, etc. Bootstrap also brings some improved default styling to buttons and forms.

Like the CCSR theme, the Bootstrap CSS framework offers something called responsiveness. This means that when the size of your viewport (for instance, the browser window) changes, the layout of the page changes in response. With a desktop browser you can see this by resizing the browser window. Users with mobile devices of varying sizes will see a layout more closely tailored to the size of the screen on their device.

In the CCSR theme there is only one breakpoint. Breakpoints are the pixel dimensions at which the layout changes. When browsing a catalog which uses the CCSR theme, if the viewport size is below 700 pixels the layout changes to accommodate the smaller screen.

Bootstrap offers a few more breakpoints. If you’re reading this in a desktop browser you can view this demo page and resize your browser window to see the effects on the page layout. In Bootstrap there are three primary breakpoints, for large, medium, and small screens.

Koha’s new Bootstrap theme expands on these default breakpoints by adding a few more which are tuned to the layout of the OPAC.

Customization

The Bootstrap theme was designed to be just as flexible for customization as the old default theme. All the customizable regions are there. The same options are available for adding custom CSS and JavaScript. However, the responsive nature of the theme adds some new complications.

If you’re adding content to a region like opacheader or OpacMainUserBlock you’ll need to keep in mind that your content should respond comfortably to the same range of breakpoints that the rest of the catalog does. If you’re simply adding text this isn’t a problem because text flows naturally no matter the page width. If you’re adding something more complicated like images or navigation menus it will require some additional testing.

If you find your custom content is not flowing nicely at multiple screen sizes you can try tailoring that content with CSS using the same major breakpoints which are built into the Bootstrap theme:

@media only screen and (min-width: 0px) and (max-width: 390px){
/* Screens bewteen 0 and 390 pixels wide */
/* Add custom CSS here */
}
@media only screen and (min-width: 342px) and (max-width: 479px) {
/* Screens bewteen 342 and 479 pixels wide */
/* Add custom CSS here */
}
@media only screen and (min-width: 480px) and (max-width: 608px) {
/* Screens between 480 and 608 pixels wide */
/* Add custom CSS here */
}
@media only screen and (min-width: 608px) and (max-width: 767px) {
/* Screens between 608 and 767 pixels wide */
/* Add custom CSS here */
}
@media only screen and (min-width: 768px) and (max-width: 984px) {
/* Screens between 768 and 984 pixels wide */
/* Add custom CSS here */
}
@media only screen and (min-width: 984px) {
/* Screens above 969 pixels wide */
/* Add custom CSS here */
}

If you would like to get visual feedback in the Bootstrap OPAC about which media queries are being applied, add this HTML to the opacheader system preference:

<div id="oh"></div>

Some examples

One of the more common items to customize in the previous default OPAC theme was the logo. My first post here was on Customizing Koha 3’s OPAC logo. The Bootstrap theme no longer has an area designed specifically for a logo. The main search bar area takes up the full width of the screen. This makes it more adaptable to various screen sizes.

opac-main-search-bar-full

There is a Koha logo in the “nav bar” region at the very top of the screen which could be customized using CSS, but it’s quite small and disappears at narrower screen widths.

The opacheader region (customizable via system preferences) will probably be the primary customization option for adding logos, banners, custom top-level navigation, etc.

Image banner

A simple option is to add an image to the opacheader region. This is a simple option because the built-in CSS for images allows an image banner to naturally resize to match the browser width. This method uses the browser’s built-in image resizing algorithm.

In your opacheader system preference:

<img alt="Your Library Name" src="http://yourlibrary.example.com/path/to/your/image.png" />

The result is fully-adaptable to various screen sizes.

Tabbed navigation

As an example of some  custom content which might require more complex CSS customization at varying screen sizes let’s look at an example with tabbed navigation.  Here’s the code we’ll start with:

In OPACUserCSS

#opacheader {
padding : 10px 10px 0 10px;
border-bottom : 1px solid #666;
}
#opacheader ul {
margin-bottom : 0;
}
#opacheader li {
display: inline;
}
#opacheader li a {
font-size: 125%;
display: inline-block;
border : 1px solid #666;
border-bottom-width: 0;
padding : 5px 15px 5px 15px;
background-color : #FFF;
border-radius : 5px 5px 0 0;
}

In opacheader:

<ul>
<li><a href="#">About</a></li>
<li><a href="#">Services</a></li>
<li><a href="#">Collections</a></li>
<li><a href="#">Research</a></li>
<li><a href="#">Events</a></li>
</ul>

At the default browser font size/zoom setting these tabs work with a viewport width down to about 607 pixels wide:

opac-header-tabs-607

Below that width the tabs start to wrap in an awkward way:

opac-header-tabs-319

Here’s where the use of CSS media queries can help us out. Let’s say we determine that the layout breaks at 600 pixels wide (a browser extension like Web Developer Toolbar can help us find the correct number). Let’s write a media query which targets a browser window which is narrower than 600 pixels wide:

@media only screen and (max-width: 600px) {
/* Screens below pixels wide */
#opacheader {
text-align : center;
}
#opacheader li a {
font-size : 110%;
border-bottom-width : 1px;
border-radius: 5px;
margin : 4px;
}
}

We append that CSS to the CSS already in OPACUserCSS and test:

opac-header-tabs-responsive-352

Now the tabs are styled one way when the screen width is above 600 pixels, and another when the width is below 600 pixels.

I hope this example gives you a sense of what is possible when it comes to customization in the new theme. Planning your customizations for more than one screen width can be time-consuming, and lots of trial and error will be involved. The outcome, however, is a site which will be much more broadly usable.

Customizing the display of online resources like eBooks

April 10th, 2013

The Athens County Public Libraries are members of the Ohio eBook Project Ohio Digital Library, a consortium of libraries who contribute to and share access to a collection of eBooks and other downloadable material through OverDrive. In order to make these resources more discoverable by our patrons we add MARC records for these titles to Koha.

When we started doing this we felt that it was important for the patrons to be able to tell very easily that the title they saw in search results was an electronic resource they could download. We already have many records in our catalog for web sites. We were concerned that these two types of resources would be difficult to distinguish.

Electronic resource in search results

An electronic resource in default OPAC search results

Since Koha gives us the ability to inject custom JavaScript into our OPAC, a JS-based solution seemed like the best option. The goal was to be able to use JS to examine each search result and look for a clue that any particular result was an Ohio eBook Project record. Luckily all the OEP records have something in common: A URL (stored in the MARC 856u) beginning with “http://ohdbks.” Here’s the JavaScript I came up with:

$("#userresults").ready(function(){
$("#userresults table td").each(function(i){
td = $(this);
var ohdbks_link = td.find("a[href^='http://ohdbks']");
var linkc = ohdbks_link.parent();
var ohdbks_link = ohdbks_link.attr("href");
if(ohdbks_link){
$("td:eq("+i+") span.availability,td:eq("+i+") span.actions").hide();
linkc.html('<a class="ebook" href="'+ohdbks_link+'">Check the Ohio e-Book Project for availability</a>');
}
});
});

Stepping through this code:

  1. The script is triggered when #userresults is ready.
  2. We loop through each td within the table inside #userresults, storing the index of each iteration as i.
  3. The matched td is stored as a variable for easy reference.
  4. The script finds an anchor tag which matches the string we’re looking for and stores that in a variable.
  5. We want to refer later to the <a> tag’s parent container, so we use jQuery’s parent() to store that as linkc.
  6. We pull the href attribute value for the previously select <a> tag.
  7. If an href was found…
  8. …hide the availability and “actions” (“Place hold,” “Add to cart”, etc.) elements which we don’t consider relevant to e-resource records.
  9. Replace the contents of the original anchor tag’s container with new html which uses the previously-saved href attribute but changes the text of the link and adds a special CSS class.

We chose to label each eBook link “Check the Ohio Digital Library for availability” because Koha has no way of knowing whether a particular title is checked out. The link is styled by CSS added to Koha’s OPACUserCSS system preference:

a.ebook {
background: url("http://www.myacpl.org/files/image/opac-results-download-ebook.png") no-repeat scroll 5px 5px transparent;
border: 1px solid #8BC45C;
border-radius: 5px 5px 5px 5px;
font-size: 135%;
font-weight: bold;
line-height: 175%;
padding: 4px 4px 4px 25px;
text-decoration: none;
}

The result:

Electronic resource in customized search results

An electronic resource in customized OPAC search results

Electronic resource detail page

When the patron clicks to view more information about one of those electronic resource titles they come to a detail page which presents additional opportunities to simplify the display for this type of record.

Since this kind of title is available only through the Ohio Digital Library web site we don’t actually have any local holdings, but when we add MARC records for these resources we include a dummy item to which we can attach some additional information. One reason for this is to be able to have a searchable collection code attached to each record. But showing holdings information to the patron isn’t very useful because none of it is relevant:

Holdings information displayed by default for electronic resources

Holdings information displayed by default for electronic resources

Another aspect of the detail page which is less than ideal is that the link to the Ohio Digital Library is pretty well hidden in the other details about the title like publisher, subject headings, etc. We again turned to JavaScript to solve both of these problems at once:

$("span.online_resources").ready(function(){
var ohdbks_link = $("span.online_resources a[href^='http://ohdbks']").attr("href");
if(ohdbks_link){
$("#holdings").html('<a href="'+ohdbks_link+'"><img src="http://www.myacpl.org/files/image/opac-download-ebook.png" alt="Check the Ohio e-Book Project for availability" /></a>');
}
});

This code is very similar to what we used on the search results page, but a little simpler.

  1. Again we trigger this function when this particular area of the page (“span.online_resources”) has completed loading.
  2. We find the link to the Ohio eBook Project download page and store the href attribute.
  3. If an href was found…
  4. Replace the holdings table (identified by the ID #holdings) with an image which links to the OEP download page.

In four lines of JavaScript both goals are accomplished: The meaningless holdings table is gone, and a prominent link is added to the Ohio eBook Project download page for the title the patron is looking at.

Here’s the result:

A customized link to the electronic resource download page

A customized link to the electronic resource download page

Cart and Lists buttons revisited

March 28th, 2012

It’s been almost three years since I wrote Colorizing the Cart and Lists buttons. My conclusion then was that we needed a fairly complex combination of markup, CSS, and background images to create the appearance of the buttons.

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.

The time has come for the simpler version. My patch for Koha bug 7584, “Update cart and lists buttons style using CSS3 features” has just appeared in Koha’s master branch, the development version which precedes an official release.

What has changed? Firefox, Safari, and Chrome have had updates since then, which has at the very least expanded the number of users of those browsers who are on a more recent version. Opera, one of the holdbacks in 2009, now supports the features required. Internet Explorer 6, 7, and 8 still linger of course, but Internet Explorer 9 is available now. IE9 offers better support for the features we need.

For me what has changed is that I now think that Koha should be a little more aggressive about taking advantage of the features of up to date browsers even if that means the experience isn’t the same for users of older browsers.

The new style

Let’s take a look at the revised markup. Where the previous version needed a lot of extra elements (<i>, <span>, etc) the new version doesn’t:


<a id="cartmenulink" href="#">Cart</a>

<a id="listsmenulink" href="#">Lists</a>

I’ll quote the relevant declarations from the CSS. First, both buttons are assigned rounded corners:


#cartmenulink, #listsmenulink {
-webkit-border-radius: 5px;
-moz-border-radius: 5px;
border-radius: 5px;
}

Notice the variations: “-webkit-border-radius” is specific to Chrome and Safari. “-moz-border-radius” is specific to Mozilla-based browsers like Firefox. When we specify a single value like “5px” the value is applied equally to all four corners. You can also specify different values:


#cartmenulink, #listsmenulink {
-webkit-border-radius: 4px 15px 4px 15px;
-moz-border-radius: 4px 15px 4px 15px;
border-radius: 4px 15px 4px 15px;
}

The values are applied clockwise starting with the upper left-hand corner.

Background Gradients

The other primary aspect of the buttons are their background colors. Previously we used a transparent image to give the button background a gradient. With CSS3 we can specify the gradient values right in our CSS. The easiest way to accomplish this is using the Ultimate CSS Gradient Generator.

A web-based tool for designing CSS gradients

With the CSS Gradient Generator you can use the visual tools for creating a gradient and the CSS will be generated for you. It generates CSS declarations specific to several major browser versions including Internet Explorer. There is even an option to upload a gradient image and have the Generator automatically match the colors.

Here’s the gradient CSS for the Cart button:


#cartmenulink {
background: #98CB58; /* Old browsers */
background: url("../../images/cart.gif"),-moz-linear-gradient(top, #d5eaba 0%, #b7db8a 50%, #98cb59 100%); /* FF3.6+ */
background: url("../../images/cart.gif"),-webkit-gradient(linear, left top, left bottom, color-stop(0%,#d5eaba), color-stop(50%,#b7db8a), color-stop(100%,#98cb59)); /* Chrome,Safari4+ */
background: url("../../images/cart.gif"),-webkit-linear-gradient(top, #d5eaba 0%,#b7db8a 50%,#98cb59 100%); /* Chrome10+,Safari5.1+ */
background: url("../../images/cart.gif"),-o-linear-gradient(top, #d5eaba 0%,#b7db8a 50%,#98cb59 100%); /* Opera 11.10+ */
background: url("../../images/cart.gif"),-ms-linear-gradient(top, #d5eaba 0%,#b7db8a 50%,#98cb59 100%); /* IE10+ */
background: url("../../images/cart.gif"),linear-gradient(top, #d5eaba 0%,#b7db8a 50%,#98cb59 100%); /* W3C */
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#d5eaba', endColorstr='#98cb59',GradientType=0 ); /* IE6-9 */

}

Eight lines of CSS each doing the same thing for different browsers, starting with a solid background color for browsers which don’t support CSS3. This is the same kind of code which will be generated by the CSS Gradient Generator with one exception: The OPAC CSS also includes a background image for the Cart button in order to display the little cart icon.

There’s more to the styling of the buttons than rounded corners and background-gradients, but nothing which we haven’t seen before. Fire up Firebug (or your favorite browser’s DOM inspection tool) and inspect the buttons for more information.

What have we gained?

Just looking at the HTML markup it would seem we’ve gained a lot of efficiency over the <span>-heavy buttons in the older version. But the multiple lines of CSS more than make up for it. What advantages does the new design offer? Importantly, flexibility. We don’t have to create custom-colored 24-bit transparent images when changing the background color of the search bar. We can make all our changes, including changes to the Cart icon, right in the CSS. Border color, border radius, background-color (or gradient), it’s now 100% CSS and can be affected by a custom stylesheet or by changes to the OPACUserCSS system preference.

This change is going to require some revisions if your library has existing CSS customizations to these areas of the OPAC, but I think going forward these changes are going to prove to be beneficial to those seeking to customize their OPAC’s appearance.

jQueryUI and Koha

November 8th, 2011

There’s another project I’ve been working on for almost as long as I haven’t posted to this blog: Incorporating the jQueryUI JavaScript library into Koha. This change would replace the YUI Library which currently powers such interface widgets as buttons, menus, and autocomplete.

When I helped develop the new templates for Koha 3.0 I evaluated several different options for creating some application-like interactions in the Koha staff client including YUI , Ext JS, and similar jQuery plugins. The goal was to have options for creating cross-platform, cross-browser interface widgets. After much testing I settled on YUI. Though I found its syntax difficult to work with, the results worked well and seemed robust. The most visible example of YUI is in the staff client interface, where “toolbars” appear on most pages for displaying actions:

 YUI also drives some autocomplete form fields in the staff client and menus in the OPAC.

In addition to YUI, Koha uses the jQuery JavaScript library and some jQuery plugins like Tablesorter and a pre-jQueryUI version of  Tabs. Since the release of Koha 3.0 over three years ago a lot has changed with these projects. The YUI library released version 3 with enough syntax changes to make an upgrade mean totally rewriting our existing YUI code. At the same time the jQueryUI library made great advances, adding a lot of the same functionality for which we depended on the YUI library.

In November 2010 BibLibre founder and CEO Paul Poulain proposed getting rid of YUI in favor of jQueryUI and the response on the Koha developer’s list was positive. Shortly after I filed a bug, Replace YUI JS libraries with Jquery UI and began working on a branch to do just that.

Since then I’ve gotten two major components migrated from YUI to jQueryUI: tabs and autocomplete. Here’s an example of jQueryUI tabs in the OPAC:

Here are the search tabs in the staff client:

And here’s autocomplete in action in the staff client:

As part of this project I have also replaced the calendar widget we have been using with Koha. Since that widget was added to Koha it stopped being open source, so it makes sense to abandon it in favor of functionality built into jQueryUI.

Calendar pop-up on the check-out screen

Also on my list of things to implement is a replacement of the modal window system used in some places in Koha, for which we’re currently using a standalone JS plugin. This can be eliminated in favor of the jQueryUI-native Dialog widget.

Unfortunately we are still waiting for one element for which we depend on YUI which jQueryUI lacks: A menu widget. Their menu widget has been in alpha stage for almost as long as I’ve been working on this jQueryUI branch. Without it we can’t reproduce the toolbars we build now in YUI. For this reason my work has been stalled for a while. I’m keeping my branch up to date and in sync with the master branch, and I’m keeping my eye on the status of the menu widget.

I’m frustrated with the wait, but I’m also excited about the improvements we’ll be able to make to the Koha interface once jQueryUI is our standard go-to library.

An update on Recent Comments

November 8th, 2011

It’s been far too long since my last post. I’m happy to say that my Recent Comments feature didn’t take quite so long to get incorporated into Koha, although it wasn’t until recently that it was obvious it was there. The page itself made it into Koha in a commit in December 2010, and was in Koha 3.2.3. What it lacked was a link in the interface pointing to the page, so you had to know where it was to get to it. This problem was fixed in a commit in October of this year which adds a new system preference, , which controls whether a link to the recent comments view should appear in the OPAC’s search bar. The option will be available to users of Koha 3.6.

A long an roundabout path, but hopefully a useful feature.

Proposed feature: A recent comments view in the OPAC

October 1st, 2010

Koha’s OPAC has a feature which lets logged-in users leave comments about records in your catalog. This feature was originally branded as “Reviews,” but was changed to “Comments” in order to align it with the familiar feature allowing users to comment on content in blogs, on YouTube, etc. If you haven’t seen it before, here’s what it looks like to a logged-in user:

A catalog record with comments

If you visit the Athens County Public Library catalog you’ll find that comments are enabled, but few users have taken advantage of the feature. I’ve often wondered what we could do to encourage people to add their comments, and one of the ideas I had was to feature recent comments–perhaps on the OPAC or library web site home page.

I’m not an experienced Perl programmer. Most of the changes I make to Koha’s Perl code are minor or cut-and-paste. Adding a feature as unformed as a recent comments view was a little daunting, but I think it turned out well, and I hope I did it right! I’m quite pleased with the result:

Recent comments

The page shows the latest comments added to any title in the catalog in descending order by date. The page also offers an RSS feed of recent comments. This offers two benefits: First, patron can subscribe to recent comments if they want to find out what others are talking about; and second, the library can use that feed to pull content into their own web site. If my library site’s content management system can process an RSS feed, I can add those recent comments on my library’s web site too.

Of course it’s too late in the development cycle for this feature to make it into 3.2, but I hope it will arrive with 3.4.

A collaborative process

There’s one more thing I wanted to share about the development of this little feature: When I was creating the RSS feed I was testing it with the W3C’s feed validator to make sure I had constructed the markup for the feed correctly. The only error I didn’t know how to fix was one with date-formatting. The validator told me I needed to  format my date according to RFC 822, but Koha didn’t include a way to format dates that way. I put out a plea on the Koha IRC channel which was answered by Chris Nighswonger. He very generously added the code I needed and I was able to include a valid RSS feed.

This anecdote shows the very best kind of interaction possible when you work with an open community of developers. I’m not suggesting that in the Koha world all one has to do is ask and free code will be provided. But sometimes you catch someone at the right moment, or the challenge appeals to them, and they pitch in. Many thanks to Chris for doing so when I needed help.

Showing item type counts on the checkout screen

July 30th, 2010

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:


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"]++;
});

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:


$("#circ_circulation_issue label[for='barcode']").after( ... );

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


<p style="margin-top:1em;">
<span id="avmuout">0</span> Music CDs out, <span id="avmuok">10</span> More Allowed
</p>
<p>
<span id="avbkout">0</span> Audio Books out, <span id="avbkok">10</span> More Allowed
</p>
<p>
<span id="avidout">0</span> Videos out, <span id="avidok">10</span> More Allowed
</p>
<p style="margin-bottom:1em;">
<span id="advdout">0</span> DVDs out, <span id="advdok">5</span> More Allowed
</p>

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


$("#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"] );

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:


$("#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);

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.


function itemTypeCount(){
$("#circ_circulation_issue label[for='barcode']").after("<p style=\"margin-top:1em;\" class=\"icount\"><span id=\"avmuout\">0</span> Music CDs out, <span id=\"avmuok\">10</span> More Allowed</p> <p class=\"icount\"><span id=\"avbkout\">0</span> Audio Books out, <span id=\"avbkok\">10</span> More Allowed</p> <p class=\"icount\"><span id=\"avidout\">0</span> Videos out, <span id=\"avidok\">10</span> More Allowed</p> <p style=\"margin-bottom:1em;\" class=\"icount\"><span id=\"advdout\">0</span> DVDs out, <span id=\"advdok\">5</span> More Allowed</p>");

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();
}
});

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.

Developing with branches

July 22nd, 2010

There was recently some discussion on the Koha mailing list about how “branches” fit into the development process. I replied with a description of how I use branches in my development process, and this post is an expansion of that.

In my discussion of Koha’s bug-reporting process I mentioned that a developer who wants to work on a bug will “accepts” a bug in Bugzilla before beginning work on it. There is a lot more to the developer’s workflow going on behind the scenes. I’ll describe what my process is.

When I first begin to work on fixing a bug, I create a “branch” in the git version control system. When I do so git creates a separate working copy of the main branch, “master.”  This copy is of the very latest version of Koha available. I create a separate branch for each distinct change I want to make to Koha. That change might be defined as a bug fix for a particular bug, or a new feature. The changes to each branch might include modifications to many different files, but the changes should all be related to that one subject.

It’s vitally important that I keep my branches clean and separate from each other because the Release Manager is relying on me to make it easy for him to apply and test my patches. If I submit a patch that covers more than one “subject,” that makes it all the more difficult to test it properly. If I introduce a bug to one aspect of my update, the whole patch may have to be rejected. Keeping things as simple as possible makes it easier for everyone.

To see how this looks in my workflow, here’s a selection of my current working branches:

ip-Bug-3125-IE-selects-2010-05-18
ip-Bug-4173-restricted-status-2010-03-18
ip-Bug-4901-Zotero-subtitles-2010-07-09
ip-hold-interface-test-2010-07-19
* master
ps-Bug-2307-calendar-i8n-2010-07-13
ps-Bug-2704-440-Display-2010-07-13
ps-Bug-2981-alternate-solution-2010-05-18
ps-Bug-3459-topissues-2010-06-29

When I first sit down to work I create a branch with a prefix “ip-” for “in progress,” give it a short title and bug number if I have one, and add the date I started working on it. You can see I might have quite a view branches in progress at a time. This might be because I’m working on a big update which is time-consuming, or it might mean I’m stumped about what the solution is.

Each time I sit down to do more work on a bug I switch to that branch, download the latest updates which have been submitted and approved on the master branch, and tell git to “rebase” my branch. The rebase process merges my changes with the latest updates. If there are any problems with the merge git will warn me and ask me to make manual changes. Usually the process is automatic. I do this every time I sit down to work on an in-progress branch. This ensures that the changes I’m making are compatible with the latest version of Koha.

Once I have finished my work I check it and test it as carefully as I can. I make sure I’ve rebased against the very latest update in git, and I submit a patch. Submitting a patch takes the changes I’ve made and distills them down to a single text file which can be “applied” by the Release Manager or any other Koha developer to their own git installations. I also attach a copy of my patch to the bug report, if there is one, as I described in my bug reporting post. This is another way to get the patch out into the open where others can review it and test it.

After I’ve submitted a patch I rename the branch I was working on with “ps-” for “patch sent” and keep the branch until my patch is approved (fingers-crossed).

All this is on my computer in a virtual machine, so in my case I’m not being open as I might. If I had the resources to work on a real server, or if I kept my work on a service like GitHub I could share all these branches with everyone, from the time I first started working on it to the time my patch was submitted.

If some time has passed and I see that my patch from one of my “patch sent” branches hasn’t been approved I’ll switch to that branch and rebase: I’ll tell git to grab the most recent Koha commits and merge them with the changes in my patch. If not too much time has passed, or the files I changed haven’t been worked on by others the rebase will be successful and I’ll know I’m still on track. If not I might have to manually make changes to my original commit so that it fits in again with the work others have been doing. If manually merging was required, that tells me the Release Manager would have to do the same. I should consider resubmitting a revised version of my patch which can apply cleanly to the latest version.

Keeping all my “patch sent” branches intact until my patch has been approved is important to my workflow because it’s the easiest way for me to keep track of what has been approved and what hasn’t. I can see at a glance which patches of mine have not been approved. If it’s been a while, I might try to find out why not. If there was a problem with the patch I might be able to revise it to the RM’s satisfaction.

I can’t submit a patch and expect it to automatically work a month from now, a week from now, or even a day from now. I’m responsible for keeping up.

I’m not a git expert, and I’ve had lots of help and advice along the way to get me to this workflow. It works really well for me, and I hope it works as well from the point of view of our Release Manager and fellow developers.

Customizing the staff client login logo: Addendum

July 22nd, 2010

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

$("#login h1 a").attr("href","http://www.myacpl.org");

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:

$(document).ready(function(){
$("#login h1 a").attr("href","http://www.myacpl.org");
});
// ]]>

<!--
/* Custom styles here */
#login h1 a {
height:71px;
}
#login h1 {
background:url("http://www.myacpl.org/sites/all/themes/npl/logo.png") no-repeat scroll center top transparent;
}
-->
<script type="text/javascript">// <![CDATA[
// <![CDATA[

The revised version adds our new JavaScript snippet inside jQuery’s standard “$(document).ready()” to be triggered upon page load.
]]>


Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported.