--- /dev/null
+<?xml version="1.0" encoding="utf-8"?>\r
+<chapter xml:id="Customizing_OPAC" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
+ xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
+ <info>\r
+ <title>Customizing the OPAC</title>\r
+ </info>\r
+ <para>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 \r
+ 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 a default installation of \r
+ Evergreen using the default file locations.</para>\r
+ <note>\r
+ <para>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 \r
+ of Evergreen.</para>\r
+ </note> \r
+ <section xml:id="ColorScheme">\r
+ <title>Change the Color Scheme</title>\r
+ <para>To change the color scheme of the default Evergreen skin, edit <filename>/openils/var/web/opac/theme/default/css/colors.css</filename>. From this one file you can \r
+ change the 4 base color scheme as well as colors of specific elements. \r
+ </para> \r
+ <para>You can also create alternate themes for your users.</para> \r
+ <procedure>\r
+ <step>\r
+ <para>Copy the css folder and its contents from the example alternate theme <filename>/openils/var/web/opac/theme/reddish/</filename> \r
+ to a new folder <filename>/openils/var/web/opac/theme/<emphasis>[your new theme]</emphasis>/</filename>.</para>\r
+ </step> \r
+ <step>\r
+ <para>Edit /openils/var/web/opac/theme/<emphasis>[your new theme]</emphasis>/css/colors.css to use the colors you want.</para>\r
+ </step>\r
+ <step>\r
+ <para>Link to your new style sheet by adding the following to <filename>/openils/var/web/opac/skin/default/xml/common/css_common.xml</filename>.</para>\r
+ <screen><link type='text/css'</screen> \r
+ <screen>rel="alternate stylesheet"</screen> \r
+ <screen>title='&opac.style.yourtheme;'</screen> \r
+ <screen>href="<!--#echo var='OILS_THEME_BASE'-->/yourtheme/css/colors.css"</screen> \r
+ <screen>name='Default' csstype='color'/></screen> \r
+ </step> \r
+ <step>\r
+ <para> Give your new theme a name users can select by adding the following to <filename>/openils/var/web/opac/locale/<emphasis>\r
+ [your locale]</emphasis>/opac.dtd</filename>.</para>\r
+ <screen><!ENTITY opac.style.yourtheme "YourTheme"></screen> \r
+ </step> \r
+ </procedure> \r
+ </section>\r
+ <section xml:id="customizing_opac_text">\r
+ <title>customizing Opac Text and Labels</title>\r
+ <para>To change text and links used throughout the OPAC, edit the following files:</para>\r
+ <itemizedlist>\r
+ <listitem><filename>/openils/var/web/opac/locale/<emphasis>[your locale]</emphasis>/lang.dtd</filename></listitem>\r
+ <listitem><filename>/openils/var/web/opac/locale/<emphasis>[your locale]</emphasis>/opac.dtd</filename></listitem>\r
+ </itemizedlist>\r
+ <tip>\r
+ <para>A better way to customize OPAC text is to create custom <emphasis>dtd</emphasis> files for your lang and opac customizations and then add a include \r
+ statement above the default dtd files.</para>\r
+ <screen><!DOCTYPE html PUBLIC</screen> \r
+ <screen>"-//W3C//DTD XHTML 1.0 Transitional//EN"</screen> \r
+ <screen>"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [</screen>\r
+ <screen><!--#include virtual="/opac/locale/${locale}/custom_opac.dtd"--></screen>\r
+ <screen><!--#include virtual="/opac/locale/${locale}/opac.dtd"--></screen>\r
+ <screen>]></screen>\r
+ <para>position is important here. The first/top included <emphasis>dtd</emphasis> files will take precedence over the subsequent dtd includes.</para> \r
+ </tip>\r
+ <para>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.</para> \r
+ <para>For example, the footer.xml file has this code to generate a copyright statement:</para>\r
+ <screen><div id='copyright_text'></screen>\r
+ <screen><span>&footer.copyright;</span></screen>\r
+ <para>The included <filename>opac.dtd</filename> file in the en-US locale direcotry has this setting for &footer.copyright text:</para> \r
+ <screen><!ENTITY footer.copyright "Copyright © 2006-2010 Georgia Public Library Service, and others"></screen>\r
+ </section>\r
+ <section xml:id="Logo_Images">\r
+ <title>Logo Images</title>\r
+ <para>To change the logos used by default to your own logos, replace the following files with images of your own, appropriately sized. </para>\r
+ <itemizedlist>\r
+ <listitem><filename>/openils/var/web/opac/images/main_logo.jpg</filename></listitem>\r
+ <listitem><filename>/openils/var/web/opac/images/main_logo.jpg</filename></listitem>\r
+ </itemizedlist> \r
+ </section>\r
+ <section xml:id="AddedContent">\r
+ <title>Added Content</title>\r
+ <para>By default Evergreen includes customizable <quote>Added Content</quote> features to enhance the OPAC experience for your user. These features include Amazon book covers \r
+ and Google books searching. These features can be turned off or custimized.</para>\r
+ <simplesect xml:id="bookcovers">\r
+ <title>Book Covers</title>\r
+ <para>The default install of Evergreen includes Amazon book covers. The settings for this are controlled by the <added_content> section of \r
+ <filename>/opneils/conf/opensrf.xml</filename>. Here are the key elements of this configuration:</para> \r
+ <screen><module>OpenILS::WWW::AddedContent::Amazon</module></screen>\r
+ <para>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. \r
+ You will also need to change other settings accordingly. There are some available book cover perl modules available in \r
+ <ulink url="http://svn.open-ils.org/trac/ILS/browser/trunk/Open-ILS/src/perlmods/OpenILS/WWW/AddedContent">trunk</ulink></para>\r
+ <screen><base_url>http://images.amazon.com/images/P/</base_url></screen>\r
+ <para>Base URL for Amazon added content fetching. This URL may need to be shortened when new (read: non-image) content fetching \r
+ capabilities are added.</para> \r
+ <screen><timeout>1</timeout></screen>\r
+ <para>Max number of seconds to wait for an added content request to return data. Data not returned within the timeout is considered a failure.</para> \r
+ <screen><retry_timeout>600</retry_timeout></screen>\r
+ <para>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.</para>\r
+ <screen><max_errors>15</max_errors></screen>\r
+ <para>Maximum number of consecutive lookup errors a given process can live before added content lookups are disabled for everyone.</para> \r
+ <screen><userid>MY_USER_ID</userid></screen>\r
+ <para>If a userid is required to access the added content.</para>\r
+ </simplesect>\r
+ <simplesect xml:id="googlebookslink">\r
+ <title>Google Books Link</title>\r
+ <para>The results page will display a <quote>Browse in Google Books Search</quote> link for items in the results page which have corresponding entries in Google Books. \r
+ 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 \r
+ display a link. This feature can be turned off by changing the googleBooksLink variable setting to <quote>false</quote>in the file \r
+ <filename>/openils/var/web/opac/skin/default/js/result_common.js</filename>. By default, this feature is activated. </para> \r
+ </simplesect> \r
+ </section>\r
+ <section xml:id="resultspage">\r
+ <title>Customizing the Results Page</title>\r
+ <para>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 \r
+ experienced web developers.</para>\r
+ <para>There are several critical files to edit if you wish to customize the results page:</para>\r
+ <itemizedlist>\r
+ <listitem><filename>/openils/var/web/opac/skin/default/js/result_common.js</filename> - This file controls the javascript for the top level elements on the results \r
+ page and should only be edited by experienced web developers except for the <link linkend='googlebookslink'>google books link setting</link> mentioned perviously.</listitem>\r
+ <listitem><filename>/openils/var/web/opac/skin/default/js/rresult.js</filename> - Has some good controls of results page settings at the top of this file but \r
+ requires web development skills for editing this file.</listitem>\r
+ <listitem><filename>/openils/var/web/opac/skin/default/xml/result/rresult_table.xml</filename> - This controls the layout of the items table on results page.</listitem>\r
+ </itemizedlist> \r
+ </section>\r
+ <section xml:id="deatailspage">\r
+ <title>Customizing the Details Page</title>\r
+ <para>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 \r
+ of Evergreen when displaying the details of items.</para> \r
+ <para>Some quick features can be turned on and off by changing variable values in the file <filename>/openils/var/web/opac/skin/default/js/rdedail.js</filename>. \r
+ You will notice the section at the top of this file called <quote>Per-skin configuration settings</quote>. Changing setting in this section can control several features includuing \r
+ 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.</para>\r
+ <para>Some copy level details settings can be turned on and off from <filename>/openils/var/web/opac/skin/default/js/copy_details.js</filename> including displaying certain fields \r
+ such as due date in the OPAC.</para>\r
+ <para>An important file is the <filename>/openils/var/web/opac/skin/default/xml/rdetail/rdetail_summary.xml</filename> file. This file allows you to control which field to display in \r
+ the details summary of the record. The new <link linkend='googlebookslink'>BibTemnplate</link> feature makes this file even more powerful by allowing you to display any marc fields \r
+ with a variey of formatting options.</para>\r
+ <para>The <filename>/openils/var/web/opac/skin/default/xml/rdetail/rdetail_copyinfo.xml</filename> file allows you to format the display of the copy information.</para> \r
+ </section> \r
+ <section xml:id="BibTemplate">\r
+ <title>BibTemplate</title>\r
+ <para>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 – \r
+ in many different formats from MARCXML to MODS to custom XML applications.</para> \r
+ <para>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 \r
+ 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.</para>\r
+ <para>BibTemplate supports the foloowing Evergreen metadata formats:</para>\r
+ <itemizedlist>\r
+ <listitem>MARCXML - datatype='marcxml-full' (default)</listitem> \r
+ <listitem>MODS 3.3: datatype='mods33'</listitem>\r
+ <listitem>Dublin Core: datatype='rdf_dc'</listitem>\r
+ <listitem>FGDC: datatype='fgdc'</listitem>\r
+ </itemizedlist> \r
+ <simplesect>\r
+ <title>HTML API</title>\r
+ <para>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 \r
+ set of attributes that are added to existing OPAC markup, and fall into two classes:</para>\r
+ <itemizedlist>\r
+ <listitem> The slot marker – Elements that denote the location of bibliographic data to insert.</listitem>\r
+ <listitem>The slot formatter – Elements that specify how the named data should be formatted for display.</listitem>\r
+ </itemizedlist> \r
+ </simplesect>\r
+ <simplesect>\r
+ <title>Slot Marker</title>\r
+ <para>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 \r
+ 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 \r
+ 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 \r
+ Nodes that should be considered for formatting.</para>\r
+ <para>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 \r
+ 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 \r
+ and unAPI links.</para>\r
+ <para>Example of a slot marker:</para>\r
+ <screen><p type='opac/slot-data' query='datafield[tag=245]'></p></screen>\r
+ <para>Most useful attribute match operators include:</para>\r
+ <itemizedlist>\r
+ <listitem> datafield[tag=245] - exact match</listitem>\r
+ <listitem>datafield[tag^=65] - match start of value</listitem>\r
+ </itemizedlist> \r
+ <tip><para>Selectors always narrow, so select broadly and iterate through the NodeList</para></tip>\r
+ </simplesect>\r
+ <simplesect>\r
+ <title>Slot Formatter</title>\r
+ <para>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> \r
+ 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 \r
+ of this element are wrapped in a JavaScript function and run for each node returned by the query CSS3 selector specified on the slot marker. This function is passed \r
+ 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 \r
+ concatenated into a single string and used to replace the contents of the slot marker.</para>\r
+ <para>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 \r
+ specified in the CSS3 selector.</para>\r
+ <para>Example of a slot formatter:</para>\r
+ <programlisting>\r
+ <td class='rdetail_item' id='rdetail_online' type='opac/slot-data' query='volumes volume uris uri' join=", ">\r
+ <script type='opac/slot-format'><![CDATA[\r
+ var link = '<a href="' + item.getAttribute('href') + '">' + item.getAttribute('label') + '</a>';\r
+ if (item.getAttribute('use_restriction'))\r
+ link += ' (Use restriction: ' + item.getAttribute('use_restriction') + ')';\r
+ return link;\r
+ ]]></script>\r
+ </td>\r
+ </programlisting>\r
+ </simplesect>\r
+ <simplesect>\r
+ <title>JavaScript API</title>\r
+ <para>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 \r
+ for each record that is to contribute to a pages display. The API for this is simple and straight-forward:</para>\r
+ <para>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 \r
+ specified in the CSS3 selector.</para>\r
+ <para>Example of a slot formatter:</para>\r
+ <programlisting>\r
+ dojo.require('openils.BibTemplate'); // Tell Dojo to load BibTemplate, if it is not already loaded\r
+ \r
+ // Create a renderer supplying the record id and the short name of the org unit, if known, and call the render() method \r
+ new openils.BibTemplate({ record : new CGI().param('r'), org_unit : here.shortname() }).render(); \r
+\r
+ </programlisting>\r
+ <para>The argument hash supplied to the new openils.BibTemplate() constructor can have the following properties:</para>\r
+ <itemizedlist>\r
+ <listitem>record – The bibliographic record ID.</listitem>\r
+ <listitem>org_unit – The relevant Organizational Unit, used to restrict holdings scope as on a search result or record detail page.</listitem>\r
+ <listitem>root – The root element within the web page that BibTemplate should search for slot markers</listitem>\r
+ </itemizedlist> \r
+ </simplesect>\r
+ <simplesect>\r
+ <title>BibTemplate Examples</title>\r
+ <para>This is all that we had to add to display the contents of an arbitrary MARC field:</para>\r
+ <programlisting>\r
+ <tr>\r
+ <td>Bibliography note</td>\r
+ <td type='opac/slot-data' query='datafield[tag=504]'></td>\r
+ </tr>\r
+ </programlisting>\r
+ <note><para>If multiple fields match, they are displayed on consecutive lines within the same left-hand cell.</para></note>\r
+ <para>To display a specific MARC subfield, add that subfield to the query attribute.</para>\r
+ <para>For example, subfield $a is the only user-oriented subfield in field 586 (Awards Note)</para>\r
+ <programlisting>\r
+ <tr>\r
+ <td>Awards note</td>\r
+ <td type='opac/slot-data' query='datafield[tag=586] subfield[code=a]'></td>\r
+ </tr>\r
+ </programlisting>\r
+ <para>Hide empty rows by default, and display them only if they have content:</para>\r
+ <programlisting>\r
+ <tr class='hide_me' id='tag504'>\r
+ <td>Bibliographic note</td>\r
+ <td type='opac/slot-data' query='datafield[tag=504]'>\r
+ <script type='opac/slot-format'><![CDATA[\r
+ dojo.query('#tag504').removeClass('hide_me');\r
+ return '<span>' + dojox.data.dom.textContent(item) +\r
+ '</span><br/>';\r
+ ]]></script>\r
+ </td></tr>\r
+ </programlisting>\r
+ <itemizedlist>\r
+ <listitem><![CDATA[ ... ]]> tells Evergreen Web server to treat the contents as literal <quote>character data</quote> - \r
+ avoids hilarity of entity substitution</listitem>\r
+ <listitem><script type='opac/slot-format'>...</script>, contained within an 'opac/slot-data' element, receives a variable named item \r
+ containing the results of the query (a NodeList)</listitem> \r
+ </itemizedlist> \r
+ <para>Suppressing a subfield:</para>\r
+ <programlisting>\r
+ <tr class='hide_me' id='tag700'>\r
+ <td>Additional authors</td>\r
+ <td type='opac/slot-data' query='datafield[tag=700]'>\r
+ <script type='opac/slot-format'><![CDATA[\r
+ dojo.query('#tag700').removeClass('hide_me');\r
+ var text = '';\r
+ var list = dojo.query('subfield:not([code=4])', item);\r
+ for (var i =0; i < list.length; i++) {\r
+ text += dojox.data.dom.textContent(list[i]) + ' ';\r
+ }\r
+ return '<span>' + text + '</span><br/>';\r
+ ]]></script>\r
+ </td></tr>\r
+ </programlisting>\r
+ </simplesect>\r
+ </section>\r
+</chapter>\r
+\r
projects / working / Evergreen.git / commitdiff