Managing patrons with same permanent & local address

Setting your borrower’s local address same as their permanent address with just a single click during patron entry into Koha ILS.

Often folks when unable to find some nifty feature that was present in their erstwhile LMS but not there in Koha, is found to be exclaiming – “But we can’t do that with Koha!”. Well, we have news for you – Koha is open source and that means, you can build / modify the parts that you need or are missing. But you do not know how to do that. Well… *that* is not really Koha’s problem. But fear not, if you are willing and have the aptitude for poking around code you can do it too. There are plenty of open access resources that show you how to do so, just waiting for you to pick up and start working on your skills. After all, it is said:

If you give a hungry man a fish, you feed him for a day, but if you teach him how to fish, you feed him for a lifetime.

Why this post

At L2C2 Technologies, we work with a lot of academic libraries where they need to record both the permanent as well as local address of their students. Koha allows for recording more than a single address for a patron since donkey’s years. If you look at the schema of the borrowers table in the Koha database, you will see that there are fields to record both the primary address as well as alternate address. These two set of fields fit nicely into our permanent and local address requirement.


However, the library staff often complain that it is useless extra work to re-enter the same data over in both set of fields as many users often have one and the same address for both. As a result, we are sometimes asked how to cut down this extra work. In this post, we are going to share one of the ways by which you too can do the same, should you need to do this.

Choosing our tools

All we use are snippets of JavaScript, jquery and css to achieve our objective. All of which go in into the Koha database as part of the IntranetUserJS system preference. We do not touch any template file or change any underlying PERL code. This way our tweak is guaranteed to survive Koha version upgrades without any further effort on our part.

The steps… as easy as 1-2-3

Since we do not want to re-type the same information, the only option is to copy it from first set of fields and that what we do by adding a checkbox HTML form input element. We give this checkbox the id copypermaddress and insert this into the DOM just before the first li element belonging to the parent fieldset memberentry_address on the Add Patron screen.

$('<li><input type="checkbox" name="copypermaddress" id="copypermaddress" value=""><label for="copypermaddress">Same as permanent address:</label><div class="hint">Click to copy permanent address data</div></li>').insertBefore(' #memberentry_address > ol > li:first-child ');

While the above insertion gets us the following screen, it still does not do anything i.e. if you clicked the checkbox, nothing would happen yet. In the next step we cover that.


So we add a listener that will wait for state-change of the checkbox. In plain English, that means it will detect when a user clicks that checkbox and then based on whether it was selected or unchecked, appropriate action would be taken. And that exactly what happens below. The first part goes into action if the checkbox was checked and the part coming after the else kicks in when it is unchecked. In the first instance we copy over the values from the permanent address field and in the second part we undo the copy and blank out the local address fields.

$('#copypermaddress').change(function() {
  if(this.checked) {
  } else {
    $('#B_state').val('West Bengal');

In the two following screenshots we get to see how exactly this works. In the first one, only the permanent address has been added. While in the second screenshot, we see how the data has been copied over when the checkbox is clicked.




  1. .insertBefore()
  2. :first-child Selector
  3. .change()
  4. .val()
  5. Koha DB Schema –

Harnessing Koha’s ExtendedPatronAttributes (aka patron custom fields)

Custom fields that make it possible to fit KohaILS to any type of library user category.

During from my frequent interactions with Indian Koha users over the last several years, one thing stands out rather starkly. There is surprisingly little understanding or use of the capabilities offered via Extended Patron Attributes. Since Koha ILS was written originally for public libraries (in fact public library consortia), its default patron data structures too are somewhat aligned with public libraries’ patron information capture.

When put to use in academic libraries e.g. K12 schools or colleges, the default patron information schema does not address the obvious need to capture data points like – programme enrolled, registration / roll numbers / class / sections details and in case of K12 schools – parent / guardian name and contact information etc. Many Koha users from the Indian sub-continent either (a) work their way around these issues without fully addressing their needs OR (b) often resort to direct editing of the koha.borrowers table schema, adding new custom fields and modifying the template files (.tmpl or .tt files) along with the Perl scripts that drive these templates.

The second approach is particularly problematic, as it means the modifications are usually hardcoded into scripts and templates. This is problematic is because doing so prevents the user from the benefit of seamless upgrades to their Koha. It means they have to do the whole “rinse-and-repeat” cycle everytime they upgrade their Koha, if they want their changes to persist. This makes Koha upgrades a costly, laborious, time-consuming process and error prone process.

Enter ExtendedPatronAttributes

According to the Koha manual –

“Patron attributes can be used to define custom fields to associate with your patron records. In order to enable the use of custom fields you need to set the ExtendedPatronAttributes system preference.”

About 10 years back, as Koha was finally moving out of version 2.x and moving into Koha 3.x, several new and exciting features were coming on to their own in Koha. One of this was the ability to easily handle custom fields for our patron records aka patron attributes. Around May 2008, my friend Galen Charlton, then with LibLime, wrote a (rather) large chunk of the code that brought in the support for custom fields to patron records. The ExtendedPatronAttributes system preference was the outcome and custom fields were here to stay.

Flash forward to present day

Recently we have been working with the Senior section library of Don Bosco School in Calcutta. Being a school library they needed to additionally support the following fields in their patron record (a) Class (b) Section (c) Roll No. (d) Parent / Guardian information i.e. name, contact info, relationship with student. Of course, we used defined these custom fields as patron attributes that were applicable only for their student patron category. In this blogpost, I will try to share just how easy and painless this is.

Step #1 : Enable ExtendedPatronAttributes syspref

This *is* the very first step and unless you enable this syspref, no matter what you do to define your custom fields (aka patron attributes), nothing would be visible.

Step #2 : Defining the Patron Attributes

In our case, we had two sets of information to be handled i.e. the student’s (a) academic details and (b) parent / guardian information. So we defined ST_CLASS, ST_SECTION and ST_ROLLNO patron attributes for the first part and ST_PNAME, ST_PRELATN and ST_PCONT as attributes for the second part.


To make things easier for the library personnel (and reduce human error in the process), we pre-defined the values available to ST_CLASS, ST_SECTION and ST_PRELATN as authorised values.


We also defined the PA_CLASS authorised value with the following two values : (a) ADETAILS (for academic details) and (b) GDETAILS (for guardian information).


Step #3 : PA_CLASS – the secret sauce!

The Koha manual barely touches on this little nugget otherwise known as the PA_CLASS authorised value category. Before we proceed, just remember that in Koha Authorised value and Authority value mean two completely different things. Here we are talking about the former. If you have ever done any programming or done anything online, you must have used a drop-down / picklist to select a value. Well in Koha, authorised values are simply another name for picklists. These are defined as a category with the options added it. To the end-user, authorised values are presented as select drop-down HTML form element.

Now coming to PA_CLASS (or Patron Attribute Class), the first thing to remember is that by default Koha does not even define the PA_CLASS authorised value category. Rather it is left to the user to define it. There is a reason why it is not defined by default, not every library is going to used ExtendedPatronAttribute and unless you use it, PA_CLASS has no use. In our case, we have defined it and allotted it two values – ADETAILS and GDETAILS for now.

By allotting our custom fields (patron attributes) to either of these two PA_CLASS values allows us to logically group our two sets of information. By default, once done it looks like this:


Order! Order! Order!

While chaos defines us, in life it is order that we look for, especially when we are attempting to present or capture information. So while the “Additional attributes and identifiers” grouping at the end of the page is adequate it is not ordered in the most logic flow with respect to the overall patron information form. Lucky for us, Koha has supported JQuery for donkey’s years. And JQuery provides us with a very nifty method .detach(). As the documentation says:

The .detach() method is the same as .remove(), except that .detach() keeps all jQuery data associated with the removed elements. This method is useful when removed elements are to be reinserted into the DOM at a later time.


By detaching the PA_CLASS grouped fieldsets from the DOM and by storing these into variables one at a time, we are now ready to insert them exactly where we want these fieldsets to be placed in the overall form. And that is exactly what we did.



This way we did not touch the templates or the underlying business logic of KohaILS. All our definitions are stored in the database. As a result, we can now perform IN-SITU upgrades of Koha without worrying if we will break our forms if we upgraded.

Koha and the “magic” of XSLT : displaying new MARC fields on the OPAC.

A short tutorial on using XSLT to make MARC fields in your data visible on the OPAC.

Earlier today, Suresh Kumar Tejomurtula, a member of the venerable LIS-Forum mailing list being run out of IISc Bangalore, posted a question on that list:

Under language codes of 008/35-37 and also under 041$a I added language code. for eg: tel for Telugu language. But I do not see any difference to the view of the record, except that the marc tags contains that values. Adding these fields data will enable library team to understand the language of the material. My question is, How will the users of the OPAC, who do not know about marc language codes will understand the item language [from just the 3-letter code sequence].

Short answer : Using XSLT

Much of Koha’s superpowers on the OPAC (as also on the staff client) side comes from its judicious use of XSLT. When we search for documents in Koha, the result that is returned from the database by way of the various perl modules that perform much of Koha’s internal plumbing, comes in as an XML (eXtensible Markup Language) document. More precisely it is returned as a MARCXML record. Readers of this blog who are familiar with the MarcEdit software may have often encountered a MARCXML record. Those who are not so familiar may well like to read up a bit from here before proceeding with this post.

So what is XSLT?

Wikipedia gives the definition of XSLT as –

“XSLT (Extensible Stylesheet Language Transformations) is a language for transforming XML documents into other XML documents, or other formats such as HTML for web pages, plain text or XSL Formatting Objects, which may subsequently be converted to other formats, such as PDF, PostScript and PNG.”

Where to start?

At the OPAC level, the XSLT magic is primarily driven by two files i.e. (a) MARC21slim2OPACResults.xsl and (b) MARC21slim2OPACDetail.xsl. Koha’s default settings of how we see the search results on the OPAC and the document specific details in the Normal view, are defined in these two files.

N.B. Directly editing these two files is strictly not advised unless you are a XSLT guru.

Lucky for us that Koha’s system preferences provide options to override the defaults by creating new XSLT files and telling Koha to use the new ones instead. The screenshot below shows the default setting.


The two files are available inside a folder named xslt under the locale of the selected theme you are using e.g. /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/xslt/ on a package-based installation. By default most of us in India would be using the English locale i.e. “en”. The default Koha theme is “bootstrap”. Thus if you are using a custom theme and/or different locale look for the files under that.

Step #1 : Copying the XSLT files

We will be fetching the 3-letter language code from MARC 008/35-37 of each marc record. Since our Koha instance here is named as “demo”, we’ll make a copy of the file MARC21slim2OPACResults.xsl as MARC21slim2OPACResults-demo.xsl and the MARC21slim2OPACDetail.xsl as MARC21slim2OPACDetail-demo.xsl.

N.B. You can give any name to the copies you make, but it is suggested that the less adventurous you are with the names, easier it will be for you to trace your steps back if you make a mistake while editing them. And trust me you will make mistakes, at least initially.

Step #2 : Editing MARC21slim2OPACResults-demo.xsl

The MARC21slim2OPACResults.xsl is what drives the display of results of a search on the Koha OPAC. And it does not show the value of 008/35-37 i.e. MARC language code, while displaying the search result. To add this facility, we need to do the following to our copy i.e. MARC21slim2OPACResults-demo.xsl. Around line no. 70 or there about, there will be this line <xsl:variable name="controlField008-30-31" select="substring($controlField008,31,2)"/>. Add the following line after it – <xsl:variable name="controlField008_35-37" select="substring($controlField008,36,3)"/>.

Explanation: we’re defining a new variable named controlField008_35-37 and in it we are storing the 3-digit value found at 008/35-37 from another variable – controlField008.

The second step in editing this file is to add the code to check if (a) 008/35-37 actually exists (e.g. if you have a blank 008 field, 008/35-37 won’t exist) and (b) it is set as something other than “und(i.e. undefined). The following code does that first and proceeds to match the value found in 008/35-37 against 23 different languages. These languages are English and the 22 official languages of India as per the Eighth Schedule of the Indian Constitution. You can add or remove any language from this list as you require. However, when you do, please make sure that the codes you setup in this list here are coming from the Code Sequence document of the MARC Code list for languages as published by the US Library of Congress.

This means that you must also be using these same exact codes in your MARC records in Koha.


Where we place this code will depend on where we want this language to listed in the results. In our case, we decided to add it between Material type and Format. And thus in our case, the code was added at line no 637. If you too want language to be displayed between the Material Type and Format, then look out for this line <xsl:if test="string-length(normalize-space($physicalDescription))"> and add this block before.

Saved the file and moved on to the next section.

Step #3 : Editing MARC21slim2OPACDetail-demo.xsl

The process is similar to what we just did above. Open the file MARC21slim2OPACDetail-demo.xsl for editing and go to line no. 51 (or there about) and look for this line <xsl:variable name="controlField008" select="marc:controlfield[@tag=008]"/>. Add the following line immediately after that: <xsl:variable name="controlField008_35-37" select="substring($controlField008,36,3)"/>.


Since we wanted the “Language of document” to come after Material type, we added the code immediate after the node <xsl:if test="$DisplayOPACiconsXSLT!='0'"> is closed but before <!--Series: Alternate Graphic Representation (MARC 880) -->; in our case, this worked out to be around line no. 195. Finally, we saved and closed the file.

Getting Koha to use the new XSLT files

The Koha system preference OPACXSLTResultsDisplay was changed from its original setting (i.e. “default”) and set to the path of our new file MARC21slim2OPACResults-demo.xsl i.e. /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/xslt/MARC21slim2OPACResults-demo.xsl. Likewise the other system preference OPACXSLTDetailsDisplay was changed to /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/xslt/MARC21slim2OPACDetail-demo.xsl. It was time to test our XSLT modifications.

And it works!

Since pictures are said to be worth a 1000 words, we will let before and after screen grabs do the talking here. Also if anyone wants to see directly how it actually looks after applying the changed XSLT, visit the URL

Before : Using the default MARC21slim2OPACResults.xsl


After : Using the new MARC21slim2OPACResults-demo.xsl


Before : Using the default MARC21slim2OPACDetail.xsl


After : Using the new MARC21slim2OPACDetail-demo.xsl


JQuery tips for Koha : Adding easy to use indicator picklists

Adding picklists for selecting indicators for MARC tags used in Koha’s cataloging worksheets.

During data audits of users’ MARC21 data, quite frequently we find that most, if not all, records are often without any form of use of indicators. Trained library professionals often give a sheepish grin when asked why they didn’t add them while cataloging the documents. ūüėČ But trained librarians are not the only ones who work with Library systems like Koha. There are many people who find themselves working in a library without a formal training or sufficient theoretical background on MARC21. Generally speaking reasons for not adding the indicators range from:

  • Lack of practise – thus unsure of the correct indicator to use.
  • Lack of awareness – i.e. untrained people with a very basic knowledge of cataloging
  • Lack of user-friendly mechanism to input indicators
  • And lastly – sheer laziness

Now, about the last one we can’t do anything about, however the rest of the reasons might use a bit of leg-up! So here goes the newest tutorial on how to add easy-to-use picklists to help us correctly populate the indicators.

According to the Design Principles of MARC21, indicators form a part of the family of content designators [1]. As defined, an indicator is :

A data element associated with a data field that supplies additional information about the field. An indicator may be any ASCII lowercase alphabetic, numeric, or blank.

For this tutorial we will focus on MARC21 bibliographic data fields 100 and 110 i.e. Main Entry Personal Name and Main Entry Corporate Name respectively. We will not touch the Koha template files at all, rather as per the global best practice for Koha ILS, we will utilize only JQuery (JavaScript) and HTML via the Koha system preference IntranetUserJS.

Step #1 – Finding out the DOM nodes

We will start by going to Home > Cataloging > Add MARC record in Koha and select the framework we want to work on. In this case we chose to work with the “Default framework” that is shipped with Koha. We used Google Chrome’s Developer Tools Inspect option [2] to find out what is the id of the selector (DOM node) we need for Main Entry Personal Name.

Since we need space to setup the picklist we chose to use the free space available on the div that displays information about the field that follows immediate after it. As you can see in the image below that div has an id identifying it, which is very good for us, since it makes selecting the DOM node absolutely painless.


It should noted that when Koha renders the cataloging interface, it suffixes the HTML element IDs with a random number (one for each new tag). In this case, the id was div_indicator_tag_100_838390 where “838390” is the random suffix number. We needed to latch on to the first part i.e. div_indicator_tag_100.

Step #2 – Let the JQuery magic work

We have to add the select dropdown picklists right after the text on the div_indicator_tag_XXX DIVs. The value we will use for the indicators will come from here and here respectively.

if ( $("#cat_addbiblio") ) {	// only while adding biblios
  $('div[id^="div_indicator_tag_100"]').append(' <label for="tag_100_indicators">Apply Ind1, Ind2</label> <select id="tag_100_indicators"><option>-Select-</option><option value="1">1 - Surname</option><option value="0">0 - Forename</option><option value="3">3 - Family name</option></select>');
  $('div[id^="div_indicator_tag_110"]').append(' <label for="tag_110_indicators">Apply Ind1, Ind2</label> <select id="tag_110_indicators"><option>-Select-</option><option value="2">2 - Name in direct order</option><option value="0">0 - Inverted name</option><option value="1">1 - Jurisdiction name</option></select>'); };   // end if


While that added the picklists, we still have to add the actual logic that will allow the indicators to be populated on selecting from the list. Again we will turn to JQuery for the following snippet:

    var what_clicked_100 = $('#tag_100_indicators').val();
    if ( !isNaN(what_clicked_100) ) {
    } else {
    var what_clicked_110 = $('#tag_110_indicators').val();
    if ( !isNaN(what_clicked_110) ) {
    } else {

The code above is listening to see when we click and select a value from the picklists i.e. when we trigger a click JavaScript event. Next it checks if we had selected a real value OR whether we had just “clicked” on the placeholder “-Select-” option that no value. And lastly based on what we had selected it sets the ind1 and ind2 values according.



In this manner we can add easy-to-use picklists for indicators. Since it is now only a matter of selecting from the available values, it also reduces significantly the scope for typographical errors during data entry into the indicator boxes. Before we leave for today, do note that the second code listing may be better handled as a JavaScript function to which the references are passed to by a handler hook. Doing so would make for a cleaner and leaner implementation of this concept especially if you are planning to set it up for all the non control MARC21 fields you use. Also, you may wish to implement the selected dropdown value check using something other than IsNan [3].


[1] “MARC 21 Specifications for Record Structure, Character Sets, and Exchange Media – RECORD STRUCTURE (2000)”

[2] “Chrome DevTools” –

[3] isNaN() –

Customizing Koha’s iconset to match page background

The world’s favorite open source ILS aka Koha ships with several iconsets included i.e. carredart, crystal-clear, seshat, bridge, npl, vokal etc. The primary use of these icon sets is to provide visual cues for different item types e.g. books, serials, DVDs, sound recordings, electronic materials etc. The icon set used by default is The Bridge Material Type Icon Set.
It is licensed under Creative Commons 2.5 Attribution, ShareAlike license.

This HOWTO will focus on how to customize the bridge iconset so that our icons match the OPAC page background. The iconset as shipped by Koha are in .gif format with a white background. This default works perfectly well when we stick with the default CSS of Koha, where the page background (the main div) is also white as seen below.


There are times when¬†we may¬†wish to customize the OPAC CSS using the opacusercss system preference, for instance in this case, we wanted to change¬†the body.main div’s background-color to match our custom OPAC color theme:

/* change main div color */
div.main { background-color: #EAE9E7; }

But due to the white background of the Bridge iconset, the page now looked like this:



Obviously this needed to be fixed. We went to The Bridge Material Type Icon Set Project page and downloaded the zip file (downloaded from here) containing the original .psd files of the icons.

While you can use Photoshop to edit them, we used GIMP (GNU Image Manipulation Program) to edit the .psd files. We will use the book material type icon – book.psd for this example.

Instructions for editing the icons using GIMP

    1. Open book.psd in GIMP
    2. Check the layers – both visible and the ones turned off gimp_layers
    3. Set the foreground color to #EAE9E7 gimp_forecolor
    4. Add a new layer using using foreground color as set above gimp_newlayer
    5. Arrange the layers correctly with only the text layer, the graphic and the new layer using the color EAE9E7 being visible in proper order gimp_addedlayer
    6. Use GIMP’s Export As option in the File menu to create your new book.gif

Repeat the above steps until you have changed all the required icons. Save all the exported .gif files in a single directory / folder which we will call as “demolib” in this example.

Getting Koha to use the customized icons

N.B.: Koha stores the item type icons in two separate locations i.e. opac-tmpl/bootstrap/itemtypeimg/ (for the OPAC) and at intranet-tmpl/prog/img/itemtypeimg/ (for the staff client)

  1. Create an OPAC sub-folder for your customized icon set mkdir -p /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/itemtypeimg/demolib
  2. Create a staff client sub-folder for your customized icon set mkdir -p /usr/share/koha/intranet/htdocs/intranet-tmpl/prog/img/itemtypeimg/demolib
  3. Copy all the .gif files in your local demolib folder into both the newly created sub-folders above. Note: You may need to use an FTP / SCP client to copy the files, if you Koha server is located on a remote machine.
  4. Navigate to Home -> Administration -> Item types administration on your Koha system.itemtypes
  5. Click on Edit option against the itemtype Book (BK). You should now be able to see a new icon set tab named “demolib” under the “Choose an icon” section def_iconset_03
  6. Select the new icon for the Book Item type from this demolib library and save the change.
  7. Repeat for each of the item types that you wish to update with your new customized iconset.

Now visit your OPAC page again and select the “Advanced search” option. This time Koha will be using your new icons and these will merge correctly with the page background.

PRO-TIP: Instead of editing the existing Bridge icon set, you can also create your own icon set. The usual icon sizes are 32×32 pixel or 40×40 pixel (Bridge uses this dimension). Design and save them to a specific folder and then follow the instructions in the section Getting Koha to use the customized icons. Demolib is just a name we are using here, you can change it to anything else as long as they are not the ones that are already used in Koha.