Removed other XISBN references as this service is no longer offered by OCLC
[kohadocs.git] / source / extending_koha.rst
1 .. include:: images.rst
2
3 Extending Koha
4 ==================
5
6 This chapter shows how you can add various enhancements and customizations
7 in and around Koha by using mostly the existing configuration options.
8
9 .. _amazon-lookup-script-for-koha-libraries-label:
10
11 Amazon lookup script for Koha libraries
12 --------------------------------------------------------
13
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
16 already.
17
18 Greasemonkey & a custom user script fit the bill nicely:
19
20 -  https://addons.mozilla.org/en-US/firefox/addon/748
21
22 -  http://userscripts.org/scripts/show/56847
23
24 A few caveats:
25
26 -  Like most scripts, this one was designed to work with Firefox; I
27    haven't explored getting it to work with other browsers.
28
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.
32
33 -  It depends on the existence of ISBN for the item in question, so
34    movies, older books, etc. would not work.
35
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!
39
40 .. _keyword-clouds-label:
41
42 Keyword Clouds
43 -----------------------------------------
44
45 In addition to the traditional tag cloud available in Koha, there is a
46 way to generate clouds for popular subjects within Koha.
47
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.
50
51 -  /home/koha/mylibrary/koharoot/koha-tmpl/cloud-author.html
52
53 -  /home/koha/yourlibrary/koharoot/koha-tmpl/cloud-subject.html
54
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.
61
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.
65
66 .. _newest-titles-pulldown-label:
67
68 Newest Titles Pulldown
69 ---------------------------------------------
70
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.
75
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
80 results.
81
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.
85
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
88 MySQL?
89
90 ::
91
92     select concat('<option value=\"mc-itype:', itemtype, '\">',description,'</option>') from itemtypes
93
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.
97
98 ::
99
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>
114     </select>
115     </form>
116     </p>
117
118 Now, what does all of that mean? The important bits are these:
119
120 First the starting of the form.
121
122 ::
123
124     <p><form name="searchform" method="get" action="/cgi-bin/koha/opac-search.pl">
125
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.
130
131 Next, there is a hidden value that is telling the search to sort by
132 acquisitions date descending (newest items at the top):
133
134 ::
135
136     <input name="sort_by" value="acqdate_dsc" type="hidden">
137
138 And finally you have an option for each item type you want people to
139 search.
140
141 ::
142
143     <option value="mc-itype:BOOK">Book</option>
144
145 These options each include the string "mc-itype:" which tells Koha to do
146 an item type search.
147
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
151 this on the left.
152
153 .. _new-titles-slider-for-opac-label:
154
155 New titles slider for OPAC
156 --------------------------
157
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
162 Flow
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.
167
168 Once the plugin is installed, the steps to get your coverflow to show up
169 are as follows:
170
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.
179
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
183 like this:
184
185 ::
186
187     - id: 42
188       selector: #coverflow
189       options:
190       style: coverflow
191
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.
200
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
204 output:
205
206 ::
207
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 */
212
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
215 over again.
216
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:
222
223 ::
224
225     ScriptAlias /coverflow.pl "/var/lib/koha/mykoha/plugins/Koha/Plugin/Com/ByWaterSolutions/CoverFlow/coverflow.pl"
226
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!
231
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
234 OpacMainUserBlock:
235
236 ::
237
238     <span id="coverflow">Loading...</span>
239
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!
244
245 |image1316|
246
247 .. _cataloging-and-searching-by-color-label:
248
249 Cataloging and Searching by Color
250 ----------------------------------------------------
251
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
255 can do this.
256
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
260 category:
261
262 ::
263
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');
308
309 If you would like to choose the colors manually you can do that via the
310 :ref:`Authorized Values` administration area.
311
312 |image1118|
313
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.
316
317 Once you have that in place you can start to catalog items by color.
318
319 Finally you'll want to add the following JQuery to your preferences so
320 that it will relabel 'Collection' to 'Color'
321
322 :ref:`IntranetUserJS`
323
324 ::
325
326     $(document).ready(function(){
327         $("#advsearch-tab-ccode a:contains('Collection')").text("Color");
328         $("#holdings th:contains('Collection')").text("Color");
329         });
330
331 :ref:`OPACUserJS`
332
333 ::
334
335     $(document).ready(function(){
336         $("#advsearch-tab-ccode a:contains('Collection')").text("Color");
337         $('#item_ccode').text("Color");
338         });
339
340
341 .. _koha-search-on-your-site-label:
342
343 Using Koha as a Content Management System (CMS)
344 -----------------------------------------------
345
346 .. _setup-label:
347
348 Setup
349 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
350
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.
358
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)
361
362 -  Edit pages.pl in an editor
363
364 -  At approximately line 33 change this code:
365
366    ::
367
368        template_name  => "opac-main.tt",
369
370 -  To this code:
371
372    ::
373
374        template_name  => "pages.tt",
375
376 -  At approximately line 62 after this code:
377
378    ::
379
380        $template->param(
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,
385                   );
386
387 -  Add these lines:
388
389    ::
390
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
394
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:
398
399    ::
400
401                $chmod 755 pages.pl
402
403 -  In the browser go to Home > Administration > System Preferences >
404    Local Use and add a New Preference called "page\_test"
405
406 -  Fill it out as so
407
408    -  Explanation: test page for pages tiny cms
409
410    -  Variable: page\_test
411
412    -  Value: Lorem ipsum
413
414    -  Click the TextArea link (or enter "TextArea" into the input field
415       below it)
416
417    -  variable options (last field): 80\|50
418
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
423    up.)
424
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.
429
430 To learn more visit the Koha wiki page on this topic:
431 http://wiki.koha-community.org/wiki/Koha_as_a_CMS
432
433 .. _editing-the-pages-template-label:
434
435 Editing the pages template
436 ^^^^^^^^^^^^^^^^^^^^^^^^^^
437
438 -  Copy
439    /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/modules/opac-main.tt
440    to
441    /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/modules/pages.tt
442
443 -  Edit
444    /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/modules/pages.tt
445
446 -  At approximately line 61, change this:
447
448    ::
449
450                [% IF ( OpacMainUserBlock ) %]<div id="opacmainuserblock">[% OpacMainUserBlock %]</div>[% END %]
451
452 -  To this:
453
454    ::
455
456                [% IF ( page_test ) %]<div id="opacmainuserblock">[% page_test %]</div>[% END %]
457
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.
463
464 ::
465
466                       [% IF ( koha_news_count ) %]
467                           <div id="news">
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>
473                           [% END %]
474                           </table>
475                           </div>
476                          [% END %]
477
478
479 .. _troubleshooting-label:
480
481 Troubleshooting
482 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
483
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
486 opac-main.pl.
487
488 .. _bonus-points-label:
489
490 Bonus Points
491 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
492
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:
497
498 ::
499
500     ScriptAlias /pages.pl "/usr/share/koha/opac/cgi-bin/opac/pages.pl"
501
502 Then restart Apache.
503
504 .. _usage-label:
505
506 Usage
507 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
508
509 After setting up Koha as a CMS you can create new pages following these
510 instructions:
511
512 .. _adding-pages-label:
513
514 Adding Pages
515 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
516
517 To add a new page you need to add a system preference under Local Use.
518
519 -  Get there: More > Administration > Global System Preferences > Local
520    Use
521
522 -  Click 'New Preference'
523
524 -  Enter in a description in the Explanation field
525
526 -  Enter a value that starts with 'page\_' in the Variable field
527
528 -  Enter starting HTML in the Value field
529
530    |image1076|
531
532 -  Set the Variable Type to Textarea
533
534 -  Set the Variable options to something like 20\|20 for 20 rows and 20
535    columns
536
537    |image1077|
538
539 .. _viewing-your-page-label:
540
541 Viewing your page
542 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
543
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.
547
548 .. _example-label:
549
550 **Example**
551
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'
556
557 |image1078|
558
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.
562
563 |image1079|
564
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:
568
569 |image1080|
570
571 .. _live-examples-label:
572
573 **Live Examples**
574
575 -  The Crawford Library at Dallas Christian College is using this method
576    for their recommended reading lists: http://opac.dallas.edu/
577
578 Koha search on your site
579 -------------------------------------------
580
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
584 go.
585
586 ::
587
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>
598     </select>
599     <input value="Search" id="searchsubmit" type="submit">
600     </p></form>