What I didn’t get to show at NAKUG ( covers that flow ) 28

I’ve been working on a plugin for CCFLS that I was planning to show at the Koha North American Users Group (NAKUG) meeting but didn’t get a chance to, so here it is!


Click to view animation

This is may take on a coverflow widget for Koha, implemented as a plugin! The title link at the bottom of each cover links to the record details for the given cover image.


Click to view animation

How does it work you might ask? Well, first, let me give props to the author of Flipster, the most excellent responsive jQuery coverflow plugin I have found! This is the library that I used for the basis of my plugin.

Once the plugin is installed, the steps to get your coverflow to show up are as follows:

First, you need to create one or more public reports for your coverflow widget or widgets to be based on. This is how the pluginknows what the content of your widget should contain. Each report needs only three columns; title, biblionumber, and isbn. It is important that you have a good and valid isbn, as that is the datum used to actually fetch the cover. In the iteration of the plugin, we are using Amazon cover images, but I believe in the end I will make the cover image fetcher configurable so we can use any data source for cover image fetching.

Second, we need to configure the plugin. The plugin configuration is a single text area that uses YAML ( actually, it’s JSON, whcih is a subset of YAML ) to store the configuration options. In this example it looks like this:

- id: 42
  selector: #coverflow
  style: coverflow

In this example, we are telling the plugin to use the report withid 42, and use it to create a coverflow widget to replace the HTML element with the id “coverflow”. The options list is passed directly to Flipster, so any options supported by Flipster can be set from the plugin configuration! In fact, in addition to the traditional coverflow, Flipster has a “carousel”mode which is a much more compact version of the coverflow. You can also configure which cover the widget will start on, among other options.

At the time the plugins options are saved or updated, the plugin will then generate some minified JavaScript code that is automatically stored in the Koha system preference OpacUserJS. Here is an example of the output:

/* JS for Koha CoverFlow Plugin 
 This JS was added automatically by installing the CoverFlow plugin
 Please do not modify */$(document).ready(function(){$.getScript("/plugin/Koha/Plugin/Com/ByWaterSolutions/CoverFlow/jquery-flipster/src/js/jquery.flipster.min.js",function(data,textStatus,jqxhr){$("head").append("<link id='flipster-css' href='/plugin/Koha/Plugin/Com/ByWaterSolutions/CoverFlow/jquery-flipster/src/css/jquery.flipster.min.css' type='text/css' rel='stylesheet' />");$('#coverflow').load("/coverflow.pl?id=42",function(){var opt={'items':'.item','minfactor':15,'distribution':1.5,'scalethreshold':0,'staticbelowthreshold':false,'titleclass':'itemTitle','selectedclass':'selectedItem','scrollactive':true,'step':{'limit':4,'width':10,'scale':true}};$('#coverflow').flipster({style:'coverflow',});});});});
/* End of JS for Koha CoverFlow Plugin */

Why do this? For speed! Rather than regenerating this code each and every time the page loads, we can generate it once, and use it over and over again.

If you inspect the code closely, you’ll notice it references a script “coverflow.pl”. This is a script that is included with the coverflow plugin. Since we need to access this from the OPAC ( and we don’t want to set off any XSS attack alarms ), we need to modify the web server configuration for the public catalog and add the followup to it:

ScriptAlias /coverflow.pl "/var/lib/koha/mykoha/plugins/Koha/Plugin/Com/ByWaterSolutions/CoverFlow/coverflow.pl"

This line gives us access to the coverflow.pl script from the OPAC. This script retrieves the report data and passes it back to the public catalog for creating the coverflow widget. Koha::Cache is supported in order to make the widget load as quickly as possible!

The final step is to put your selector element somewhere in your public catalog. In this example, I put the following in the system preference OpacMainUserBlock:

<span id="coverflow">Loading...</span>

Once that is in place, you need only refresh your OPAC page, and there you have it, your very own catalog coverflow widget! Not only do these coverflows look great on a computer screen, but they look great on mobile platforms as well, and are even touch responsive!

Keep an eye out on the ByWater Koha Plugins page, you should see it there soon!

Leave a comment

Your email address will not be published. Required fields are marked *

Are you human? * Time limit is exhausted. Please reload CAPTCHA.

28 thoughts on “What I didn’t get to show at NAKUG ( covers that flow )

  • Viktor Sarge

    This looks very interesting Kyle! How is work progressing?

    There is some work done currently to be able to work with multiple cover image sources in the Koha opac. Do you think this plugin will be able to benefit from that? For us over here in Sweden Amazon is not really such a great source of covers and we sort of need to use 2-3 of them to get decent coverage.

    Kind regards/Viktor

    • Kyle M Hall

      Work on it is progressing steadily! It’s really totally functional out of the box. However, if you want to use a different cover source than amazon it would need some minor tweaks. I’d really like it to support all the cover image sources Koha supports. However, at the moment they are implemented at the template level, so there’s nothing I can reference in my plugin. At the moment, it’s just a copy/paste affair. I’ll keep an eye on the multi-source cover images and see if it’s something I can make use of! It would really be nice for the plugin to just automatically use the same source/sources that the Koha installation is already set to use!

      • Viktor Sarge

        Great news Kyle – thanks for the swift reply! I’ll keep watching the ByWater plugins page then. Interesting to hear there is no current way to hook into the cover sources supported by Koha, but a little tweaking is ok by me.

  • Christopher Brannon

    Kyle, this is excellent news. I can’t wait to see this in production. 🙂 I have been tinkering with my own flavor of this project based off the public reports as well. Unfortunately I hit limitations with running code from our own server. Having something on the Koha server side wil definitely reduce some barriers. Looking forward to this one.


  • Lennon Mazonde

    Hi Kyle,

    I am keen to implement this coverflow widget/plugin(I’m customising my OPAC) but i’m quite the noob at this stuff. I’ve managed to plugins in Koha, but i’m stuck at the very first step- how to install the Jquery Flipster plugin.

    May you please be kind enough to give me a detailed step-by-step how-to? I would appreciate that a lot, thanks!!

      • Abdou

        Hello Kyle,
        I’m interested in this plugin, It’s very nice, But i need to know how to implement this report in details and where’s its place, If you have an example for that please send it for me.

          • Abdou

            Thanks Nicole,
            Now I’ve understood you, You mean sql report in saved reports, I’ve already made one, its ID is 50 and i’ve attached it in configuration panel but there’s no result also,
            this my report

            SELECT title,biblionumber ,isbn
            (SELECT i.holdingbranch,b.biblionumber,ExtractValue(marcxml,’//datafield[@tag=”245″]/subfield[@code>=”a”]’)
            AS title,b.isbn FROM biblioitems b LEFT JOIN items i USING (biblionumber))
            AS subjects WHERE (isbn !=”NULL”) AND title LIKE (“%math%”) GROUP BY biblionumber

            also i couldn’t run the report from plugins link called Run report, but i can run it from saved reports correctly


          • Nicole C. Engard


            SELECT b.biblionumber, b.title, m.isbn 
            FROM biblio b left join biblioitems m on (b.biblionumber=m.biblionumber) where
            m.isbn is not NULL and b.title LIKE "%math%"

            Also – it might be better to put this conversation on the Koha mailing list so that more people can help out here.

          • Abdou

            Thanks Nicole,
            I’ve applied your suggestion but also this message appeared

            Software error:

            There is no such report.
            Although the report is public and its id is correct.

          • Nicole C. Engard

            I’m sorry, you are now past my area of expertise. I think the best thing to do is email the mailing list for some additional help. Good luck!

  • Aaron Sakovich

    Dude, this seriously rocks. Any ideas how hard it would be to do this with Content Café? And what about using a book list (or multiple selectable ones) instead of just pulling from a report?
    This is brilliant. Thanks for all of your work on the plugins!

    • Kyle M Hall

      It really depends on how we can get covers from content cafe. If we can get them by ISBN I’m sure we could add support for that. It should be trivial to use a book list for this, as we can just write a report that uses a given book list!

  • Craig

    Hi all,

    Fantastic plugin! Thank you for the work on it!

    Running: Koha 3.20 on Ubuntu 14.04 LTS (VPS). Package install.


    Can someone point me to the file in which I should insert the Script Alias? Does “web server configuration” above mean .conf file at /etc/apache2/sites-available/ ? Not sure where to put this line of code.

    Thanks all!


  • Fred

    I’m trying to install coverflow, but Koha’s plugin upload page wants a kpz file, which I can’t find anywhere. Either I’m missing something right in front of me, or it’s hiding somewhere. Can you point me in the right direction?

      • Fred

        Thanks! Now I have a new and exciting problem: I downloaded the file, uploaded it and configured it, and couldn’t get it to work. It looked like some directory paths didn’t match up, so I tried uninstalling it with the intention of reinstalling. Now it’s saying “Cannot unpack file to the plugins directory. Please verify that the Apache user can write to the plugins directory.” AFAIK, I didn’t change anything between the time I uninstalled it and tried to reinstall, so I’m not sure what’s up. Any ideas?

  • Marjorie

    I installed plugin in Koha 3.18 but i have a software error when i try to configure it.
    “Template process failed: file error – doc-head-open.inc: not found at /home/i/git/koha-rosemont-dev-ccsr/C4/Templates.pm line 129.”

    Do you have any idea what happens?


  • Erwin

    Good day everyone, i already follow the steps given by kyle, and yet i still have a problem with the coverflow plugins, i successfully installed and configured it with the given id (based on report module id), and when i check the “opacuserjs” and “opacusercss”, the script which is expected to be here is not added, i would like to ask if you have encounter this problem, i also added this script to apache-shared-opac.conf (ScriptAlias /coverflow.pl “/var/lib/koha/mykoha/plugins/Koha/Plugin/Com/ByWaterSolutions/CoverFlow/coverflow.pl”)
    i am using koha 16.05 by the way, thanks!