LP#1240207: Spellchecked the docs
[working/Evergreen.git] / docs / admin_initial_setup / designing_your_catalog.txt
1 Designing your catalog
2 ======================
3
4 When people want to find things in your Evergreen system, they will check the
5 catalog. In Evergreen, the catalog is made available through a web interface,
6 called the _OPAC_ (Online Public Access Catalog). In the latest versions of the
7 Evergreen system, the OPAC is built on a set of programming modules called the
8 Template Toolkit. You will see the OPAC sometimes referred to as the _TPAC_.
9
10 In this chapter, we'll show you how to customize the OPAC, change it from its
11 default configuration, and make it your own.
12
13 Configuring and customizing the public interface
14 ------------------------------------------------
15
16 The public interface is referred to as the TPAC or Template Toolkit (TT) within
17 the Evergreen community. The template toolkit system allows you to customize the
18 look and feel of your OPAC by editing the template pages (.tt2) files as well as
19 the associated style sheets.   
20
21 Locating the default template files
22 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
23
24 The default URL for the TPAC on a default Evergreen system is
25 _http://localhost/eg/opac/home_ (adjust _localhost_ to match your hostname or IP
26 address).
27
28 The default template file is installed in _/openils/var/templates/opac_.
29
30 You should generally avoid touching the installed default template files, unless
31 you are contributing changes for Evergreen to adopt as a new default. Even then,
32 while you are developing your changes, consider using template overrides rather
33 than touching the installed templates until you are ready to commit the changes
34 to a branch. See below for information on template overrides.
35
36 Mapping templates to URLs
37 ~~~~~~~~~~~~~~~~~~~~~~~~~
38
39 The mapping for templates to URLs is straightforward. Following are a few
40 examples, where _<templates>_ is a placeholder for one or more directories that
41 will be searched for a match:
42
43 * _http://localhost/eg/opac/home => /openils/var/<templates>/opac/home.tt2_
44 * _http://localhost/eg/opac/advanced =>
45 /openils/var/<templates>/opac/advanced.tt2_
46 * _http://localhost/eg/opac/results => 
47 /openils/var/<templates>/opac/results.tt2_
48
49 The template files themselves can process, be wrapped by, or include other
50 template files. For example, the _home.tt2_ template currently involves a number
51 of other template files to generate a single HTML file.
52
53 Example Template Toolkit file: _opac/home.tt2_.
54 ----
55 [%  PROCESS "opac/parts/header.tt2";
56     WRAPPER "opac/parts/base.tt2";
57     INCLUDE "opac/parts/topnav.tt2";
58     ctx.page_title = l("Home") %]
59     <div id="search-wrapper">
60       [% INCLUDE "opac/parts/searchbar.tt2" %]
61     </div>
62     <div id="content-wrapper">
63         <div id="main-content-home">
64              <div class="common-full-pad"></div>
65              [% INCLUDE "opac/parts/homesearch.tt2" %]
66              <div class="common-full-pad"></div>
67         </div>
68      </div>
69 [% END %]
70 ----
71 Note that file references are relative to the top of the template directory.
72
73 How to override template files
74 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75
76 Overrides for template files or TPAC pages go in a directory that parallels the
77 structure of the default templates directory. The overrides then get pulled in
78 via the Apache configuration.
79
80 The following example demonstrates how to create a file that overrides the
81 default "Advanced search page" (_advanced.tt2_) by adding a new 
82 _templates_custom_ directory and editing the new file in that directory.
83
84 ----
85 bash$ mkdir -p /openils/var/templates_custom/opac
86 bash$ cp /openils/var/templates/opac/advanced.tt2 \
87          /openils/var/templates_custom/opac/.
88 bash$ vim /openils/var/templates_custom/opac/advanced.tt2
89 ----
90
91 Configuring the custom templates directory in Apache's eg.conf
92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93
94 You now need to teach Apache about the new custom template directory. Edit
95 _/etc/apache2/sites-available/eg.conf_ and add the following _<Location /eg>_
96 element to each of the _<VirtualHost>_ elements in which you want to include the
97 overrides. The default Evergreen configuration includes a VirtualHost directive
98 for port 80 (HTTP) and another one for port 443 (HTTPS); you probably want to
99 edit both, unless you want the HTTP user experience to be different from the
100 HTTPS user experience.
101
102 ----
103 <VirtualHost *:80>
104     # <snip>
105
106     # - absorb the shared virtual host settings
107     Include eg_vhost.conf
108     <Location /eg>
109         PerlAddVar OILSWebTemplatePath "/openils/var/templates_custom"
110     </Location>
111
112     # <snip>
113 </VirtualHost>
114 ----
115
116 Finally, reload the Apache configuration to pick up the changes. You should now
117 be able to see your change at _http://localhost/eg/opac/advanced_ where
118 _localhost_ is the hostname of your Evergreen server.
119
120 Adjusting colors for your public interface
121 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
122
123 You may adjust the colors of your public interface by editing the _colors.tt2_
124 file. The location of this file is in 
125 _/openils/var/templates/opac/parts/css/colors.tt2_. When you customize the
126 colors of your public interface, remember to create a custom file in your custom
127 template folder and edit the custom file and not the file located in you default
128 template.    
129
130 Adjusting fonts in your public interface
131 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
132
133 Font sizes can be changed in the _colors.tt2_ file located in
134 _/openils/var/templates/opac/parts/css/_. Again, create and edit a custom
135 template version and not the file in the default template.
136
137 Other aspects of fonts such as the default font family can be adjusted in
138 _/openils/var/templates/opac/css/style.css.tt2_. 
139
140 Media file locations in the public interface
141 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
142 The media files (mostly PNG images) used by the default TPAC templates are stored
143 in the repository in _Open-ILS/web/images/_ and installed in
144 _/openils/var/web/images/_.
145
146 Changing some text in the public interface
147 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
148
149 Out of the box, TPAC includes a number of placeholder text and links. For
150 example, there is a set of links cleverly named Link 1, Link 2, and so on in the
151 header and footer of every page in TPAC. Here is how to customize that for a 
152 _custom templates_ skin.
153
154 To begin with, find the page(s) that contain the text in question. The simplest
155 way to do that is with the grep -s command. In the following example, search for
156 files that contain the text "Link 1":
157
158 ----
159 bash$ grep -r "Link 1" /openils/var/templates/opac
160 /openils/var/templates/opac/parts/topnav_links.tt2
161 4:            <a href="http://example.com">[% l('Link 1') %]</a>
162 ----
163
164
165 Next, copy the file into our overrides directory and edit it with vim.
166
167 Copying the links file into the overrides directory.
168
169 ----
170 bash$ cp /openils/var/templates/opac/parts/topnav_links.tt2 \
171 /openils/var/templates_custom/opac/parts/topnav_links.tt2
172 bash$ vim /openils/var/templates_custom/opac/parts/topnav_links.tt2
173 ----
174
175 Finally, edit the link text in _opac/parts/header.tt2_. Content of the
176 _opac/parts/header.tt2_ file.
177
178 ----
179 <div id="gold-links-holder">
180     <div id="gold-links">
181         <div id="header-links">
182             <a href="http://example.com">[% l('Link 1') %]</a>
183             <a href="http://example.com">[% l('Link 2') %]</a>
184             <a href="http://example.com">[% l('Link 3') %]</a>
185             <a href="http://example.com">[% l('Link 4') %]</a>
186             <a href="http://example.com">[% l('Link 5') %]</a>
187         </div>
188     </div>
189 </div>
190 ----
191
192 For the most part, the page looks like regular HTML, but note the _[%_(" ")%]_
193 that surrounds the text of each link. The _[% ... %]_ signifies a TT block, 
194 which can contain one or more TT processing instructions. l(" ... "); is a
195 function that marks text for localization (translation); a separate process can
196 subsequently extract localized text as GNU gettext-formatted PO (Portable
197 Object) files.
198
199 As Evergreen supports multiple languages, any customization to Evergreen's
200 default text must use the localization function. Also, note that the
201 localization function supports placeholders such as [_1], [_2] in the text;
202 these are replaced by the contents of variables passed as extra arguments to the
203 l() function.
204
205 Once the link and link text has been edited to your satisfaction, load the page
206 in a Web browser and see the live changes immediately.
207
208 Adding and removing MARC fields from the record details display page
209 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
210
211 It is possible to add and remove the MARC fields and subfields displayed in the
212 record details page.  In order to add MARC fields to be displayed on the details
213 page of a record, you will need to map the MARC code to variables in the
214 _/openils/var/templates/opac/parts/misc_util.tt2 file_.
215
216 For example, to map the template variable _args.pubdates_ to the date of
217 publication MARC field 260, subfield c, add these lines to _misc_util.tt2_:
218
219 ----
220 args.pubdates = [];
221 FOR sub IN xml.findnodes('//*[@tag="260"]/*[@code="c"]');
222     args.pubdates.push(sub.textContent);
223 END;
224 args.pubdate = (args.pubdates.size) ? args.pubdates.0 : ''
225 ----
226
227 You will then need to edit the 
228 _/openils/var/templates/opac/parts/record/summary.tt2_ file in  order to get the
229 template variable for the MARC field to display.
230
231 For example, to display the date of publication code you created in the
232 _misc_util.tt2_ file, add these lines:
233
234 ----
235 [% IF attrs.pubdate; %]
236     <span itemprop="datePublished">[% attrs.pubdate | html; %]</span>
237 [% END; %]
238 ----
239
240 You can add any MARC field to your record details page. Moreover, this approach
241 can also be used to display MARC fields in other pages, such as your results
242 page.
243
244 Setting the default physical location for your library environment
245 ------------------------------------------------------------------
246
247 _physical_loc_ is an Apache environment variable that sets the default physical
248 location, used for setting search scopes and determining the order in which
249 copies should be sorted. This variable is set in
250 _/etc/apache2/sites-available/eg.conf_. The following example demonstrates the
251 default physical location being set to library ID 104:
252
253 ----
254 SetEnv physical_loc 104
255 ----
256
257 Setting a default language and adding optional languages
258 --------------------------------------------------------
259
260 _OILSWebLocale_ adds support for a specific language. Add this variable to the
261 Virtual Host section in _/etc/apache2/sites-available/eg.conf_.
262
263 _OILSWebDefaultLocale_ specifies which locale to display when a user lands on a
264 page in TPAC and has not chosen a different locale from the TPAC locale picker.
265 The following example shows the _fr_ca_ locale being added to the locale picker
266 and being set as the default locale:
267
268 ----
269 PerlAddVar OILSWebLocale "fr_ca"
270 PerlAddVar OILSWebLocale "/openils/var/data/locale/fr-CA.po"
271 PerlAddVar OILSWebDefaultLocale "fr-CA"
272 ----
273
274 Below is a table of the currently supported languages packaged with Evergreen:
275
276 [options="header"]
277 |================================================================
278 |Language| Code| PO file
279 |Czech| cs_cz| /openils/var/data/locale/cs-CZ.po
280 |English - Canada| en_ca| /openils/var/data/locale/en-CA.po
281 |English - Great Britain| en_gb| /openils/var/data/locale/en-GB.po
282 |*English - United States| en_us| not applicable
283 |French - Canada| fr_ca| /openils/var/data/locale/fr-CA.po
284 |Portuguese - Brazil| pt_br| /openils/var/data/locale/pt_BR.po
285 |Russian| ru_ru| /openils/var/data/locale/ru_RU.po
286 |=================================================================
287 *American English is built into Evergreen so you do not need to set up this
288 language and there are no PO files. 
289
290 Editing the formats select box options in the search interface.
291 ---------------------------------------------------------------
292
293 You may wish to remove, rename or organize the options in the formats select
294 box. This can be accomplished from the staff client.
295
296 . From the staff client, navigate to *Admin > Server Administration > Marc Coded
297 Value Maps* 
298 . Select _Type_ from the *Record Attribute Type* select box.
299 . Double click on the format type you wish to edit.
300
301 To change the label for the type, enter a value in the *Search Label* field.
302
303 To  move the option to a top list separated by a dashed line from the others,
304 check the *Is Simple Selector* check box.
305
306 To hide the type so that it does not appear in the search interface, uncheck the
307 *OPAC Visible* checkbox.
308
309 Changes will be immediate.
310
311 Adding and removing search fields in advanced search
312 -----------------------------------------------------
313
314 It is possible to add and remove search fields on the advanced search page by
315 editing the _opac/parts/config.tt2_ file in your template directory. Look for
316 this section of the file:
317
318 ----
319 search.adv_config = [
320     {adv_label => l("Item Type"), adv_attr => ["mattype", "item_type"]},
321     {adv_label => l("Item Form"), adv_attr => "item_form"},
322     {adv_label => l("Language"),  adv_attr => "item_lang"},
323     {adv_label => l("Audience"),  adv_attr => ["audience_group", "audience"], adv_break => 1},
324     {adv_label => l("Video Format"), adv_attr => "vr_format"},
325     {adv_label => l("Bib Level"), adv_attr => "bib_level"},
326     {adv_label => l("Literary Form"), adv_attr => "lit_form", adv_break => 1},
327     {adv_label => l("Search Library"), adv_special => "lib_selector"},
328     {adv_label => l("Publication Year"), adv_special => "pub_year"},
329     {adv_label => l("Sort Results"), adv_special => "sort_selector"},
330 ];
331 ----
332
333 For example, if you delete the line:
334
335 ----
336 {adv_label => l("Language"),  adv_attr => "item_lang"},
337 ----
338
339 the language field will no longer appear on your advanced search page. Changes
340 will appear immediately after you save your changes.
341
342 Changing the display of facets and facet groups
343 -----------------------------------------------
344
345 Facets can be reordered on the search results page by editing the
346 _opac/parts/config.tt2_ file in your template directory.  
347
348 Edit the following section of _config.tt2_, changing the order of the facet
349 categories according to your needs:
350
351 ----
352
353 facet.display = [
354     {facet_class => 'author',  facet_order => ['personal', 'corporate']},
355     {facet_class => 'subject', facet_order => ['topic']},
356     {facet_class => 'series',  facet_order => ['seriestitle']},
357     {facet_class => 'subject', facet_order => ['name', 'geographic']}
358 ];
359
360 ----
361
362 You may also change the default number of facets appearing under each category
363 by editing the _facet.default_display_count_ value in _config.tt2_. The default 
364 value is 5.
365
366 Including external content in your public interface
367 ---------------------------------------------------
368
369 The public interface allows you to include external services and content in your
370 public interface. These can include book cover images, user reviews, table of
371 contents, summaries, author notes, annotations, user suggestions, series
372 information among other services. Some of these services are free while others
373 require a subscription.    
374
375 The following are some of the external content services which you can configure
376 in Evergreen.
377
378 OpenLibrary
379 ~~~~~~~~~~~
380
381 The default install of Evergreen includes OpenLibrary book covers. The settings
382 for this are controlled by the <added_content> section of
383 _/openils/conf/opensrf.xml_. Here are the key elements of this configuration:
384
385 ----
386 <module>OpenILS::WWW::AddedContent::OpenLibrary</module>
387 ----
388
389 This section calls the OpenLibrary perl module. If you wish to link to a
390 different book cover service other than OpenLibrary, you must refer to the
391 location of the corresponding Perl module. You will also need to change other
392 settings accordingly.
393
394 ----
395 <timeout>1</timeout>
396 ----
397
398 Max number of seconds to wait for an added content request to return data. Data 
399 not returned within the timeout is considered a failure.
400 ----
401 <retry_timeout>600</retry_timeout>
402 ----
403
404 This setting is the amount of time to wait before we try again.
405
406 ----
407 <max_errors>15</max_errors>
408 ----
409
410 Maximum number of consecutive lookup errors a given process can have before
411 added content lookups are disabled for everyone. To adjust the site of the cover
412 image on the record details page edit the config.tt2 file and change the value
413 of the record.summary.jacket_size. The default value is "medium" and the
414 available options are "small", "medium" and "large."   
415
416 ChiliFresh
417 ~~~~~~~~~~
418
419 ChiliFresh is a subscription-based service which allows book covers, reviews and
420 social interaction of patrons to appear in your catalog. To activate ChiliFresh,
421 you will need to open the Apache configuration file _/etc/apache2/eg_vhost.conf_
422 and edit several lines:
423
424 . Uncomment (remove the "#" at the beginning of the line) and add your ChiliFresh
425 account number:
426
427 ----
428 #SetEnv OILS_CHILIFRESH_ACCOUNT
429 ----
430
431 . Uncomment this line and add your ChiliFresh Profile:
432
433 ----
434 #SetEnv OILS_CHILIFRESH_PROFILE
435 ----
436
437 Uncomment the line indicating the location of the Evergreen JavaScript for
438 ChiliFresh:
439
440 ----
441 #SetEnv OILS_CHILIFRESH_URL http://chilifresh.com/on-site /js/evergreen.js
442 ----
443
444 . Uncomment the line indicating the secure URL for the Evergreen JavaScript :
445
446 ----
447 #SetEnv OILS_CHILIFRESH_HTTPS_URL https://secure.chilifresh.com/on-site/js/evergreen.js
448 ----
449
450 [id="_content_cafe"]
451 Content Café
452 ~~~~~~~~~~~~
453
454 Content Café is a subscription-based service that can add  jacket images,
455 reviews, summaries, tables of contents and book details to your records.
456
457 In order to activate Content Café, edit the _/openils/conf/opensrf.xml_ file and
458 change the _<module>_ element to point to the ContentCafe Perl Module:
459
460 ----
461 <module>OpenILS::WWW::AddedContent::ContentCafe</module>
462 ----
463
464 To adjust settings for Content Café, edit a couple of fields with the
465 _<ContentCafe>_ Section of _/openils/conf/opensrf.xml_.
466
467 Edit the _userid_ and _password_ elements to match the user id and password for
468 your Content Café account.
469
470 Change the _return_behavior_on_no_jacket_image_ to set the behavior of your
471 service when an image is not available for an item. By default this value is set
472 to T which will result in a small image with the text "No Image Available" in
473 place of a book cover. If you set this value to 1 a 1X1 blank image will be in
474 place of a book cover. 
475
476 Google Analytics
477 ~~~~~~~~~~~~~~~~
478
479 Google Analytics is a free service to collect statistics for your Evergreen
480 site.  In order to use Google Analytics you will first need to set up the
481 service from the Google Analytics website at http://www.google.com/analytics/.
482 To activate Google Analytics you will need to edit _config.tt2_ in your
483 template. To enable the service set the value of google_analytics.enabled to
484 true and change the value of _google_analytics.code_ to be the code in your
485 Google Analytics account.
486
487 NoveList
488 ~~~~~~~~
489
490 Novelist is a subscription-based service providing reviews and recommendation
491 for books in you catalog. To activate your Novelist service in Evergreen, open
492 the Apache configuration file _/etc/apache2/eg_vhost.conf_ and edit the line:
493
494 ----
495 #SetEnv OILS_NOVELIST_URL
496 ----
497
498 You should use the URL provided by NoveList.
499
500 RefWorks
501 ~~~~~~~~
502
503 RefWorks is a subscription-based online bibliographic management tool. If you
504 have a RefWorks subscription, you can activate RefWorks in Evergreen by editing
505 the _config.tt2_ file located in your template directory. You will need to set
506 the _ctx.refworks.enabled_ value to _true_. You may also set the RefWorks URL by
507 changing the _ctx.refworks.url_ setting on the same file. 
508
509 SFX OpenURL resolver
510 ~~~~~~~~~~~~~~~~~~~~
511
512 An OpenURL resolver allows you to find electronic resources and pull them into
513 your catalog based on the ISBN or ISSN of the item. In order to use the SFX
514 OpenURL resolver, you will need to subscribe to the Ex Libris SFX service.  To
515 activate the service in Evergreen edit the _config.tt2_ file in your template.
516 Enable the resolver by changing the value of _openurl.enabled_ to _true_ and
517 change the _openurl.baseurl_ setting to point to the URL of your OpenURL
518 resolver. 
519
520 Syndetic Solutions
521 ~~~~~~~~~~~~~~~~~~
522
523 Syndetic Solutions is a subscription service providing book covers and other
524 data for items in your catalog. In order to activate Syndetic, edit the
525 _/openils/conf/opensrf.xml_ file and change the _<module>_ element to point to
526 the Syndetic Perl Module:
527
528 ----
529 <module>OpenILS::WWW::AddedContent::Syndetic</module>
530 ----
531
532 You will also need to edit the  _<userid>_ element to be the user id provided to
533 you by Syndetic.
534
535 Then, you will need to uncomment and edit the _<base_url>_ element so that it
536 points to the Syndetic service:
537
538 ----
539 <base_url>http://syndetics.com/index.aspx</base_url>
540 ----
541
542 For changes to be activated for your public interface you will need to restart
543 Evergreen and Apache.
544
545 Troubleshooting TPAC errors
546 ---------------------------
547
548 If there is a problem such as a TT syntax error, it generally shows up as an
549 ugly server failure page. If you check the Apache error logs, you will probably
550 find some solid clues about the reason for the failure. For example, in the
551 following example, the error message identifies the file in which the problem
552 occurred as well as the relevant line numbers.
553
554 Example error message in Apache error logs:
555
556 ----
557 bash# grep "template error" /var/log/apache2/error_log
558 [Tue Dec 06 02:12:09 2011] [warn] [client 127.0.0.1] egweb: template error:
559  file error - parse error - opac/parts/record/summary.tt2 line 112-121:
560   unexpected token (!=)\n  [% last_cn = 0;\n        FOR copy_info IN
561   ctx.copies;\n            callnum = copy_info.call_number_label;\n
562 ----