A bookmarklet to jump from OPAC to staff client

Koha has strong separation between OPAC and staff client functionalities. If you log in to the OPAC as a staff user you don’t have any kind of elevated privileges compared to any other user. This is good for extra security, but it can be frustrating for staff if they happen to be looking at a record in the OPAC and want to switch to the staff client.
Continue reading

A quick Firebug tip for editing CSS

I’ve talked before about Firebug’s inspector tool for examinating 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;
border-width: 5px 0;
padding: 5px;

A custom input border

Customizing the staff client login logo

A Koha user (from Tanzania!) asked today on the Koha mailing list, “I need some help on how to customize the staff client login page/replace koha logo with a new one.” I haven’t heard this request before, so it’s a good opportunity to investigate.

If this were the OPAC we could use a system preference, opacsmallimage, to change the logo. We don’t have that option in the staff client, so we’ll have to see if we can use the available customization options to accomplish the same thing.

Our first stop, as usual, is FireBug. I opened up the staff client to examine how the default Koha logo is displayed on the login form. Using the Inspect tool I highlight the logo and view the results in the FireBug HTML inspector window:

FireBug details for the login logo anchor tag

The logo is constructed by nesting a link (“anchor”) tag (<a>) inside a top-level heading tag (<h1>). The above screenshot shows the HTML and style details for the <a>, here are the results for the <h1>:

FireBug details for the login logo heading tag

From this we can collect all the CSS information we need to control the display of the login logo:

#login h1 a {
border-bottom:medium none;

#login h1 {
background:url("../../img/koha-logo.gif") no-repeat scroll center top transparent;

The staff client logo is displayed using an image-replacement technique similar to the one used to display the Koha logo in the OPAC. The style of the anchor tag sets an explicit height which matches the logo image, and it sets a negative text-indent property which moves the text contents of the tag off the screen. These two properties create a blank space inside the anchor tag in which to display the logo.

The style of the heading tag does the work of displaying the logo. The background property points to the URL of the logo image. In the default case this is an image file on the Koha server’s file system. The URL doesn’t have to be a relative one, though. It can be a full URL pointing to anywhere on the internet.

Customizing the logo CSS

In order to change the image we need to make very simple changes to two CSS properties:

  1. The background-image of the <h1> tag.
  2. The height of the <a> tag.

Let’s use as an example the logo on the Athens County Public Libraries site. I can right-click the image in Firefox and choose “View image” to find the details I need. The location bar shows the URL I need, and the title bar shows the dimensions of the image. I just need to note the height.

Since we only need to change two properties, our custom CSS is simpler than the original. We only need to specify the properties which we need to override:

#login h1 a {

#login h1 {
background:url("https://www.myacpl.org/sites/all/themes/npl/logo.png") no-repeat scroll center top transparent;

Applying the custom CSS

We’ve got our custom CSS, now what do we do with it? We don’t have an opacsmallimage preference for the staff client, and we don’t even have an option like OPACUserCSS. We do have a couple of options which will work.


If you have access to your Koha server’s file system you can add a stylesheet there and tell Koha to apply it in addition to the default staff client stylesheet. For example, you could create a new CSS file called custom.css and save it alongside staff-global.css and the other staff client CSS files. Then you can specify that filename, custom.css, in the intranetcolorstylesheet system preference.


If you don’t have access to your Koha server’s file system, there’s a way to insert custom CSS into your staff client pages, but it’s a bit of a hack. Lacking an “intranetusercss” preference we’re going to hijack an existing preference, intranetuserjs, to do the job for us.

When you insert custom JavaScript into the intranetuserjs preference, Koha detects this and adds it to the header of each staff client page, wrapped in the appropriate <script> tags:


Since Koha automatically wraps the intranetuserjs content in opening and closing <script> tags, we’ll have to do a little bit of roundabout coding to embed a <style> block:


/* Custom styles here */


Let’s run down what’s happening here. Lines 1 and 2 have been inserted automatically by Koha in order to properly embed the custom JavaScript it expects from the intranetuserjs preference. Line 3 is the first line of the contents of intranetuserjs. Lines 4 and 5 we have added manually to close the automatically-embedded <script> tag. With the script tag closed we can go on to add just about any HTML we want, really, but this is all inside the <head> of the HTML document, so few things would be valid.

Lines 6, 7, and 8 show the <style> tag we’re adding. This is where we’re going to put our custom CSS. Lines 9, 10, and 11 are the last lines of our custom intranetuserjs. Knowing that Koha wants to close the <script> tag it opened on line 1, we have to re-open a new <script> tag so that when Koha closes it we’ll have valid markup.

Putting it all together, here’s what the contents of our intranetuserjs preference will be:

// ]]>

/* Custom styles here */
#login h1 a {
#login h1 {
background:url("https://www.example.com/images/logo.png") no-repeat scroll center top transparent;

// <![CDATA[

If all goes well, this is what you should see when you log out and look at your login screen:

id=”attachment_633″ align=”aligncenter” width=”300″ caption=”Customized login form”

Note: I’ve published a quick addendum to this post which covers using jQuery to change the URL to which the logo links

A New OPAC Theme: Bootstrap

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.


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.


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:


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

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

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


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


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:


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

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 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");
$("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("https://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:

var ohdbks_link = $("span.online_resources a[href^='http://ohdbks']").attr("href");
$("#holdings").html('<a href="'+ohdbks_link+'"><img src="https://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