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.

2017-06-19_01

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.

2017-06-19_02

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.

$(document).ready(function(){
$('#copypermaddress').change(function() {
  if(this.checked) {
    $('#B_address').val($('#address').val());
    $('#B_address2').val($('#address2').val());
    $('#B_city').val($('#city').val());
    $('#B_state').val($('#state').val());
    $('#B_zipcode').val($('#zipcode').val());
    $('#B_country').val($('#country').val());
  } else {
    $('#B_address').val('');
    $('#B_address2').val('');
    $('#B_city').val('');
    $('#B_state').val('West Bengal');
    $('#B_zipcode').val('');
    $('#B_country').val('India');
  }
});
});

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.

2017-06-19_03

2017-06-19_04

References

  1. .insertBefore()http://api.jquery.com/insertbefore/
  2. :first-child Selectorhttps://api.jquery.com/first-child-selector/
  3. .change()https://api.jquery.com/change/
  4. .val()http://api.jquery.com/val/
  5. Koha DB Schema – http://schema.koha-community.org/master/

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.

2017-05-16_03-44-10

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.

2017-05-15_19-34-06

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

2017-05-16_03-50-36

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:

2017-05-16_01-49-10

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.

blog-epa

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.

epa-full

Conclusion

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.

2017-05-04_03-05-15

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.

2017-05-04_05-40-55

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)"/>.

2017-05-04_06-02-17

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 http://demo-opac.l2c2academy.co.in/cgi-bin/koha/opac-detail.pl?biblionumber=18

Before : Using the default MARC21slim2OPACResults.xsl

chrome_2017-05-04_07-05-24

After : Using the new MARC21slim2OPACResults-demo.xsl

chrome_2017-05-04_07-17-09

Before : Using the default MARC21slim2OPACDetail.xsl

chrome_2017-05-04_07-48-28

After : Using the new MARC21slim2OPACDetail-demo.xsl

chrome_2017-05-04_07-49-09

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.

blog_01

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.

$(document).ready(function(){
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
});
});

blog_02

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:

$(document).ready(function(){
  $('#tag_100_indicators').click(function(){
    var what_clicked_100 = $('#tag_100_indicators').val();
    if ( !isNaN(what_clicked_100) ) {
      $('input[name^="tag_100_indicator1"]').val(what_clicked_100);
      $('input[name^="tag_100_indicator2"]').val("#");
    } else {
      $('input[name^="tag_100_indicator1"]').val("");
      $('input[name^="tag_100_indicator2"]').val("");
    }
  });
  $('#tag_110_indicators').click(function(){
    var what_clicked_110 = $('#tag_110_indicators').val();
    if ( !isNaN(what_clicked_110) ) {
      $('input[name^="tag_110_indicator1"]').val(what_clicked_110);
      $('input[name^="tag_110_indicator2"]').val("#");
    } else {
      $('input[name^="tag_110_indicator1"]').val("");
      $('input[name^="tag_110_indicator2"]').val("");
    }
  });
});

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.

blog_04

Conclusion

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

References

[1] “MARC 21 Specifications for Record Structure, Character Sets, and Exchange Media – RECORD STRUCTURE (2000)” https://www.loc.gov/marc/specifications/specrecstruc.html

[2] “Chrome DevTools” – https://developers.google.com/web/tools/chrome-devtools/

[3] isNaN() – https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/isNaN

The 5-Minute Series: Adding Lightbox support to your Koha OPAC

Ever wanted to add a Lightbox enabled custom gallery page to your Koha ILS installation? Here’s how you can do it, with a bit of background and a brief touch on caveats and afterthoughts of implementing it.

Recently one of our client partners, Ms. Parama Sarkhel, Librarian, Ramakrishna Sarada Mission Vivekananda Vidyabhavan, requested us to add an image gallery with photos of the library and library events to her OPAC. We promised her that we’ll to look into it.

gallery_01

While we had setup image galleries for others, this time we decided to do something different. As any seasoned Koha user will know, you can add custom pages to your Koha OPAC. Adding a gallery typically means adding a new custom page with a bunch of photos and the nessecary CSS styles along with (usually) some Javascript to handle it. In fact, if you are not too bothered about supporting older browsers you can set up a gallery using *only* CSS3 alone.

NOTE 1: If you are a new user of Koha, you may wish read up Appendix H. Using Koha as a Content Management System (CMS) from the Koha 16.05 Manual (en). Be advised that the instructions for Koha as a CMS are slightly out of sync, so you need to change where it says “pages.tmpl” to “pages.tt” to be able to actually use these instructions.

NOTE 2: Prior to release of Koha v 3.4.3 [1] on July 25, 2011, Koha used the HTML::Template perl module for handling its template requirements. Via Bug id #5917 [2], Koha 3.4.3 switched over to Template::Toolkit templating system [3]. The reference to “pages.tmpl” is a relic from Koha’s HTML::Template past.

Introducing Lightbox2

To an average Web UI designer / programmer, Lightbox usually needs no introduction. However since the target audience of this blog includes people who do not neccesarily program, either for passion or a living, let us introduce the main “protagonist” of our post here i.e. Lightbox! Lightbox2 is a successor to the the original lightbox [4] script by Lokesh Dhakar. As described by it’s author Lokesh :

“Lightbox is small javascript library used to overlay images on top of the current page. It’s a snap to setup and works on all modern browsers.”

Users who are new to the term lightbox (you have probably used it online, without knowing that it is called a ‘lightbox’) can have a look at [4] below in the reference sub-section.

Making Lightbox2 work with Koha

Before we get out hands dirty and share with you what we did, here are a few things that we must keep in mind.

First the things that one must know

1. As on date the Koha OPAC uses an older version of Jquery javascript library i.e. version 1.7.2 (released [5] on March 21, 2012) AND a rather old version of the Twitter Bootstrap framework i.e. 2.3.1. So whatever lightbox script / library we choose to use, it *must* work correctly with these two software’s version as shipped with Koha.

2. Luckily Lightbox2 works with jquery 1.7.x or higher, which puts us in the clear about our choice of lightbox library.

3. When Lokesh’s Lightbox was released about 8 years ago, the world of web development was vastly different from today. Different browser versions (mainly IE) implementing “quirky” mode vs. “strict” modes differently, support of HTML5 / CSS3 often varied significantly from W3C standards, desktop PCs rather than smartphones and tablets ruled the world. In fact, we were also witnessing the closing moments of the second browser wars [6]. By selecting the up-to-date version of the original lightbox script, we ensure that we are using a mature javascript library with the largest possible cross-browser, cross-device compatibility *including* backward compatibility.

Now that we have all these history lessons out of the way, let us proceed with the actual steps to get this show on the road.

Step #1 – Downloading Lightbox2

Following the instructions on the Lightbox2 site, we proceeded to download the latest version of the library https://github.com/lokesh/lightbox2/archive/master.zip on our server and proceeded to unzip it.

Step #2 – Installing Lightbox2 inside our OPAC’s DocumentRoot

Since we are using Debian 8.4 on our server with Koha being installed via the .deb package route, our OPAC’s DocumentRoot is located by default at /usr/share/koha/opac/htdocs. As our server is multi-tenanted [7], we are going to create a new folder lightbox2 under this location so that every Koha instance running off this server can take advantage of the Lightbox installation.

sudo mkdir /usr/share/koha/opac/htdocs/lightbox2

Next we shall copy over the folders under the /dist folder from inside our unzipped copy of Lightbox2.

sudo cp -R dist/* /usr/share/koha/opac/htdocs/lightbox2/.

Three folders should be copied over css,images and js. The important files that we will need for our work are:

/usr/share/koha/opac/htdocs/lightbox2/css/lightbox.css
/usr/share/koha/opac/htdocs/lightbox2/js/lightbox.js
/usr/share/koha/opac/htdocs/lightbox2/images/close.png
/usr/share/koha/opac/htdocs/lightbox2/images/loading.gif
/usr/share/koha/opac/htdocs/lightbox2/images/next.png
/usr/share/koha/opac/htdocs/lightbox2/images/prev.png
Step #3 – Getting Koha to work with Lightbox

Now that we have the Lightbox2 library installed on our server, it is time to tell Koha how to use it. And the way we are going to do that using the very important OPAC system preference OPACUserJS[8] and some jQuery magic that will help us load up the library into our OPAC’s Document Object Model (DOM)[9]. This is how we will do it:

$(document).ready(function () {
  $("head").append("");
  $.getScript('/lightbox2/js/lightbox.js').done(function( script, textStatus ) {
    console.log( textStatus );
  })
});

The first line $("head").append(""); inserts the necessary stylesheet (lightbox.css) into the <head> section of the OPAC. The second line uses $.getScript[10] to dynamically load lightbox.js into the page using an AJAX based HTTP GET request when the OPAC page’s DOM has been fully loaded. The last line is used to log the success or failure of the attempt to load the file lightbox.js.

Step #4 – Using Lightbox

Adding the data-lightbox attribute a image link activates the lightbox capability for the image of our choice. The value of the data-lightbox attribute should be unique on the page on which the image is, unless we want to create a set of images on that page which should all be served by Lightbox . Basically, using the same value for a set of image links creates a manual carousal for that page. Since we are creating an image gallery we will use the same value for the entire set of images placed on and linked to from our gallery page. In fact, in our case, we wanted to show *two* galleries on the same page – one showing every day activities, another showing a recent event organised by the library. So, we ended up using *two* data-lightbox values – one for each of the sets.

This is where we define our custom page and the custom CSS styles to set things up and ready for Lightbox to take over.

A snippet of our custom page’s markup as follows, the data-title attribute adds the captions to displayed by Lightbox. As you can see, all the four example images share the same data-lightbox attribute i.e. “gallery-1” marking them as a part of a single set or gallery of images.

<div class="span3 l2c2galimg">
  <a href="gallery/rksmvv_gallery_02.jpg" data-lightbox="gallery-1" data-title="Reading Room - Journal Section">
    <img src="gallery/rksmvv_gallery_02.jpg" alt="Reading Room - Journal Section" />
  </a>
  <div class="desc">Reading Room - Journal Section</div>
</div>

<div class="span3 l2c2galimg">
  <a href="gallery/rksmvv_gallery_03.jpg" data-lightbox="gallery-1" data-title="Circulation Counter">
    <img src="gallery/rksmvv_gallery_03.jpg" alt="Circulation Counter" />
  </a>
  <div class="desc">Circulation Counter</div>
</div>

<div class="span3 l2c2galimg">
  <a href="gallery/rksmvv_gallery_04.jpg" data-lightbox="gallery-1" data-title="E-Resource Centre">
    <img src="gallery/rksmvv_gallery_04.jpg" alt="E-Resource Centre" />
  </a>
  <div class="desc">E-Resource Centre</div>
</div>

<div class="span3 l2c2galimg">
  <a href="gallery/rksmvv_gallery_05.jpg" data-lightbox="gallery-1" data-title="Photocopy Service">
    <img src="gallery/rksmvv_gallery_05.jpg" alt="Photocopy Service" />
  </a>
  <div class="desc">Photocopy Service</div>
</div>

In the following snippet note that the data-lightbox attribute is different, thus marking these entries as a separate set or gallery.

<div class="span3 offset3 l2c2galimg"><a href="gallery/rksmvv_gallery_01.jpg" data-lightbox="gallery-2" data-title="Inauguration of Research and Resource Centre - #1"> <img src="gallery/rksmvv_gallery_01.jpg" alt="Reading Room - Journal Section" />
</a>
<div class="desc">Inauguration - #1</div>
</div>
<div class="span3 l2c2galimg"><a href="gallery/rksmvv_gallery_10.jpg" data-lightbox="gallery-2" data-title="Inauguration of Research and Resource Centre - #2"> <img src="gallery/rksmvv_gallery_10.jpg" alt="Circulation Counter" />
</a>
<div class="desc">Inauguration - #2</div>
</div>

The custom CSS classes l2c2galimg and desc as seen in the above snippets are simply used to style the images and the captioning <div> and are not related to lightbox’s CSS declarations and so you are free to define your own styling.

Show me the money!

See the Lightbox enabled galleries in action here https://rksmvvlibrary.in/pages.pl?p=gallery. Simply click on any of the images and watch Lightbox take it over. As these are galleries you can scroll through the images by touching / taping / clicking the left or right side of any image in the set or even the left/right arrow keys on your keyboard to go back or forward. Clicking or touching the “XCLOSE widget or for that matter anywhere on the screen outside the lightbox popup will take you back to the gallery page.

Caveats and afterthoughts

1. You do not neccesarily need to put your list of images into separate divs of spanX class as we have done here. Lightbox will work equally well with unordered lists <ul> classed with Bootstrap 2.3.1’s thumbnail styles.

2. This set of instruction will work with all the previous versions of Koha that uses Bootstrap 2.3.1 and jQuery 1.7.2 for the OPAC. Basically that means all versions of Koha which have shipped with the bootstrap theme i.e. Koha 3.14 and above.

3. Lazy loading[11] the lightbox.js library using getScript AJAX call comes with *one* penalty though. The script is loaded timestamped and hence not cached, meaning it gets loaded each time this gallery page is opened by a visitor. You may be able to workaround the lack of caching by using the jQuery.ajax call and setting the datatype to script and indicating an expiry value for lightbox.js. We haven’t tried it, so YMMV!

4. Of course, if you deem this to an important enhancement (we don’t) then you can of course file a new enhancement bug and submit a patch to Koha community.

References:

[1] Koha 3.4.3 is now available

[2] Bug 5917 – Switch Koha to use Template::Toolkit

[3] http://template-toolkit.org/

[4] Lightbox (JavaScript) – From Wikipedia, the free encyclopedia

[5] jQuery 1.7.2 Released

[6] Second browser war – From Wikipedia, the free encyclopedia

[7] Multitenancy – From Wikipedia, the free encyclopedia

[8] 1.11.2.50. OPACUserJS – Koha 16.05 (En)

[9] Document Object Model – From Wikipedia, the free encyclopedia

[10] jQuery.getScript()

[11] Lazy loading – From Wikipedia, the free encyclopedia

Adding the item type filter to OPAC masthead search

Earlier today my good friend Vimal Kumar Vazaphally posted a question here about how to add the the item type (mc-itype in koha search speak) filter as a dropdown to the default main masthead search in the Koha OPAC.

Fig. 1: The default OPAC masthead search bar.
Fig. 1: The default OPAC masthead search bar.

RTFM and RTFM often!!! It may save your life!

<rant>The discussion that pursued on the FB group made something very¬†clear. People forget to read the fine manual and when they do, they do not read “between the lines”. Trust me on this one, the Koha user manual is truly a ginormous treasure trove, if you take the pains to read it.</rant>

Ok! here is why I said that people really need to RTFM. The solution to the problem which Vimal shared can easily be extrapolated from this section in the manual –¬†Appendix P: Extending KohaNewest title pulldown¬†(#KohaTrivia it is based on a July 2012 blog post by Nicole C. Engard (Koha’s indefatigable Documentation manager).

“Reading between the lines” of a given solution

Here was the catch: Nicole’s solution pulled out only the newest arrivals of each itemtype, whereas we need it to pull out everything tagged to an itemtype, whether new or old. The second catch was that in Nicole’s example, she added plain HTML to the OpacNav system preference. However we are going to add it via the jquery / javascript route using the opacuserjs system preference.

We will follow Nicole’s example and pull out all item types that we need to populate the drop-down using SQL. However, we will need to escape the additional “backslash” (i.e. \ ) since¬†we need MySQL to execute the query and actually generate the HTML markup that will be rendered on the browser¬†via Javascript. Javascript does not care for¬†arbitrary line breaks ūüėČ [1] and MySQL does not care about unescaped backslashes!

Now, if this sounded confusing, ponder for a moment on this Ajeet joke from yesteryears:

Raabert: Boss? Is kaa kyaa kare boss?
Ajeet: Rawbert! Is pille ko liquid oxygen me daal do. Liquid ise jeene nahi dega, aur oxygen ise marne nahi dega.

Nicole’s SQL based option list generator:
SELECT CONCAT('<option value=\"mc-itype:', itemtype, '\">',description,'</option>') FROM itemtypes

Our modification to the that make the output Javascript friendly:
SELECT CONCAT('<option value=\"mc-itype:', itemtype, '\">',description,'</option> \\') FROM itemtypes

In this case, turns out we have 5 itemtypes defined and we get this following output and we save it as CSV for introduction into our jquery.

<option value=”mc-itype:BBK”>Bengali Books</option>\
<option value=”mc-itype:BOOK”>Books</option>\
<option value=”mc-itype:BVOL”>Bound Volumes</option>\
<option value=”mc-itype:REF”>Reference Books</option>\
<option value=”mc-itype:SER”>Serials</option>\

(Hint: the exact item types is most likely to differ in your case; DO NOT copy-paste this output AS-IS.)

Let’s build the actual jQuery snippet

$( '<select name="limit" id="limitfiler" style="margin-left: 4px;"> \
<option value="">-- filter by item type --</option> \
<option value="mc-itype:BBK">Bengali Books</option> \
<option value="mc-itype:BOOK">Book</option> \
<option value="mc-itype:BVOL">Bound Volumes</option> \
<option value="mc-itype:REF">Reference Books</option> \
<option value="mc-itype:SER">Serials</option> \
</select>' ).insertAfter('#masthead_search');

And plug it into your opacuserjs system preference.

Let test our new drop-down!

add_itype_04
Fig 2: Searching for “Subject” as “English language” and no item-type based filtering
Fig 3: Additionally "BOOK" item type filter on.
Fig 3: Additionally “BOOK” item type filter on.
Fig 4: With REF itemtype filtering on.
Fig 4: With REF itemtype filtering on.

References:

[1] “Multi-Line JavaScript¬†Strings” by David Walsh

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.

def_iconset

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:

def_iconset_01

 

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

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.