Customizing the OPAC
While Evergreen is ready to go out of the box, libraries will want to customize Evergreen with their own color scheme, logos and layout. This chapter will explain how to
customize Evergreen to meet the needs of your users. For these task some knowledge of html and css is required. Many of these
instructions assume an installation of Evergreen using the default file locations.
Be sure to save a backup copy of all files you edit in a location other than /openils/var/web/opac/ as files here could be
overwritten when you upgrade your copy of Evergreen.
Change the Color Scheme
To change the color scheme of the default Evergreen skin, edit /openils/var/web/opac/theme/default/css/colors.css . From this one file you can
change the 4 base color scheme as well as colors of specific elements.
You can also create alternate themes for your users.
Copy the css folder and its contents from the example alternate theme /openils/var/web/opac/theme/reddish/
to a new folder /openils/var/web/opac/theme/[your new theme] / .
Edit /openils/var/web/opac/theme/[your new theme] /css/colors.css to use the colors you want.
Link to your new style sheet by adding the following to /openils/var/web/opac/skin/default/xml/common/css_common.xml .
<link type='text/css'
rel="alternate stylesheet"
title='&opac.style.yourtheme;'
href="<!--#echo var='OILS_THEME_BASE'-->/yourtheme/css/colors.css"
name='Default' csstype='color'/>
Give your new theme a name users can select by adding the following to /openils/var/web/opac/locale/
[your locale] /opac.dtd .
<!ENTITY opac.style.yourtheme "YourTheme">
customizing Opac Text and Labels
To change text and links used throughout the OPAC, edit the following files:
/openils/var/web/opac/locale/[your locale] /lang.dtd
/openils/var/web/opac/locale/[your locale] /opac.dtd
A better way to customize OPAC text is to create custom dtd files for your lang and opac customizations and then add a include
statement above the default dtd files.
<!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!--#include virtual="/opac/locale/${locale}/custom_opac.dtd"-->
<!--#include virtual="/opac/locale/${locale}/opac.dtd"-->
]>
position is important here. The first/top included dtd files will take precedence over the subsequent dtd includes.
While it is possible to add text to the xml files itself, it is a good practice to use the DTD file to control the text and refer to the DTD elements in the xml/html code.
For example, the footer.xml file has this code to generate a copyright statement:
<div id='copyright_text'>
<span>&footer.copyright;</span>
The included opac.dtd file in the en-US locale directory has this setting for &footer.copyright text:
<!ENTITY footer.copyright "Copyright © 2006-2010 Georgia Public Library Service, and others">
Logo Images
To change the logos used by default to your own logos, replace the following files with images of your own, appropriately sized.
Large main logo:/openils/var/web/opac/images/main_logo.jpg
Small logo:/openils/var/web/opac/images/small_logo.jpg
Added Content
By default Evergreen includes customizable Added Content
features to enhance the OPAC experience for your user. These features include Amazon book covers
and Google books searching. These features can be turned off or customized.
Book Covers
The default install of Evergreen includes Amazon 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::Amazon</module>
This calls the Amazon perl module. If you wish to link to a different book cover service other than Amazon, you must create a new perl module and refer to it here.
You will also need to change other settings accordingly. There are some available book cover perl modules available in
trunk
<base_url>http://images.amazon.com/images/P/</base_url>
Base URL for Amazon added content fetching. This URL may need to be shortened when new (read: non-image) content fetching
capabilities are added.
<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>
After added content lookups have been disabled due to too many lookup failures, this 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 live before added content lookups are disabled for everyone.
<userid>MY_USER_ID</userid>
If a userid is required to access the added content.
Google Books Link
The results page will display a Browse in Google Books Search link for items in the results page which have corresponding entries
in Google Books .
This will link to Google Books content including table of contents and complete versions of the work if it exists in Google Books. Items not in Google Books will not
display a link. This feature can be turned off by changing the googleBooksLink variable setting to false in the file
/openils/var/web/opac/skin/default/js/result_common.js . By default, this feature is activated.
Customizing the Results Page
The results page is extremely customizable and allows some built in features to be activated with some simple edits or more advanced customizations can be done by more
experienced web developers.
There are several critical files to edit if you wish to customize the results page:
/openils/var/web/opac/skin/default/js/result_common.js - This file controls the JavaScript for the top level elements on the results
page and should only be edited by experienced web developers except for the Google books link setting mentioned previously.
/openils/var/web/opac/skin/default/js/rresult.js - Has some good controls of results page settings at the top of this file but
requires web development skills for editing this file.
/openils/var/web/opac/skin/default/xml/result/rresult_table.xml - This controls the layout of the items table on results page.
Customizing the Details Page
There are many options when customizing the details page in Evergreen. The default settings are effective for most libraries, but it is important to understand the full potential
of Evergreen when displaying the details of items.
Some quick features can be turned on and off by changing variable values in the file /openils/var/web/opac/skin/default/js/rdedail.js .
You will notice the section at the top of this file called Per-skin configuration settings
. Changing setting in this section can control several features including
limiting results to local only or showing copy location or displaying serial holdings. Form this section you can also enable refworks and set the Refworks host URL.
Some copy level details settings can be turned on and off from /openils/var/web/opac/skin/default/js/copy_details.js including displaying certain fields
such as due date in the OPAC.
An important file is the /openils/var/web/opac/skin/default/xml/rdetail/rdetail_summary.xml file. This file allows you to control which field to display in
the details summary of the record. The new BibTemplate feature makes this file even more powerful by allowing you to display any marc fields
with a variety of formatting options.
The /openils/var/web/opac/skin/default/xml/rdetail/rdetail_copyinfo.xml file allows you to format the display of the copy information.
BibTemplate BibTemplate
BibTemplate is an Evergreen-custom Dojo module which can be used to retrieve and format XML data served by the Evergreen unAPI service. unAPI is a protocol for requesting known objects in specific formats, and Evergreen uses this to supply data – bibliographic records,
metarecords, monograph holdings information, Located URIs, and more to come – in many different formats from MARCXML to MODS to custom XML applications.
unAPI MARCXML MODS
Managing the display of information from raw XML can be difficult, and the purpose of BibTemplate is to make this simpler, as well as move the display closer to the
client and away from the source data. This is good from a separation-of-responsibilities perspective, and also makes it easier to contain and control local customization.
BibTemplate supports the following Evergreen meta data formats:
MARCXML - datatype='marcxml-full' (default)
MODS 3.3: datatype='mods33'
Dublin Core: datatype='rdf_dc' Dublin Core
FGDC: datatype='fgdc' FGDC
HTML API
BibTemplate follows the Dojo convention of adding attributes to existing (X)HTML in order to progressively change its behavior. The 1.6.0 HTML API consists of a
set of attributes that are added to existing OPAC markup, and fall into two classes: Dojo toolkit
The slot marker – Elements that denote the location of bibliographic data to insert.
The slot formatter – Elements that specify how the named data should be formatted for display.
Slot Marker slot marker
A slot marker is any displayable HTML element that has a type attribute with a value starting with opac/slot-data. This element will become the container
for the formatted data. A slot marker is required in order to retrieve, format and display data using BibTemplate. A slot marker must also have an
attribute called query containing a CSS3 selector. This selector is applied to the XML returned by the unAPI service in order to gather the specific XML
Nodes that should be considered for formatting. CSS3
The slot marker can also specify the format of the data to be returned from the unAPI service. This can be specified by adding +{format} to the type
attribute, as in opac/slot-data+mods33-full. The default data format is marcxml-uri, which is an augmented MARCXML record containing Located URI information
and unAPI links.
Example of a slot marker:
<p type='opac/slot-data' query='datafield[tag=245]'></p>
Most useful attribute match operators include:
datafield[tag=245] - exact match
datafield[tag^=65] - match start of value
Selectors always narrow, so select broadly and iterate through the NodeList
Slot Formatter slot formatter
A slot formatter is any invisible HTML element which has a type attribute with the value of opac/slot-format. (NOTE: before 1.6.0.4, only <script>
elements were supported, though this restriction is now removed to support Internet Explorer.) Only one slot formatter element is allowed in each slot. The text contents
of this element are wrapped in a JavaScriptJavaScript function and run for each node returned by the query CSS3 selector
specified on the slot marker. This function is passed
one argument, called item, which an XML Node captured by the selector. This function should return HTML text. The output for all runs of the slot formatter is
concatenated into a single string and used to replace the contents of the slot marker.
The slot formatter is optional, and if not supplied BibTemplate will create a simple function which extracts and returns the text content of the XML Nodes
specified in the CSS3 selector.
Example of a slot formatter:
<td class='rdetail_item' id='rdetail_online' type='opac/slot-data' query='volumes volume uris uri' join=", ">
<script type='opac/slot-format'><![CDATA[
var link = '<a href="' + item.getAttribute('href') + '">' + item.getAttribute('label') + '</a>';
if (item.getAttribute('use_restriction'))
link += ' (Use restriction: ' + item.getAttribute('use_restriction') + ')';
return link;
]]></script>
</td>
JavaScript API JavaScript
In order for BibTemplate to find the slot markers and invoke the slot formatters JavaScript renderer must be instantiated and called. This must be done
for each record that is to contribute to a pages display. The API for this is simple and straight-forward:
The slot formatter is optional, and if not supplied BibTemplate will create a simple function which extracts and returns the text content of the XML Nodes
specified in the CSS3 selector. CSS3
Example of a slot formatter:
dojo.require('openils.BibTemplate'); // Tell Dojo to load BibTemplate, if it is not already loaded
// Create a renderer supplying the record id and the short name of the org unit, if known, and call the render() method
new openils.BibTemplate({ record : new CGI().param('r'), org_unit : here.shortname() }).render();
The argument hash supplied to the new openils.BibTemplate() constructor can have the following properties:
record – The bibliographic record ID.
org_unit – The relevant Organizational Unit, used to restrict holdings scope as on a search result or record detail page.
root – The root element within the web page that BibTemplate should search for slot markers
BibTemplate Examples
This is all that we had to add to display the contents of an arbitrary MARC field:
<tr>
<td>Bibliography note</td>
<td type='opac/slot-data' query='datafield[tag=504]'></td>
</tr>
If multiple fields match, they are displayed on consecutive lines within the same left-hand cell.
To display a specific MARC subfield, add that subfield to the query attribute. MARC
For example, subfield $a is the only user-oriented subfield in field 586 (Awards Note)
<tr>
<td>Awards note</td>
<td type='opac/slot-data' query='datafield[tag=586] subfield[code=a]'></td>
</tr>
Hide empty rows by default, and display them only if they have content:
<tr class='hide_me' id='tag504'>
<td>Bibliographic note</td>
<td type='opac/slot-data' query='datafield[tag=504]'>
<script type='opac/slot-format'><![CDATA[
dojo.query('#tag504').removeClass('hide_me');
return '<span>' + dojox.data.dom.textContent(item) +
'</span><br/>';
]]></script>
</td></tr>
<![CDATA[ ... ]]> tells Evergreen Web server to treat the contents as literal character data
-
avoids hilarity of entity substitution
<script type='opac/slot-format'>...</script>, contained within an opac/slot-data
element, receives a variable named item
containing the results of the query (a NodeList)
Suppressing a subfield:
<tr class='hide_me' id='tag700'>
<td>Additional authors</td>
<td type='opac/slot-data' query='datafield[tag=700]'>
<script type='opac/slot-format'><![CDATA[
dojo.query('#tag700').removeClass('hide_me');
var text = '';
var list = dojo.query('subfield:not([code=4])', item);
for (var i =0; i < list.length; i++) {
text += dojox.data.dom.textContent(list[i]) + ' ';
}
return '<span>' + text + '</span><br/>';
]]></script>
</td></tr>
Customizing the Slimpac
The Slimpac is the an alternative OPAC display for browsers or devices without JavaScript or which may have screen size limitations. There is both a simple and advanced search
option for the Slimpac.
The html files for customizing the Slimpac search display are located in the folder /openils/var/web/opac/extras/slimpac .
start.html is the basic search display and advanced.html is the display for the advanced search option.
By default, the Slimpac files include the same locale dtd as the regular OPAC (opac.dtd ). However, the slimpac files do not use the same CSS files as the
regular OPAC which means that if you change the OPAC color scheme, you must also edit the Slimpac files.