Docs: replacing Admin menu with Administration menu
[Evergreen.git] / docs / admin_initial_setup / designing_your_catalog.adoc
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 translations to PO file
209 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
210
211 After you have added custom text in translatable form to a TT2 template, you need to add the custom strings and its translations to the PO file containing the translations. Evergreen PO files are stored  in _/openils/var/template/data/locale/_ 
212
213 The PO file consists of pairs of the text extracted from the code:  Message ID  denoted as _msgid_ and message string denoted as _msgstr_.  When adding the custom string to PO file: 
214
215 * The line with English expressions must start with _msgid_. The English term must be enclosed in double apostrophes. 
216 * The line with translation start with /msgstr/. The translation to local language must be and enclosed in enclosed in double apostrophes.  
217 * It is recommended to  add a note in which template and on which line the particular string is located. The lines with notes must be marked as comments i.e., start with number sign (#) 
218
219 Example: 
220
221 ----
222
223 # ---------------------------------------------------------------------
224 # The lines below contains the custom strings manually added to the catalog
225 # ---------------------------------------------------------------------
226
227 #: ../../Open-ILS/src/custom_templates/opac/parts/topnav_links.tt2:1
228 msgid "Union Catalog of the Czech Republic"
229 msgstr "Souborný katalog České republiky"
230
231
232 #: ../../Open-ILS/src/custom_templates/opac/parts/topnav_links.tt2:1
233 msgid "Uniform Information Gateway "
234 msgstr "Jednotná informační brána"
235
236 ----
237
238 [NOTE]
239 ====
240 It is good practice to save backup copy of the original PO file before changing it.
241 ====
242
243 After making changes, restart Apache to make the changes take effect. As root run the command:
244
245 ----
246 service apache2 restart
247 ----
248
249 Adding and removing MARC fields from the record details display page
250 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
251
252 It is possible to add and remove the MARC fields and subfields displayed in the
253 record details page.  In order to add MARC fields to be displayed on the details
254 page of a record, you will need to map the MARC code to variables in the
255 _/openils/var/templates/opac/parts/misc_util.tt2 file_.
256
257 For example, to map the template variable _args.pubdates_ to the date of
258 publication MARC field 260, subfield c, add these lines to _misc_util.tt2_:
259
260 ----
261 args.pubdates = [];
262 FOR sub IN xml.findnodes('//*[@tag="260"]/*[@code="c"]');
263     args.pubdates.push(sub.textContent);
264 END;
265 args.pubdate = (args.pubdates.size) ? args.pubdates.0 : ''
266 ----
267
268 You will then need to edit the 
269 _/openils/var/templates/opac/parts/record/summary.tt2_ file in  order to get the
270 template variable for the MARC field to display.
271
272 For example, to display the date of publication code you created in the
273 _misc_util.tt2_ file, add these lines:
274
275 ----
276 [% IF attrs.pubdate; %]
277     <span itemprop="datePublished">[% attrs.pubdate | html; %]</span>
278 [% END; %]
279 ----
280
281 You can add any MARC field to your record details page. Moreover, this approach
282 can also be used to display MARC fields in other pages, such as your results
283 page.
284
285 Using bibliographic source variables
286 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
287
288 For bibliographic records, there is a "bib source" that can be associated with
289 every record. This source and its ID are available as record attributes called
290 _bib_source.source_ and _bib_source.id_.  These variables do not present
291 themselves in the catalog display by default.
292
293 .Example use case
294 ****
295
296 In this example, a library imports e-resource records from a third party and
297 uses the bib source to indicate where the records came from. Patrons can place
298 holds on these titles, but they must be placed via the vendor website, not in
299 Evergreen. By exposing the bib source, the library can alter the Place Hold
300 link for these records to point at the vendor website.
301
302 ****
303
304 Setting the default physical location for your library environment
305 ------------------------------------------------------------------
306
307 _physical_loc_ is an Apache environment variable that sets the default physical
308 location, used for setting search scopes and determining the order in which
309 copies should be sorted. This variable is set in
310 _/etc/apache2/sites-available/eg.conf_. The following example demonstrates the
311 default physical location being set to library ID 104:
312
313 ----
314 SetEnv physical_loc 104
315 ----
316
317 Setting a default language and adding optional languages
318 --------------------------------------------------------
319
320 _OILSWebLocale_ adds support for a specific language. Add this variable to the
321 Virtual Host section in _/etc/apache2/eg_vhost.conf_.
322
323 _OILSWebDefaultLocale_ specifies which locale to display when a user lands on a
324 page in TPAC and has not chosen a different locale from the TPAC locale picker.
325 The following example shows the _fr_ca_ locale being added to the locale picker
326 and being set as the default locale:
327
328 ----
329 PerlAddVar OILSWebLocale "fr_ca"
330 PerlAddVar OILSWebLocale "/openils/var/data/locale/opac/fr-CA.po"
331 PerlAddVar OILSWebDefaultLocale "fr-CA"
332 ----
333
334 Below is a table of the currently supported languages packaged with Evergreen:
335
336 [options="header"]
337 |===
338 |Language| Code| PO file
339 |Arabic - Jordan| ar_jo | /openils/var/data/locale/opac/ar-JO.po
340 |Armenian| hy_am| /openils/var/data/locale/opac/hy-AM.po
341 |Czech| cs_cz| /openils/var/data/locale/opac/cs-CZ.po
342 |English - Canada| en_ca| /openils/var/data/locale/opac/en-CA.po
343 |English - Great Britain| en_gb| /openils/var/data/locale/opac/en-GB.po
344 |*English - United States| en_us| not applicable
345 |French - Canada| fr_ca| /openils/var/data/locale/opac/fr-CA.po
346 |Portuguese - Brazil| pt_br| /openils/var/data/locale/opac/pt-BR.po
347 |Spanish| es_es| /openils/var/data/locale/opac/es-ES.po
348 |===
349 *American English is built into Evergreen so you do not need to set up this
350 language and there are no PO files. 
351
352 Updating translations in Evergreen using current translations from Launchpad
353 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
354
355 Due to Evergreen release workflow/schedule, some language strings may already have been translated in Launchpad,
356 but are not yet packaged with Evergreen. In such cases, it is possible to manually replace the PO file in
357 Evergreen with an up-to-date PO file downloaded from Launchpad. 
358
359 . Visit the Evergreen translation site in https://translations.launchpad.net/evergreen[Launchpad] 
360 . Select required language (e.g. _Czech_ or _Spanish_)
361 . Open the  _tpac_  template  and  then select option _Download translation_. Note: to be able to download the translation file you need to be logged in to Launchpad.
362 . Select _PO format_ and submit the _request for download_ button. You can also request for download of all existitng templates and languages at once, see https://translations.launchpad.net/evergreen/master/+export. The download link will be sent You to email address provided. 
363 . Download the file and name it according to the language used (e.g., _cs-CZ.po_ for Czech or  _es-ES.po_ for Spanish)  
364 . Copy the downloaded file to  _/openils/var/template/data/locale_. It is a good practice to backup the original PO file before.
365 . Be sure that the desired language is set as default, using the <<_setting_a_default_language_and_adding_optional_languages,Default language>> procedures.
366
367 Analogously, to update the web staff client translations, download the translation template _webstaff_ and copy it to _openils/var/template/data/locale/staff_.
368
369
370 Changes require web server reload to take effect. As root run the command 
371
372 ----
373 service apache2 restart
374 ----
375
376
377 Editing the formats select box options in the search interface.
378 ---------------------------------------------------------------
379
380 You may wish to remove, rename or organize the options in the formats select
381 box. This can be accomplished from the staff client.
382
383 . From the staff client, navigate to *Administration -> Server Administration ->  Marc Coded
384 Value Maps* 
385 . Select _Type_ from the *Record Attribute Type* select box.
386 . Double click on the format type you wish to edit.
387
388 To change the label for the type, enter a value in the *Search Label* field.
389
390 To  move the option to a top list separated by a dashed line from the others,
391 check the *Is Simple Selector* check box.
392
393 To hide the type so that it does not appear in the search interface, uncheck the
394 *OPAC Visible* checkbox.
395
396 Changes will be immediate.
397
398 Adding and removing search fields in advanced search
399 -----------------------------------------------------
400
401 It is possible to add and remove search fields on the advanced search page by
402 editing the _opac/parts/config.tt2_ file in your template directory. Look for
403 this section of the file:
404
405 ----
406 search.adv_config = [
407     {adv_label => l("Item Type"), adv_attr => ["mattype", "item_type"]},
408     {adv_label => l("Item Form"), adv_attr => "item_form"},
409     {adv_label => l("Language"),  adv_attr => "item_lang"},
410     {adv_label => l("Audience"),  adv_attr => ["audience_group", "audience"], adv_break => 1},
411     {adv_label => l("Video Format"), adv_attr => "vr_format"},
412     {adv_label => l("Bib Level"), adv_attr => "bib_level"},
413     {adv_label => l("Literary Form"), adv_attr => "lit_form", adv_break => 1},
414     {adv_label => l("Search Library"), adv_special => "lib_selector"},
415     {adv_label => l("Publication Year"), adv_special => "pub_year"},
416     {adv_label => l("Sort Results"), adv_special => "sort_selector"},
417 ];
418 ----
419
420 For example, if you delete the line:
421
422 ----
423 {adv_label => l("Language"),  adv_attr => "item_lang"},
424 ----
425
426 the language field will no longer appear on your advanced search page. Changes
427 will appear immediately after you save your changes.
428
429 You can also add fields based on Search Facet Groups that you create in the
430 staff client's Local Administration menu. This can be helpful if you want to
431 simplify your patrons' experience by presenting them with only certain
432 limiters (e.g. the most commonly used languages in your area).  To do this,
433
434 . Click *Administration -> Local Administration -> Search Facet Groups*.
435 . Click *New*.
436 . Enter descriptive values into the code and label fields.  The owner needs to
437 be set to your consortium.
438 . Once the Facet Group is created, click on the blue hyperlinked code value.
439 . Click the *New* button to create the necessary values for your field.
440 . Go to the _opac/parts/config.tt2_ file, and add a line like the following,
441 where *Our Library's Field* is the name you'd like to be displayed next to
442 your field, and *facet_group_code* is the code you've added using the staff
443 client.
444 +
445 ----
446  {adv_label => l("Our Library's Field"), adv_filter => "facet_group_code"},
447 ----
448
449 Changing the display of facets and facet groups
450 -----------------------------------------------
451
452 Facets can be reordered on the search results page by editing the
453 _opac/parts/config.tt2_ file in your template directory.  
454
455 Edit the following section of _config.tt2_, changing the order of the facet
456 categories according to your needs:
457
458 ----
459
460 facet.display = [
461     {facet_class => 'author',  facet_order => ['personal', 'corporate']},
462     {facet_class => 'subject', facet_order => ['topic']},
463     {facet_class => 'series',  facet_order => ['seriestitle']},
464     {facet_class => 'subject', facet_order => ['name', 'geographic']}
465 ];
466
467 ----
468
469 You may also change the default number of facets appearing under each category
470 by editing the _facet.default_display_count_ value in _config.tt2_. The default 
471 value is 5.
472
473 Change Date Format in Patron Account View
474 -----------------------------------------
475 Libraries with same-day circulations may want their patrons to be able to view
476 the due *time* as well as due date when they log in to their OPAC account.  To
477 accomplish this, go to _opac/myopac/circs.tt2_.  Find the line that reads:
478
479 ----
480 [% date.format(due_date, DATE_FORMAT) %]
481 ----
482
483 Replace it with:
484
485 ----
486 [% date.format(due_date, '%D %I:%M %p') %]
487 ----
488
489
490 Including External Content in Your Public Interface
491 ---------------------------------------------------
492
493 The public interface allows you to include external services and content in your
494 public interface. These can include book cover images, user reviews, table of
495 contents, summaries, author notes, annotations, user suggestions, series
496 information among other services. Some of these services are free while others
497 require a subscription.    
498
499 The following are some of the external content services which you can configure
500 in Evergreen.
501
502 OpenLibrary
503 ~~~~~~~~~~~
504
505 The default install of Evergreen includes OpenLibrary book covers. The settings
506 for this are controlled by the <added_content> section of
507 _/openils/conf/opensrf.xml_. Here are the key elements of this configuration:
508
509 ----
510 <module>OpenILS::WWW::AddedContent::OpenLibrary</module>
511 ----
512
513 This section calls the OpenLibrary perl module. If you wish to link to a
514 different book cover service other than OpenLibrary, you must refer to the
515 location of the corresponding Perl module. You will also need to change other
516 settings accordingly.
517
518 ----
519 <timeout>1</timeout>
520 ----
521
522 Max number of seconds to wait for an added content request to return data. Data 
523 not returned within the timeout is considered a failure.
524 ----
525 <retry_timeout>600</retry_timeout>
526 ----
527
528 This setting is the amount of time to wait before we try again.
529
530 ----
531 <max_errors>15</max_errors>
532 ----
533
534 Maximum number of consecutive lookup errors a given process can have before
535 added content lookups are disabled for everyone. To adjust the site of the cover
536 image on the record details page edit the config.tt2 file and change the value
537 of the record.summary.jacket_size. The default value is "medium" and the
538 available options are "small", "medium" and "large."   
539
540 ChiliFresh
541 ~~~~~~~~~~
542
543 ChiliFresh is a subscription-based service which allows book covers, reviews and
544 social interaction of patrons to appear in your catalog. To activate ChiliFresh,
545 you will need to open the Apache configuration file _/etc/apache2/eg_vhost.conf_
546 and edit several lines:
547
548 . Uncomment (remove the "#" at the beginning of the line) and add your ChiliFresh
549 account number:
550
551 ----
552 #SetEnv OILS_CHILIFRESH_ACCOUNT
553 ----
554
555 . Uncomment this line and add your ChiliFresh Profile:
556
557 ----
558 #SetEnv OILS_CHILIFRESH_PROFILE
559 ----
560
561 Uncomment the line indicating the location of the Evergreen JavaScript for
562 ChiliFresh:
563
564 ----
565 #SetEnv OILS_CHILIFRESH_URL http://chilifresh.com/on-site /js/evergreen.js
566 ----
567
568 . Uncomment the line indicating the secure URL for the Evergreen JavaScript :
569
570 ----
571 #SetEnv OILS_CHILIFRESH_HTTPS_URL https://secure.chilifresh.com/on-site/js/evergreen.js
572 ----
573
574 [id="_content_cafe"]
575 Content Café
576 ~~~~~~~~~~~~
577
578 Content Café is a subscription-based service that can add  jacket images,
579 reviews, summaries, tables of contents and book details to your records.
580
581 In order to activate Content Café, edit the _/openils/conf/opensrf.xml_ file and
582 change the _<module>_ element to point to the ContentCafe Perl Module:
583
584 ----
585 <module>OpenILS::WWW::AddedContent::ContentCafe</module>
586 ----
587
588 To adjust settings for Content Café, edit a couple of fields with the
589 _<ContentCafe>_ Section of _/openils/conf/opensrf.xml_.
590
591 Edit the _userid_ and _password_ elements to match the user id and password for
592 your Content Café account.
593
594 This provider retrieves content based on ISBN or UPC, with a default preference
595 for ISBNs.  If you wish for UPCs to be preferred, or wish one of the two identifier
596 types to not be considered at all, you can change the "identifier_order" option
597 in opensrf.xml.  When the option is present, only the identifier(s) listed will
598 be sent.
599
600 Obalkyknih.cz
601 ~~~~~~~~~~~~~
602
603 Setting up Obalkyknih.cz account
604 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
605
606 If your library wishes to use added content provided by Obalkyknih.cz, a service based in the Czech Republic, you have to http://obalkyknih.cz/signup[create an Obalkyknih.cz account].
607 Please note that the interface is only available in Czech. After logging in your Obalkyknih.cz account, you have to add your IP address and Evergreen server address to your account settings.
608 (In case each library uses an address of its own, all of these addresses have to be added.) 
609
610 Enabling Obalkyknih.cz in Evergreen
611 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
612
613 Set obalkyknih_cz.enabled to true in '/openils/var/templates/opac/parts/config.tt2':
614
615 [source,perl]
616 ----
617 obalkyknih_cz.enabled = 'true';
618 ----
619
620 Enable added content from Obalkyknih.cz in '/openils/conf/opensrf.xml' configuration file (and – at the same time – disable added content from Open Library, i.e., Evergreen's default added content provider):
621
622 [source,xml]
623 ----
624 <!-- <module>OpenILS::WWW::AddedContent::OpenLibrary</module> -->
625 <module>OpenILS::WWW::AddedContent::ObalkyKnih</module>
626 ----
627
628 Using default settings for Obalkyknih.cz means all types of added content from Obalkyknih.cz are visible in your online catalog.
629 If the module is enabled, book covers are always displayed. Other types of added content (summaries, ratings or tables of contents) can be: 
630
631 * switched off using _false_ option,
632 * switched on again using _true_ option.
633
634 The following types of added content are used: 
635
636 * summary (or annotation)
637 * tocPDF (table of contents available as image)
638 * tocText (table of contents available as text)
639 * review (user reviews)
640
641 An example of how to switch off summaries: 
642
643 [source,xml]
644 ----
645 <summary>false</summary>
646 ----
647
648
649 Google Analytics
650 ~~~~~~~~~~~~~~~~
651
652 Google Analytics is a free service to collect statistics for your Evergreen
653 site. Statistic tracking is disabled by default through the Evergreen 
654 client software when library staff use your site within the client, but active 
655 when anyone uses the site without the client. This was a preventive measure to 
656 reduce the potential risks for leaking patron information. In order to use Google 
657 Analytics you will first need to set up the service from the Google Analytics 
658 website at http://www.google.com/analytics/. To activate Google Analytics you 
659 will need to edit _config.tt2_ in your template. To enable the service set 
660 the value of google_analytics.enabled to true and change the value of 
661 _google_analytics.code_ to be the code in your Google Analytics account.
662
663 NoveList
664 ~~~~~~~~
665
666 Novelist is a subscription-based service providing reviews and recommendation
667 for books in you catalog. To activate your Novelist service in Evergreen, open
668 the Apache configuration file _/etc/apache2/eg_vhost.conf_ and edit the line:
669
670 ----
671 #SetEnv OILS_NOVELIST_URL
672 ----
673
674 You should use the URL provided by NoveList.
675
676 RefWorks
677 ~~~~~~~~
678
679 RefWorks is a subscription-based online bibliographic management tool. If you
680 have a RefWorks subscription, you can activate RefWorks in Evergreen by editing
681 the _config.tt2_ file located in your template directory. You will need to set
682 the _ctx.refworks.enabled_ value to _true_. You may also set the RefWorks URL by
683 changing the _ctx.refworks.url_ setting on the same file. 
684
685 SFX OpenURL Resolver
686 ~~~~~~~~~~~~~~~~~~~~
687
688 An OpenURL resolver allows you to find electronic resources and pull them into
689 your catalog based on the ISBN or ISSN of the item. In order to use the SFX
690 OpenURL resolver, you will need to subscribe to the Ex Libris SFX service.  To
691 activate the service in Evergreen edit the _config.tt2_ file in your template.
692 Enable the resolver by changing the value of _openurl.enabled_ to _true_ and
693 change the _openurl.baseurl_ setting to point to the URL of your OpenURL
694 resolver. 
695
696 Syndetic Solutions
697 ~~~~~~~~~~~~~~~~~~
698
699 Syndetic Solutions is a subscription service providing book covers and other
700 data for items in your catalog. In order to activate Syndetic, edit the
701 _/openils/conf/opensrf.xml_ file and change the _<module>_ element to point to
702 the Syndetic Perl Module:
703
704 ----
705 <module>OpenILS::WWW::AddedContent::Syndetic</module>
706 ----
707
708 You will also need to edit the  _<userid>_ element to be the user id provided to
709 you by Syndetic.
710
711 Then, you will need to uncomment and edit the _<base_url>_ element so that it
712 points to the Syndetic service:
713
714 ----
715 <base_url>http://syndetics.com/index.aspx</base_url>
716 ----
717
718 For changes to be activated for your public interface you will need to restart
719 Evergreen and Apache.
720
721 The Syndetic Solutions provider retrieves images based on the following identifiers
722 found in bibliographic records:
723
724 * ISBN
725 * UPC
726 * ISSN
727
728
729 Clear External/Added Content Cache
730 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
731
732 On the catalog's record summary page, there is a link for staff that will forcibly clear 
733 the cache of the Added Content for that record. This is helpful for when the Added Content 
734 retrieved the wrong cover jacket art, summary, etc. and caches the wrong result.
735
736 image::media/clear-added-content-cache-1.png[Clear Cache Link]
737
738 Once clicked, there is a pop up that will display what was cleared from the cache. 
739
740 image::media/clear-added-content-cache-2.jpg[Example Popup]
741
742 You will need to reload the record in the staff client to obtain the new images from your 
743 Added Content Supplier.
744
745
746 Configure a Custom Image for Missing Images
747 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
748
749 You can configure a "no image" image other than the standard 1-pixel
750 blank image.  The example eg_vhost.conf file provides examples in the
751 comments.  Note: Evergreen does not provide default images for these.
752
753
754 Including Locally Hosted Content in Your Public Interface
755 ---------------------------------------------------------
756
757 It is also possible to show added content that has been generated locally 
758 by placing the content in a specific spot on the web server.  It is 
759 possible to have local book jackets, reviews, TOC, excerpts or annotations.
760
761 File Location and Format
762 ~~~~~~~~~~~~~~~~~~~~~~~~
763
764 By default the files will need to be placed in directories under 
765 */openils/var/web/opac/extras/ac/* on the server(s) that run Apache.
766
767 The files need to be in specific folders depending on the format of the 
768 added content.  Local Content can only be looked up based on the 
769 record ID at this time.
770
771 .URL Format:
772 \http://catalog/opac/extras/ac/*\{type}/\{format}/r/\{recordid}*
773
774  * *type* is one of *jacket*, *reviews*, *toc*, *excerpt* or *anotes*.
775   * *format* is type dependent:
776     - for jacket, one of small, medium or large
777     - others, one of html, xml or json ... html is the default for non-image added content
778   * *recordid* is the bibliographic record id (bre.id).
779
780 Example
781 ~~~~~~~
782
783 If you have some equipment that you are circulating such as a 
784 laptop or eBook reader and you want to add an image of the equipment 
785 that will show up in the catalog.
786
787 [NOTE]
788 =============
789 If you are adding jacket art for a traditional type of media 
790 (book, CD, DVD) consider adding the jacket art to the http://openlibrary.org 
791 project instead of hosting it locally.  This would allow other 
792 libraries to benefit from your work.
793 =============
794
795 Make note of the Record ID of the bib record.  You can find this by 
796 looking at the URL of the bib in the catalog.  
797 http://catalog/eg/opac/record/*123*, 123 is the record ID.  
798 These images will only show up for one specific record.
799
800 Create 3 different sized versions of the image in png or jpg format.
801
802  * *Small* - 80px x 80px - named _123-s.jpg_ or _123-s.png_ - This is displayed in the browse display.
803  * *Medium* - 240px x 240px - named _123-m.jpg_ or _123-m.png_ - This is displayed on the summary page.
804  * *Large* - 400px x 399px - named _123-l.jpg_ or _123-l.png_ - This is displayed if the summary page image is clicked on.
805
806 [NOTE] 
807 The image dimensions are up to you, use what looks good in your catalog.
808  
809 Next, upload the images to the evergreen server(s) that run apache, 
810 and move/rename the files to the following locations/name.  
811 You will need to create directories that are missing.
812  
813  * Small - Move the file *123-s.jpg* to */openils/var/web/opac/extras/ac/jacket/small/r/123*
814  * Medium - Move the file *123-m.jpg* to */openils/var/web/opac/extras/ac/jacket/medum/r/123*.
815  * Large - Move the file *123-l.jpg* to */openils/var/web/opac/extras/ac/jacket/large/r/123*.
816
817 [NOTE]
818 The system doesn't need the file extension to know what kind of file it is.
819  
820 Reload the bib record summary in the web catalog and your new image will display.
821