1 .. include:: images.rst
6 This chapter shows how you can add various enhancements and customizations
7 in and around Koha by using mostly the existing configuration options.
9 .. _amazon-lookup-script-for-koha-libraries-label:
11 Amazon lookup script for Koha libraries
12 --------------------------------------------------------
14 We order most of our materials from Amazon, so I've been looking for a
15 convenient way to tell if a book under consideration is in our catalog
18 Greasemonkey & a custom user script fit the bill nicely:
20 - https://addons.mozilla.org/en-US/firefox/addon/748
22 - http://userscripts.org/scripts/show/56847
26 - Like most scripts, this one was designed to work with Firefox; I
27 haven't explored getting it to work with other browsers.
29 - I'm not a JavaScript programmer -- this was adapted from others'
30 work. Just a few lines would have to be changed to get the script to
31 work with your catalog.
33 - It depends on the existence of ISBN for the item in question, so
34 movies, older books, etc. would not work.
36 Others have added all sorts of bells & whistles: custom messages based on the status of items (on
37 order, on hold, etc.), ... just search the UserScripts site for Amazon +
38 library. For a later date!
40 .. _keyword-clouds-label:
43 -----------------------------------------
45 In addition to the traditional tag cloud available in Koha, there is a
46 way to generate clouds for popular subjects within Koha.
48 The :ref:`Author/Subject Cloud cron job <subject/author-clouds-label>` is used to help
49 with this process. This cron job sends its output to files.
51 - /home/koha/mylibrary/koharoot/koha-tmpl/cloud-author.html
53 - /home/koha/yourlibrary/koharoot/koha-tmpl/cloud-subject.html
55 This means that you can produce clouds for authors, collective author,
56 all kind of subjects, classifications, etc. And since it works on zebra
57 indexes, it is quick, even on large DBs. Tags clouds are sent to files.
58 It's up to library webmaster to deal with those files in order to
59 include them in :ref:`OPACMainUserBlock <opacmainuserblock-label>`, or include
60 them into their library CMS.
62 Some libraries even send the file into a Samba shared folder where
63 webmaster take them, eventually clean them a little bit before
64 integrating them into navigation widgets or pages.
66 .. _newest-titles-pulldown-label:
68 Newest Titles Pulldown
69 ---------------------------------------------
71 Often we want to add a way for our patrons to do searches for the newest
72 items. In this example I'll show you how to create a pull down menu of
73 the newest items by item type. These tips will work (with a couple
74 changes) for collection codes or shelving locations as well.
76 First, it's important to note that every link in Koha is a permanent
77 link. This means if I do a search for everything of a specific item type
78 sorted by the acquisitions date and bookmark that URL, whenever I click
79 it I'll see the newest items of that type on the first few pages of the
82 I took this knowledge and wrote a form takes this functionality in to
83 consideration. It basically just does a search of your Koha catalog for
84 a specific item type and sorts the results by acquisitions date.
86 The first thing I did was write a MySQL statement to generate a list of
87 item types for me - why copy and paste when you can use the power of
92 select concat('<option value=\"mc-itype:', itemtype, '\">',description,'</option>') from itemtypes
94 The above looks at the itemtypes table and slaps the necessary HTML
95 around each item type for me. I then exported that to CSV and opened it
96 in my text editor and added the other parts of the form.
100 <p><strong>New Items</strong></p>
101 <p><form name="searchform" method="get" action="/cgi-bin/koha/opac-search.pl">
102 <input name="idx" value="kw" type="hidden">
103 <input name="sort_by" value="acqdate_dsc" type="hidden">
104 <input name="do" value="OK" type="hidden">
105 <select name="limit" onchange="this.form.submit()">
106 <option>-- Please choose --</option>
107 <option value="mc-itype:BOOK">Book</option>
108 <option value="mc-itype:BOOKCD">Book on CD</option>
109 <option value="mc-itype:DVD">DVD</option>
110 <option value="mc-itype:LRG_PRINT">Large print book</option>
111 <option value="mc-itype:MAGAZINE">Magazine</option>
112 <option value="mc-itype:NEWSPAPER">Newspaper</option>
113 <option value="mc-itype:VIDEO">Videocassette</option>
118 Now, what does all of that mean? The important bits are these:
120 First the starting of the form.
124 <p><form name="searchform" method="get" action="/cgi-bin/koha/opac-search.pl">
126 This tells the browser to take any value selected and put it at the end
127 of this http://YOURSITE/cgi-bin/koha/opac-search.pl. If you want to
128 embed this form on your library website (and not on your OPAC) you can
129 put the full OPAC URL in there.
131 Next, there is a hidden value that is telling the search to sort by
132 acquisitions date descending (newest items at the top):
136 <input name="sort_by" value="acqdate_dsc" type="hidden">
138 And finally you have an option for each item type you want people to
143 <option value="mc-itype:BOOK">Book</option>
145 These options each include the string "mc-itype:" which tells Koha to do
148 Once you have all of that in place you can copy and paste the form to
149 somewhere on your OPAC. The `Farmington Public Libraries
150 OPAC <http://catalog.farmingtonlibraries.org>`__ has a few examples of
153 .. _new-titles-slider-for-opac-label:
155 New titles slider for OPAC
156 --------------------------
158 Often times libraries will want to add a flowing widget with new
159 materials at the library to their main public catalog page. To do this
160 you can use a widget from any number of services (usually for a cost) or
161 you can `enable plugins <#pluginsystem>`__ in Koha and use the `Cover
163 plugin <http://git.bywatersolutions.com/koha-plugins.git/shortlog/refs/heads/cover_flow>`__
164 which is based on the
165 `Flipster <https://github.com/drien/jquery-flipster>`__, a responsive
166 jQuery coverflow plugin.
168 Once the plugin is installed, the steps to get your coverflow to show up
171 First, you need to create one or more public reports for your coverflow
172 widget or widgets to be based on. This is how the plugin knows what the
173 content of your widget should contain. Each report needs only three
174 columns; title, biblionumber, and isbn. It is important that you have a
175 good and valid isbn, as that is the datum used to actually fetch the
176 cover. In the iteration of the plugin, we are using Amazon cover images,
177 but I believe in the end I will make the cover image fetcher
178 configurable so we can use any data source for cover image fetching.
180 Second, we need to configure the plugin. The plugin configuration is a
181 single text area that uses YAML ( actually, it’s JSON, whcih is a subset
182 of YAML ) to store the configuration options. In this example it looks
192 In this example, we are telling the plugin to use the report with id 42,
193 and use it to create a coverflow widget to replace the HTML element with
194 the id “coverflow”. The options list is passed directly to Flipster, so
195 any options supported by Flipster can be set from the plugin
196 configuration! In fact, in addition to the traditional coverflow,
197 Flipster has a “carousel” mode which is a much more compact version of
198 the coverflow. You can also configure which cover the widget will start
199 on, among other options.
201 At the time the plugins options are saved or updated, the plugin will
202 then generate some minified JavaScript code that is automatically stored
203 in the Koha system preference OPACUserJS. Here is an example of the
208 /* JS for Koha CoverFlow Plugin
209 This JS was added automatically by installing the CoverFlow plugin
210 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',});});});});
211 /* End of JS for Koha CoverFlow Plugin */
213 Why do this? For speed! Rather than regenerating this code each and
214 every time the page loads, we can generate it once, and use it over and
217 If you inspect the code closely, you’ll notice it references a script
218 “coverflow.pl”. This is a script that is included with the coverflow
219 plugin. Since we need to access this from the OPAC ( and we don’t want
220 to set off any XSS attack alarms ), we need to modify the web server
221 configuration for the public catalog and add the followup to it:
225 ScriptAlias /coverflow.pl "/var/lib/koha/mykoha/plugins/Koha/Plugin/Com/ByWaterSolutions/CoverFlow/coverflow.pl"
227 This line gives us access to the coverflow.pl script from the OPAC. This
228 script retrieves the report data and passes it back to the public
229 catalog for creating the coverflow widget. Koha::Cache is supported in
230 order to make the widget load as quickly as possible!
232 The final step is to put your selector element somewhere in your public
233 catalog. In this example, I put the following in the system preference
238 <span id="coverflow">Loading...</span>
240 Once that is in place, you need only refresh your OPAC page, and there
241 you have it, your very own catalog coverflow widget! Not only do these
242 coverflows look great on a computer screen, but they look great on
243 mobile platforms as well, and are even touch responsive!
247 .. _cataloging-and-searching-by-color-label:
249 Cataloging and Searching by Color
250 ----------------------------------------------------
252 One of the icon sets installed in Koha includes a series of colors. This
253 set can be used to catalog and search by color if you'd like. This guide
254 will walk you use changing collection code to color in Koha so that you
257 The following SQL could be used to add these colors to the CCODE
258 authorized value category in a batch. If you wanted to use these colors
259 for another authorized value you'd have to edit this to use that
264 insert into authorised_values (category, authorised_value, lib,
265 lib_opac, imageurl) values ('CCODE','000000','Black','','colors/000000.png');
266 insert into authorised_values (category, authorised_value, lib,
267 lib_opac, imageurl) values ('CCODE','66cc66','Bright Green','','colors/66cc66.png');
268 insert into authorised_values (category, authorised_value, lib,
269 lib_opac, imageurl) values ('CCODE','99cc33','Olive','','colors/99cc33.png');
270 insert into authorised_values (category, authorised_value, lib,
271 lib_opac, imageurl) values ('CCODE','3333cc','Dark Blue','','colors/3333cc.png');
272 insert into authorised_values (category, authorised_value, lib,
273 lib_opac, imageurl) values ('CCODE','006600' ,'Dark Green','','colors/006600.png');
274 insert into authorised_values (category, authorised_value, lib,
275 lib_opac, imageurl) values ('CCODE','6600cc','Plum','','colors/6600cc.png');
276 insert into authorised_values (category, authorised_value, lib,
277 lib_opac, imageurl) values ('CCODE','6666cc','Purple','','colors/6666cc.png');
278 insert into authorised_values (category, authorised_value, lib,
279 lib_opac, imageurl) values ('CCODE','9999cc','Light Purple','','colors/9999cc.png');
280 insert into authorised_values (category, authorised_value, lib,
281 lib_opac, imageurl) values ('CCODE','660000' ,'Burgundy','','colors/660000.png');
282 insert into authorised_values (category, authorised_value, lib,
283 lib_opac, imageurl) values ('CCODE','663333' ,'Brown','','colors/663333.png');
284 insert into authorised_values (category, authorised_value, lib,
285 lib_opac, imageurl) values ('CCODE','990000' ,'Red','','colors/990000.png');
286 insert into authorised_values (category, authorised_value, lib,
287 lib_opac, imageurl) values ('CCODE','996633' ,'Tan','','colors/996633.png');
288 insert into authorised_values (category, authorised_value, lib,
289 lib_opac, imageurl) values ('CCODE','999999' ,'Gray','','colors/999999.png');
290 insert into authorised_values (category, authorised_value, lib,
291 lib_opac, imageurl) values ('CCODE','cc66cc','Pink','','colors/cc66cc.png');
292 insert into authorised_values (category, authorised_value, lib,
293 lib_opac, imageurl) values ('CCODE','cc99cc','Bubble Gum','','colors/cc99cc.png');
294 insert into authorised_values (category, authorised_value, lib,
295 lib_opac, imageurl) values ('CCODE','cc3333' ,'Orange','','colors/cc3333.png');
296 insert into authorised_values (category, authorised_value, lib,
297 lib_opac, imageurl) values ('CCODE','cc6666' ,'Peach','','colors/cc6666.png');
298 insert into authorised_values (category, authorised_value, lib,
299 lib_opac, imageurl) values ('CCODE','cc9999' ,'Rose','','colors/cc9999.png');
300 insert into authorised_values (category, authorised_value, lib,
301 lib_opac, imageurl) values ('CCODE','cccc00' ,'Gold','','colors/cccc00.png');
302 insert into authorised_values (category, authorised_value, lib,
303 lib_opac, imageurl) values ('CCODE','ffff33' ,'Yellow','','colors/ffff33.png');
304 insert into authorised_values (category, authorised_value, lib,
305 lib_opac, imageurl) values ('CCODE','ffffcc','Cream','','colors/ffffcc.png');
306 insert into authorised_values (category, authorised_value, lib,
307 lib_opac, imageurl) values ('CCODE','ffffff','White','','colors/ffffff.png');
309 If you would like to choose the colors manually you can do that via the
310 :ref:`Authorized Values` administration area.
314 Next you'll want to :ref:`update the frameworks <marc-bibliographic-frameworks-label>` so
315 that the 952$8 (if you're using collection code) label to says Color.
317 Once you have that in place you can start to catalog items by color.
319 Finally you'll want to add the following JQuery to your preferences so
320 that it will relabel 'Collection' to 'Color'
322 :ref:`IntranetUserJS`
326 $(document).ready(function(){
327 $("#advsearch-tab-ccode a:contains('Collection')").text("Color");
328 $("#holdings th:contains('Collection')").text("Color");
335 $(document).ready(function(){
336 $("#advsearch-tab-ccode a:contains('Collection')").text("Color");
337 $('#item_ccode').text("Color");
341 .. _koha-search-on-your-site-label:
343 Using Koha as a Content Management System (CMS)
344 -----------------------------------------------
349 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
351 These are instructions for taking a default install of Koha and allowing
352 it to function as a little content management system. This will allow a
353 library to publish an arbitrary number of pages based on a template.
354 This example uses the template for the main opac page, but you could
355 just as well use any template you wish with a bit more editing. This may
356 be appropriate if you have a small library, want to allow librarians to
357 easily add pages, and do not want to support a complete CMS.
359 - Copy /usr/share/koha/opac/cgi-bin/opac/opac-main.pl to
360 /usr/share/koha/opac/cgi-bin/opac/pages.pl (in the same directory)
362 - Edit pages.pl in an editor
364 - At approximately line 33 change this code:
368 template_name => "opac-main.tt",
374 template_name => "pages.tt",
376 - At approximately line 62 after this code:
381 koha_news => $all_koha_news,
382 koha_news_count => $koha_news_count,
383 display_daily_quote => C4::Context->preference('QuoteOfTheDay'),
384 daily_quote => $quote,
391 my $page = "page_" . $input->param('p'); # go for "p" value in URL and do the concatenation
392 my $preference = C4::Context->preference($page); # Go for preference
393 $template->{VARS}->{'page_test'} = $preference; # pass variable to template pages.tt
395 - Note pages.pl file must have Webserver user execution permissions,
396 you can use `chmod <http://en.wikipedia.org/wiki/Chmod>`__ command if
397 you are actually logged in as such user:
403 - In the browser go to Home > Administration > System Preferences >
404 Local Use and add a New Preference called "page\_test"
408 - Explanation: test page for pages tiny cms
410 - Variable: page\_test
414 - Click the TextArea link (or enter "TextArea" into the input field
417 - variable options (last field): 80\|50
419 - In a browser go to http://youraddress/cgi-bin/koha/pages.pl?p=test
420 The page should come up with the words "Lorem ipsum" in the main
421 content area of the page. (replace "youraddress" with localhost,
422 127.0.0.1, or your domain name depending on how you have Apache set
425 - To add more pages simply create a system preference where the title
426 begins with "page\_" followed by any arbitrary letters. You can add
427 any markup you want as the value of the field. Reference the new page
428 by changing the value of the "p" parameter in the URL.
430 To learn more visit the Koha wiki page on this topic:
431 http://wiki.koha-community.org/wiki/Koha_as_a_CMS
433 .. _editing-the-pages-template-label:
435 Editing the pages template
436 ^^^^^^^^^^^^^^^^^^^^^^^^^^
439 /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/modules/opac-main.tt
441 /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/modules/pages.tt
444 /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/modules/pages.tt
446 - At approximately line 61, change this:
450 [% IF ( OpacMainUserBlock ) %]<div id="opacmainuserblock">[% OpacMainUserBlock %]</div>[% END %]
456 [% IF ( page_test ) %]<div id="opacmainuserblock">[% page_test %]</div>[% END %]
458 Remark: You may wish to disable your News block of these CMS style pages
459 e.g. when you do not want it displayed on the CMS style pages or where
460 the News block is long enough that it actually makes the 'page\_test'
461 include scroll outside the default viewport dimensions. In that case,
462 remove the following code from your pages.tt template.
466 [% IF ( koha_news_count ) %]
468 <table class="table table-bordered">
469 [% FOREACH koha_new IN koha_news %]
470 <thead><tr><th>[% koha_new.title %]</th></tr></thead>
471 <tbody><tr><td><p>[% koha_new.new %]</p>
472 <p class="newsfooter"><i>(published on [% koha_new.newdate %])</i></p></td></tr></tbody>
479 .. _troubleshooting-label:
482 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
484 If you have problems check file permissions on pages.pl and pages.tt.
485 They should have the same user and group as other Koha files like
488 .. _bonus-points-label:
491 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
493 Instead of using the address
494 http://youraddress/cgi-bin/koha/pages.pl?p=test you can shorten it to
495 http://youraddress/pages.pl?p=test Just open up
496 /etc/koha/koha-httpd.conf and add the follow at about line 13:
500 ScriptAlias /pages.pl "/usr/share/koha/opac/cgi-bin/opac/pages.pl"
507 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
509 After setting up Koha as a CMS you can create new pages following these
512 .. _adding-pages-label:
515 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
517 To add a new page you need to add a system preference under Local Use.
519 - Get there: More > Administration > Global System Preferences > Local
522 - Click 'New Preference'
524 - Enter in a description in the Explanation field
526 - Enter a value that starts with 'page\_' in the Variable field
528 - Enter starting HTML in the Value field
532 - Set the Variable Type to Textarea
534 - Set the Variable options to something like 20\|20 for 20 rows and 20
539 .. _viewing-your-page-label:
542 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
544 You can view your new page at
545 http://YOUR-OPAC/cgi-bin/koha/pages.pl?p=PAGENAME where PAGENAME is the
546 part you entered after 'page\_' in the Variable field.
552 This process can be used to create recommended reading lists within
553 Koha. So once the code changes have been made per the instructions on
554 'Koha as a CMS' you go through the 'Adding a New Page' instructions
555 above to great a page for 'Recommended Reading Lists'
559 Next we need to create pages for our various classes (or categories). To
560 do this, return to the 'Adding a New Page' section and create a
561 preference for the first class.
565 Next you'll want to link your first page to your new second page, go to
566 the page\_recommend preference and click 'Edit.' Now you want to edit
567 the HTML to include a link to your newest page:
571 .. _live-examples-label:
575 - The Crawford Library at Dallas Christian College is using this method
576 for their recommended reading lists: http://opac.dallas.edu/
578 Koha search on your site
579 -------------------------------------------
581 Often you'll want to add a Koha search box to your library website. To
582 do so, just copy and paste the following code in to your library website
583 and update the YOURCATALOG bit with your catalog's URL and you're set to
588 <form name="searchform" method="get" action="http://YOURCATLOG/cgi-bin/koha/opac-search.pl" id="searchform">
589 <input id="transl1" name="q" type="text"><p>
590 <select name="idx" id="masthead_search">
591 <option value="kw">Keyword</option>
592 <option value="ti">Title</option>
593 <option value="au">Author</option>
594 <option value="su">Subject</option>
595 <option value="nb">ISBN</option>
596 <option value="se">Series</option>
597 <option value="callnum">Call Number</option>
599 <input value="Search" id="searchsubmit" type="submit">