This is an old revision of the document!
Table of Contents
Template Toolkit OPAC
- Author: Bill Erickson
- Create Date: 2011-03-08
The Code
The code currently lives in an ESI Git branch called "template-toolkit-opac". You can view the code and watch changes here.
Downloading the code by creating a git clone of the branch
$ git clone git://git.evergreen-ils.org/evergreen/equinox.git $ cd equinox $ git checkout -tb template-toolkit-opac origin/template-toolkit-opac
The code changes frequently. You can update the code by pulling changes from the repository.
$ git checkout template-toolkit-opac # just in case $ git pull
Installation
Prerequisites
- Install the following additional Perl modules via OS package manager or CPAN:
- Template::Plugin::POSIX
- Locale::Maketext::Lexicon
Installing Over an existing Evergreen installation (2.1+)
- Copy these files from the repository into place on the file system. Your mileage may vary on OS-dependent paths. Note: Be careful not to clobber local changes you didn't want clobbered.
$ sudo cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/ $ sudo -u opensrf cp Open-ILS/examples/oils_web.xml.example /openils/conf/oils_web.xml $ sudo cp -r Open-ILS/src/perlmods/lib/OpenILS/WWW/* /usr/local/share/perl/5.10.1/OpenILS/WWW/ $ sudo -u opensrf cp -r Open-ILS/src/templates* /openils/var/
- Edit /openils/conf/oils_web.xml and change <path>/openils/var/web/templates</path> to <path>/openils/var/templates</path>
- Reload or restart Apache.
- Navigate to http://SERVER/eg/opac/home and you should see the KCLS-skinned server-side OPAC.
Staff Client Integration
- The eventual goal is to fully integrate the TT OPAC into the staff client. Until it's complete, it's necessary to manually configure the staff client to use the new OPAC.
- To use the Template Toolkit OPAC as the catalog in the staff client, as opensrf:
echo "urls['opac'] = '/eg/opac/advanced'; urls['opac_rdetail'] = '/eg/opac/record/'; urls['opac_rresult'] = '/eg/opac/results'; urls['opac_rresult_metarecord'] = '/eg/opac/results?metarecord='; urls['browser'] = urls.opac;" > /openils/var/web/xul/server/skin/custom.js;
Customizing
Skinning
Skinning the TT OPAC is much easier than skinning previous incarnations of the Evergreen OPAC.
- Create a directory where you will store your template customizations, let's say
/openils/var/my_own_templates
.
- Look for the node
<template_paths>
in your/openils/conf/oils_web.xml
file.
- Add a new
<path>
child node directly above all existing ones so that everything within<template_paths>
now looks something like this:
<template_paths> <path>/openils/var/my_own_templates</path> <path>/openils/var/templates</path> </template_paths>
- Place your version of all
.tt2
files that you would edit into a directory structure that mirrors that of the stock template path. That is, if you want to have your own version of/openils/var/templates/default/opac/parts/topnav.tt2
, put it at/openils/var/my_own_templates/default/opac/parts/topnav.tt2
.
- Do not copy every file under
/openils/var/templates
intomy_own_templates
– that is not necessary.
- Reload Apache.
String Localization
- Create a .po file for your locale. Requires Locale::Maketext::Extract::Plugin::TT2
sudo -u opensrf xgettext.pl --plugin=tt2 --directory=Open-ILS/src/templates/opac/ --output-dir=/openils/var/data/locale --output=tpac.fr_CA.po
- Add your .po file to /openils/conf/oils_web.xml
<locales> <en_US/> <en_CA>/openils/var/data/locale/tpac.en_CA.po</en_CA> <fr_CA>/openils/var/data/locale/tpac.fr_CA.po</fr_CA> </locales>
- Edit strings in your new .po file. For example:
... #: Open-ILS/src/templates/opac/parts/topnav.tt2:34 msgid "My Account" msgstr "Mon compte" ...
- Reload Apache. (Translations are cached in the browser)
- To test, reload the page with fr-CA as the browser's default locale
Custom Perl Handler
It's possible to override specific behavior of the default OPAC mod_perl handler by sub-classing the default and selecting methods to override.
- Create a local Perl module that is a subclass of OpenILS::WWW::EGCatLoader. Example:
package EGCatLoaderLocal; use base 'OpenILS::WWW::EGCatLoader'; # override a single method sub redirect_auth { my $self = shift; return $self->generic_redirect("http://my-fancy-auth-service.example.org"); }
- Configure the new Perl module as the OPAC handler in Apache
<Location /eg/opac> #PerlSetVar OILSWebContextLoader "OpenILS::WWW::EGCatLoader" PerlSetVar OILSWebContextLoader "EGCatLoaderLocal" </Location>
- Reload Apache
Development conventions
- Use the localization macro (
l()
) to mark text that needs to be translated:<h1>[% l('Search results') %]</h1>
The localization macro accepts parameters so that you can create complex strings that represent a complete sentence or translatable phrase. In the following example, variable
[_1]
is replaced by the value of the first argument, user_name, and[_2]
is replaced by the value of the second argument, library_name:[% l('Hello [_1]! You are browsing the [_2] catalog', user_name, library_name) %]
- Escape output to prevent XSS vulnerabilities and broken HTML.Use the
html
filter to escape text generated from outside of the template in HTML, and theuri
filter to escape URIs. For example, in the following example the text in the first table cell is not escaped because it is static text from the template itself, while the attrs.author text comes from the database and therefore should be escaped:<td>[% l("Author:") %]'</td><td>[% attrs.author | html %]</td>
Note that the
uri
filter is not necessary in cases where the URI has passed through the CGI plugin, such as in themkurl()
macro.