Docs: Information for system administrators about translations

[Evergreen.git] / docs / admin_initial_setup / designing_your_catalog.txt

Designing your catalog
======================

When people want to find things in your Evergreen system, they will check the
catalog. In Evergreen, the catalog is made available through a web interface,
called the _OPAC_ (Online Public Access Catalog). In the latest versions of the
Evergreen system, the OPAC is built on a set of programming modules called the
Template Toolkit. You will see the OPAC sometimes referred to as the _TPAC_.

In this chapter, we'll show you how to customize the OPAC, change it from its
default configuration, and make it your own.

Configuring and customizing the public interface
------------------------------------------------

The public interface is referred to as the TPAC or Template Toolkit (TT) within
the Evergreen community. The template toolkit system allows you to customize the
look and feel of your OPAC by editing the template pages (.tt2) files as well as
the associated style sheets.   

Locating the default template files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The default URL for the TPAC on a default Evergreen system is
_http://localhost/eg/opac/home_ (adjust _localhost_ to match your hostname or IP
address).

The default template file is installed in _/openils/var/templates/opac_.

You should generally avoid touching the installed default template files, unless
you are contributing changes for Evergreen to adopt as a new default. Even then,
while you are developing your changes, consider using template overrides rather
than touching the installed templates until you are ready to commit the changes
to a branch. See below for information on template overrides.

Mapping templates to URLs
~~~~~~~~~~~~~~~~~~~~~~~~~

The mapping for templates to URLs is straightforward. Following are a few
examples, where _<templates>_ is a placeholder for one or more directories that
will be searched for a match:

* _http://localhost/eg/opac/home => /openils/var/<templates>/opac/home.tt2_
* _http://localhost/eg/opac/advanced =>
/openils/var/<templates>/opac/advanced.tt2_
* _http://localhost/eg/opac/results => 
/openils/var/<templates>/opac/results.tt2_

The template files themselves can process, be wrapped by, or include other
template files. For example, the _home.tt2_ template currently involves a number
of other template files to generate a single HTML file.

Example Template Toolkit file: _opac/home.tt2_.
----
[%  PROCESS "opac/parts/header.tt2";
    WRAPPER "opac/parts/base.tt2";
    INCLUDE "opac/parts/topnav.tt2";
    ctx.page_title = l("Home") %]
    <div id="search-wrapper">
      [% INCLUDE "opac/parts/searchbar.tt2" %]
    </div>
    <div id="content-wrapper">
        <div id="main-content-home">
             <div class="common-full-pad"></div>
             [% INCLUDE "opac/parts/homesearch.tt2" %]
             <div class="common-full-pad"></div>
        </div>
     </div>
[% END %]
----
Note that file references are relative to the top of the template directory.

How to override template files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Overrides for template files or TPAC pages go in a directory that parallels the
structure of the default templates directory. The overrides then get pulled in
via the Apache configuration.

The following example demonstrates how to create a file that overrides the
default "Advanced search page" (_advanced.tt2_) by adding a new 
_templates_custom_ directory and editing the new file in that directory.

----
bash$ mkdir -p /openils/var/templates_custom/opac
bash$ cp /openils/var/templates/opac/advanced.tt2 \
         /openils/var/templates_custom/opac/.
bash$ vim /openils/var/templates_custom/opac/advanced.tt2
----

Configuring the custom templates directory in Apache's eg.conf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You now need to teach Apache about the new custom template directory. Edit
_/etc/apache2/sites-available/eg.conf_ and add the following _<Location /eg>_
element to each of the _<VirtualHost>_ elements in which you want to include the
overrides. The default Evergreen configuration includes a VirtualHost directive
for port 80 (HTTP) and another one for port 443 (HTTPS); you probably want to
edit both, unless you want the HTTP user experience to be different from the
HTTPS user experience.

----
<VirtualHost *:80>
    # <snip>

    # - absorb the shared virtual host settings
    Include eg_vhost.conf
    <Location /eg>
        PerlAddVar OILSWebTemplatePath "/openils/var/templates_custom"
    </Location>

    # <snip>
</VirtualHost>
----

Finally, reload the Apache configuration to pick up the changes. You should now
be able to see your change at _http://localhost/eg/opac/advanced_ where
_localhost_ is the hostname of your Evergreen server.

Adjusting colors for your public interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You may adjust the colors of your public interface by editing the _colors.tt2_
file. The location of this file is in 
_/openils/var/templates/opac/parts/css/colors.tt2_. When you customize the
colors of your public interface, remember to create a custom file in your custom
template folder and edit the custom file and not the file located in you default
template.    

Adjusting fonts in your public interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Font sizes can be changed in the _colors.tt2_ file located in
_/openils/var/templates/opac/parts/css/_. Again, create and edit a custom
template version and not the file in the default template.

Other aspects of fonts such as the default font family can be adjusted in
_/openils/var/templates/opac/css/style.css.tt2_. 

Media file locations in the public interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The media files (mostly PNG images) used by the default TPAC templates are stored
in the repository in _Open-ILS/web/images/_ and installed in
_/openils/var/web/images/_.

Changing some text in the public interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Out of the box, TPAC includes a number of placeholder text and links. For
example, there is a set of links cleverly named Link 1, Link 2, and so on in the
header and footer of every page in TPAC. Here is how to customize that for a 
_custom templates_ skin.

To begin with, find the page(s) that contain the text in question. The simplest
way to do that is with the grep -s command. In the following example, search for
files that contain the text "Link 1":

----
bash$ grep -r "Link 1" /openils/var/templates/opac
/openils/var/templates/opac/parts/topnav_links.tt2
4:            <a href="http://example.com">[% l('Link 1') %]</a>
----


Next, copy the file into our overrides directory and edit it with vim.

Copying the links file into the overrides directory.

----
bash$ cp /openils/var/templates/opac/parts/topnav_links.tt2 \
/openils/var/templates_custom/opac/parts/topnav_links.tt2
bash$ vim /openils/var/templates_custom/opac/parts/topnav_links.tt2
----

Finally, edit the link text in _opac/parts/header.tt2_. Content of the
_opac/parts/header.tt2_ file.

----
<div id="gold-links-holder">
    <div id="gold-links">
        <div id="header-links">
            <a href="http://example.com">[% l('Link 1') %]</a>
            <a href="http://example.com">[% l('Link 2') %]</a>
            <a href="http://example.com">[% l('Link 3') %]</a>
            <a href="http://example.com">[% l('Link 4') %]</a>
            <a href="http://example.com">[% l('Link 5') %]</a>
        </div>
    </div>
</div>
----

For the most part, the page looks like regular HTML, but note the `[%_(" ")%]`
that surrounds the text of each link. The `[% ... %]` signifies a TT block,
which can contain one or more TT processing instructions. `l(" ... ");` is a
function that marks text for localization (translation); a separate process can
subsequently extract localized text as GNU gettext-formatted PO (Portable
Object) files.

As Evergreen supports multiple languages, any customization to Evergreen's
default text must use the localization function. Also, note that the
localization function supports placeholders such as `[_1]`, `[_2]` in the text;
these are replaced by the contents of variables passed as extra arguments to the
`l()` function.

Once the link and link text has been edited to your satisfaction, load the page
in a Web browser and see the live changes immediately.

Adding translations to PO file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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/_ 

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: 

* The line with English expressions must start with _msgid_. The English term must be enclosed in double apostrophes. 
* The line with translation start with /msgstr/. The translation to local language must be and enclosed in enclosed in double apostrophes.  
* 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 (#) 

Example: 

----

# ---------------------------------------------------------------------
# The lines below contains the custom strings manually added to the catalog
# ---------------------------------------------------------------------

#: ../../Open-ILS/src/custom_templates/opac/parts/topnav_links.tt2:1
msgid "Union Catalog of the Czech Republic"
msgstr "Souborný katalog České republiky"


#: ../../Open-ILS/src/custom_templates/opac/parts/topnav_links.tt2:1
msgid "Uniform Information Gateway "
msgstr "Jednotná informační brána"

----

[NOTE]
====
It is good practice to save backup copy of the original PO file before changing it.
====

After making changes, restart Apache to make the changes take effect. As root run the command:

----
service apache2 restart
----

Adding and removing MARC fields from the record details display page
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It is possible to add and remove the MARC fields and subfields displayed in the
record details page.  In order to add MARC fields to be displayed on the details
page of a record, you will need to map the MARC code to variables in the
_/openils/var/templates/opac/parts/misc_util.tt2 file_.

For example, to map the template variable _args.pubdates_ to the date of
publication MARC field 260, subfield c, add these lines to _misc_util.tt2_:

----
args.pubdates = [];
FOR sub IN xml.findnodes('//*[@tag="260"]/*[@code="c"]');
    args.pubdates.push(sub.textContent);
END;
args.pubdate = (args.pubdates.size) ? args.pubdates.0 : ''
----

You will then need to edit the 
_/openils/var/templates/opac/parts/record/summary.tt2_ file in  order to get the
template variable for the MARC field to display.

For example, to display the date of publication code you created in the
_misc_util.tt2_ file, add these lines:

----
[% IF attrs.pubdate; %]
    <span itemprop="datePublished">[% attrs.pubdate | html; %]</span>
[% END; %]
----

You can add any MARC field to your record details page. Moreover, this approach
can also be used to display MARC fields in other pages, such as your results
page.

Setting the default physical location for your library environment
------------------------------------------------------------------

_physical_loc_ is an Apache environment variable that sets the default physical
location, used for setting search scopes and determining the order in which
copies should be sorted. This variable is set in
_/etc/apache2/sites-available/eg.conf_. The following example demonstrates the
default physical location being set to library ID 104:

----
SetEnv physical_loc 104
----

Setting a default language and adding optional languages
--------------------------------------------------------

_OILSWebLocale_ adds support for a specific language. Add this variable to the
Virtual Host section in _/etc/apache2/sites-available/eg.conf_.

_OILSWebDefaultLocale_ specifies which locale to display when a user lands on a
page in TPAC and has not chosen a different locale from the TPAC locale picker.
The following example shows the _fr_ca_ locale being added to the locale picker
and being set as the default locale:

----
PerlAddVar OILSWebLocale "fr_ca"
PerlAddVar OILSWebLocale "/openils/var/data/locale/opac/fr-CA.po"
PerlAddVar OILSWebDefaultLocale "fr-CA"
----

Below is a table of the currently supported languages packaged with Evergreen:

[options="header"]
|================================================================
|Language| Code| PO file
|Czech| cs_cz| /openils/var/data/locale/opac/cs-CZ.po
|English - Canada| en_ca| /openils/var/data/locale/opac/en-CA.po
|English - Great Britain| en_gb| /openils/var/data/locale/opac/en-GB.po
|*English - United States| en_us| not applicable
|French - Canada| fr_ca| /openils/var/data/locale/opac/fr-CA.po
|Portuguese - Brazil| pt_br| /openils/var/data/locale/opac/pt_BR.po
|Russian| ru_ru| /openils/var/data/locale/opac/ru_RU.po
|=================================================================
*American English is built into Evergreen so you do not need to set up this
language and there are no PO files. 

Updating translations in Evergreen using current translations from Launchpad
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Due to Evergreen release workflow/schedule, some language strings may already have been translated in Launchpad,
but are not yet packaged with Evergreen. In such cases, it is possible to manually replace the PO file in
Evergreen with an up-to-date PO file downloaded from Launchpad. 

. Visit the Evergreen translation site in https://translations.launchpad.net/evergreen[Launchpad] 
. Select required language (e.g. _Czech_ or _Spanish_)
. 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.
. 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. 
. Download the file and name it according to the language used (e.g., _cs-CZ.po_ for Czech or  _es-ES.po_ for Spanish)  
. Copy the downloaded file to  _/openils/var/template/data/locale_. It is a good practice to backup the original PO file before.
. Be sure that the desired language is set as default, using the <<_setting_a_default_language_and_adding_optional_languages,Default language>> procedures.

Analogously, to update the web staff client translations, download the translation template _webstaff_ and copy it to _openils/var/template/data/locale/staff_.


Changes require web server reload to take effect. As root run the command 

----
service apache2 restart
----


Editing the formats select box options in the search interface.
---------------------------------------------------------------

You may wish to remove, rename or organize the options in the formats select
box. This can be accomplished from the staff client.

. From the staff client, navigate to *Admin > Server Administration > Marc Coded
Value Maps* 
. Select _Type_ from the *Record Attribute Type* select box.
. Double click on the format type you wish to edit.

To change the label for the type, enter a value in the *Search Label* field.

To  move the option to a top list separated by a dashed line from the others,
check the *Is Simple Selector* check box.

To hide the type so that it does not appear in the search interface, uncheck the
*OPAC Visible* checkbox.

Changes will be immediate.

Adding and removing search fields in advanced search
-----------------------------------------------------

It is possible to add and remove search fields on the advanced search page by
editing the _opac/parts/config.tt2_ file in your template directory. Look for
this section of the file:

----
search.adv_config = [
    {adv_label => l("Item Type"), adv_attr => ["mattype", "item_type"]},
    {adv_label => l("Item Form"), adv_attr => "item_form"},
    {adv_label => l("Language"),  adv_attr => "item_lang"},
    {adv_label => l("Audience"),  adv_attr => ["audience_group", "audience"], adv_break => 1},
    {adv_label => l("Video Format"), adv_attr => "vr_format"},
    {adv_label => l("Bib Level"), adv_attr => "bib_level"},
    {adv_label => l("Literary Form"), adv_attr => "lit_form", adv_break => 1},
    {adv_label => l("Search Library"), adv_special => "lib_selector"},
    {adv_label => l("Publication Year"), adv_special => "pub_year"},
    {adv_label => l("Sort Results"), adv_special => "sort_selector"},
];
----

For example, if you delete the line:

----
{adv_label => l("Language"),  adv_attr => "item_lang"},
----

the language field will no longer appear on your advanced search page. Changes
will appear immediately after you save your changes.

You can also add fields based on Search Facet Groups that you create in the
staff client's Local Administration menu. This can be helpful if you want to
simplify your patrons' experience by presenting them with only certain
limiters (e.g. the most commonly used languages in your area).  To do this,

. Click *Admin -> Local Administration -> Search Facet Groups*.
. Click *New*.
. Enter descriptive values into the code and label fields.  The owner needs to
be set to your consortium.
. Once the Facet Group is created, click on the blue hyperlinked code value.
. Click the *New* button to create the necessary values for your field.
. Go to the _opac/parts/config.tt2_ file, and add a line like the following,
where *Our Library's Field* is the name you'd like to be displayed next to
your field, and *facet_group_code* is the code you've added using the staff
client.
+
----
 {adv_label => l("Our Library's Field"), adv_filter => "facet_group_code"},
----

Changing the display of facets and facet groups
-----------------------------------------------

Facets can be reordered on the search results page by editing the
_opac/parts/config.tt2_ file in your template directory.  

Edit the following section of _config.tt2_, changing the order of the facet
categories according to your needs:

----

facet.display = [
    {facet_class => 'author',  facet_order => ['personal', 'corporate']},
    {facet_class => 'subject', facet_order => ['topic']},
    {facet_class => 'series',  facet_order => ['seriestitle']},
    {facet_class => 'subject', facet_order => ['name', 'geographic']}
];

----

You may also change the default number of facets appearing under each category
by editing the _facet.default_display_count_ value in _config.tt2_. The default 
value is 5.

Change Date Format in Patron Account View
-----------------------------------------
Libraries with same-day circulations may want their patrons to be able to view
the due *time* as well as due date when they log in to their OPAC account.  To
accomplish this, go to _opac/myopac/circs.tt2_.  Find the line that reads:

----
[% date.format(due_date, DATE_FORMAT) %]
----

Replace it with:

----
[% date.format(due_date, '%D %I:%M %p') %]
----


Including External Content in Your Public Interface
---------------------------------------------------

The public interface allows you to include external services and content in your
public interface. These can include book cover images, user reviews, table of
contents, summaries, author notes, annotations, user suggestions, series
information among other services. Some of these services are free while others
require a subscription.    

The following are some of the external content services which you can configure
in Evergreen.

OpenLibrary
~~~~~~~~~~~

The default install of Evergreen includes OpenLibrary book covers. The settings
for this are controlled by the <added_content> section of
_/openils/conf/opensrf.xml_. Here are the key elements of this configuration:

----
<module>OpenILS::WWW::AddedContent::OpenLibrary</module>
----

This section calls the OpenLibrary perl module. If you wish to link to a
different book cover service other than OpenLibrary, you must refer to the
location of the corresponding Perl module. You will also need to change other
settings accordingly.

----
<timeout>1</timeout>
----

Max number of seconds to wait for an added content request to return data. Data 
not returned within the timeout is considered a failure.
----
<retry_timeout>600</retry_timeout>
----

This setting is the amount of time to wait before we try again.

----
<max_errors>15</max_errors>
----

Maximum number of consecutive lookup errors a given process can have before
added content lookups are disabled for everyone. To adjust the site of the cover
image on the record details page edit the config.tt2 file and change the value
of the record.summary.jacket_size. The default value is "medium" and the
available options are "small", "medium" and "large."   

ChiliFresh
~~~~~~~~~~

ChiliFresh is a subscription-based service which allows book covers, reviews and
social interaction of patrons to appear in your catalog. To activate ChiliFresh,
you will need to open the Apache configuration file _/etc/apache2/eg_vhost.conf_
and edit several lines:

. Uncomment (remove the "#" at the beginning of the line) and add your ChiliFresh
account number:

----
#SetEnv OILS_CHILIFRESH_ACCOUNT
----

. Uncomment this line and add your ChiliFresh Profile:

----
#SetEnv OILS_CHILIFRESH_PROFILE
----

Uncomment the line indicating the location of the Evergreen JavaScript for
ChiliFresh:

----
#SetEnv OILS_CHILIFRESH_URL http://chilifresh.com/on-site /js/evergreen.js
----

. Uncomment the line indicating the secure URL for the Evergreen JavaScript :

----
#SetEnv OILS_CHILIFRESH_HTTPS_URL https://secure.chilifresh.com/on-site/js/evergreen.js
----

[id="_content_cafe"]
Content Café
~~~~~~~~~~~~

Content Café is a subscription-based service that can add  jacket images,
reviews, summaries, tables of contents and book details to your records.

In order to activate Content Café, edit the _/openils/conf/opensrf.xml_ file and
change the _<module>_ element to point to the ContentCafe Perl Module:

----
<module>OpenILS::WWW::AddedContent::ContentCafe</module>
----

To adjust settings for Content Café, edit a couple of fields with the
_<ContentCafe>_ Section of _/openils/conf/opensrf.xml_.

Edit the _userid_ and _password_ elements to match the user id and password for
your Content Café account.

Change the _return_behavior_on_no_jacket_image_ to set the behavior of your
service when an image is not available for an item. By default this value is set
to T which will result in a small image with the text "No Image Available" in
place of a book cover. If you set this value to 1 a 1X1 blank image will be in
place of a book cover. 

Obalkyknih.cz
~~~~~~~~~~~~~

Setting up Obalkyknih.cz account
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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].
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.
(In case each library uses an address of its own, all of these addresses have to be added.) 

Enabling Obalkyknih.cz in Evergreen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Set obalkyknih_cz.enabled to true in '/openils/var/templates/opac/parts/config.tt2':

[source,perl]
----
obalkyknih_cz.enabled = 'true';
----

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):

[source,xml]
----
<!-- <module>OpenILS::WWW::AddedContent::OpenLibrary</module> -->
<module>OpenILS::WWW::AddedContent::ObalkyKnih</module>
----

Using default settings for Obalkyknih.cz means all types of added content from Obalkyknih.cz are visible in your online catalog.
If the module is enabled, book covers are always displayed. Other types of added content (summaries, ratings or tables of contents) can be: 

* switched off using _false_ option,
* switched on again using _true_ option.

The following types of added content are used: 

* summary (or annotation)
* tocPDF (table of contents available as image)
* tocText (table of contents available as text)
* review (user reviews)

An example of how to switch off summaries: 

[source,xml]
----
<summary>false</summary>
----


Google Analytics
~~~~~~~~~~~~~~~~

Google Analytics is a free service to collect statistics for your Evergreen
site. Statistic tracking is disabled by default through the Evergreen 
client software when library staff use your site within the client, but active 
when anyone uses the site without the client. This was a preventive measure to 
reduce the potential risks for leaking patron information. In order to use Google 
Analytics you will first need to set up the service from the Google Analytics 
website at http://www.google.com/analytics/. To activate Google Analytics you 
will need to edit _config.tt2_ in your template. To enable the service set 
the value of google_analytics.enabled to true and change the value of 
_google_analytics.code_ to be the code in your Google Analytics account.

NoveList
~~~~~~~~

Novelist is a subscription-based service providing reviews and recommendation
for books in you catalog. To activate your Novelist service in Evergreen, open
the Apache configuration file _/etc/apache2/eg_vhost.conf_ and edit the line:

----
#SetEnv OILS_NOVELIST_URL
----

You should use the URL provided by NoveList.

RefWorks
~~~~~~~~

RefWorks is a subscription-based online bibliographic management tool. If you
have a RefWorks subscription, you can activate RefWorks in Evergreen by editing
the _config.tt2_ file located in your template directory. You will need to set
the _ctx.refworks.enabled_ value to _true_. You may also set the RefWorks URL by
changing the _ctx.refworks.url_ setting on the same file. 

SFX OpenURL Resolver
~~~~~~~~~~~~~~~~~~~~

An OpenURL resolver allows you to find electronic resources and pull them into
your catalog based on the ISBN or ISSN of the item. In order to use the SFX
OpenURL resolver, you will need to subscribe to the Ex Libris SFX service.  To
activate the service in Evergreen edit the _config.tt2_ file in your template.
Enable the resolver by changing the value of _openurl.enabled_ to _true_ and
change the _openurl.baseurl_ setting to point to the URL of your OpenURL
resolver. 

Syndetic Solutions
~~~~~~~~~~~~~~~~~~

Syndetic Solutions is a subscription service providing book covers and other
data for items in your catalog. In order to activate Syndetic, edit the
_/openils/conf/opensrf.xml_ file and change the _<module>_ element to point to
the Syndetic Perl Module:

----
<module>OpenILS::WWW::AddedContent::Syndetic</module>
----

You will also need to edit the  _<userid>_ element to be the user id provided to
you by Syndetic.

Then, you will need to uncomment and edit the _<base_url>_ element so that it
points to the Syndetic service:

----
<base_url>http://syndetics.com/index.aspx</base_url>
----

For changes to be activated for your public interface you will need to restart
Evergreen and Apache.


Clear External/Added Content Cache
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On the catalog’s record summary page, there is a link for staff that will forcibly clear 
the cache of the Added Content for that record. This is helpful for when the Added Content 
retrieved the wrong cover jacket art, summary, etc. and caches the wrong result.

image::media/clear-added-content-cache-1.png[Clear Cache Link]

Once clicked, there is a pop up that will display what was cleared from the cache. 

image::media/clear-added-content-cache-2.jpg[Example Popup]

You will need to reload the record in the staff client to obtain the new images from your 
Added Content Supplier.


Configure a Custom Image for Missing Images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can configure a "no image" image other than the standard 1-pixel
blank image.  The example eg_vhost.conf file provides examples in the
comments.  Note: Evergreen does not provide default images for these.


Including Locally Hosted Content in Your Public Interface
---------------------------------------------------------

It is also possible to show added content that has been generated locally 
by placing the content in a specific spot on the web server.  It is 
possible to have local book jackets, reviews, TOC, excerpts or annotations.

File Location and Format
~~~~~~~~~~~~~~~~~~~~~~~~

By default the files will need to be placed in directories under 
*/openils/var/web/opac/extras/ac/* on the server(s) that run Apache.

The files need to be in specific folders depending on the format of the 
added content.  Local Content can only be looked up based on the 
record ID at this time.

.URL Format:
\http://catalog/opac/extras/ac/*\{type}/\{format}/r/\{recordid}*

 * *type* is one of *jacket*, *reviews*, *toc*, *excerpt* or *anotes*.
  * *format* is type dependent:
    - for jacket, one of small, medium or large
    - others, one of html, xml or json ... html is the default for non-image added content
  * *recordid* is the bibliographic record id (bre.id).

Example
~~~~~~~

If you have some equipment that you are circulating such as a 
laptop or eBook reader and you want to add an image of the equipment 
that will show up in the catalog.

[NOTE]
=============
If you are adding jacket art for a traditional type of media 
(book, CD, DVD) consider adding the jacket art to the http://openlibrary.org 
project instead of hosting it locally.  This would allow other 
libraries to benefit from your work.
=============

Make note of the Record ID of the bib record.  You can find this by 
looking at the URL of the bib in the catalog.  
http://catalog/eg/opac/record/*123*, 123 is the record ID.  
These images will only show up for one specific record.

Create 3 different sized versions of the image in png or jpg format.

 * *Small* - 80px x 80px - named _123-s.jpg_ or _123-s.png_ - This is displayed in the browse display.
 * *Medium* - 240px x 240px - named _123-m.jpg_ or _123-m.png_ - This is displayed on the summary page.
 * *Large* - 400px x 399px - named _123-l.jpg_ or _123-l.png_ - This is displayed if the summary page image is clicked on.

[NOTE] 
The image dimensions are up to you, use what looks good in your catalog.
 
Next, upload the images to the evergreen server(s) that run apache, 
and move/rename the files to the following locations/name.  
You will need to create directories that are missing.
 
 * Small - Move the file *123-s.jpg* to */openils/var/web/opac/extras/ac/jacket/small/r/123*
 * Medium - Move the file *123-m.jpg* to */openils/var/web/opac/extras/ac/jacket/medum/r/123*.
 * Large - Move the file *123-l.jpg* to */openils/var/web/opac/extras/ac/jacket/large/r/123*.

[NOTE]
The system doesn't need the file extension to know what kind of file it is.
 
Reload the bib record summary in the web catalog and your new image will display.

Sitemap generator
-----------------
A http://www.sitemaps.org[sitemap] directs search engines to the pages of
interest in a web site so that the search engines can intelligently crawl
your site. In the case of Evergreen, the primary pages of interest are the
bibliographic record detail pages.

The sitemap generator script creates sitemaps that adhere to the
http://sitemaps.org specification, including:

* limiting the number of URLs per sitemap file to no more than 50,000 URLs;
* providing the date that the bibliographic record was last edited, so
  that once a search engine has crawled all of your sites' record detail pages,
  it only has to reindex those pages that are new or have changed since the last
  crawl;
* generating a sitemap index file that points to each of the sitemap files.

Running the sitemap generator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `sitemap_generator` script must be invoked with the following argument:

* `--lib-hostname`: specifies the hostname for the catalog (for example,
  `--lib-hostname https://catalog.example.com`); all URLs will be generated
  appended to this hostname

Therefore, the following arguments are useful for generating multiple sitemaps
per Evergreen instance:

* `--lib-shortname`: limit the list of record URLs to those which have copies
  owned by the designated library or any of its children;
* `--prefix`: provides a prefix for the sitemap index file names

Other options enable you to override the OpenSRF configuration file and the
database connection credentials, but the default settings are generally fine.

Note that on very large Evergreen instances, sitemaps can consume hundreds of
megabytes of disk space, so ensure that your Evergreen instance has enough room
before running the script.

Scheduling
~~~~~~~~~~
To enable search engines to maintain a fresh index of your bibliographic
records, you may want to include the script in your cron jobs on a nightly or
weekly basis.

Sitemap files are generated in the same directory from which the script is
invoked, so a cron entry will look something like:

------------------------------------------------------------------------
12 2 * * * cd /openils/var/web && /openils/bin/sitemap_generator
------------------------------------------------------------------------

Troubleshooting TPAC errors
---------------------------

If there is a problem such as a TT syntax error, it generally shows up as an
ugly server failure page. If you check the Apache error logs, you will probably
find some solid clues about the reason for the failure. For example, in the
following example, the error message identifies the file in which the problem
occurred as well as the relevant line numbers.

Example error message in Apache error logs:

----
bash# grep "template error" /var/log/apache2/error_log
[Tue Dec 06 02:12:09 2011] [warn] [client 127.0.0.1] egweb: template error:
 file error - parse error - opac/parts/record/summary.tt2 line 112-121:
  unexpected token (!=)\n  [% last_cn = 0;\n        FOR copy_info IN
  ctx.copies;\n            callnum = copy_info.call_number_label;\n
----