This is an old revision of the document!
Table of Contents
Template Toolkit OPAC
- Author: Bill Erickson
- Create Date: 2011-03-08
- Development plan (to replace above "todos?")
The Code
On 2011-09-11, the code was merged to the master branch of the Evergreen git repository at http://git.evergreen-ils.org.
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
The TPAC needs to be installed as part of an overall system upgrade to master; it will be an integrated part of the Evergreen 2.2 release.
Pay close attention to the following files on upgrade:
Open-ILS/examples/apache/eg_vhost.conf
- Perl modules, including the previously mentioned prerequisites
Open-ILS/src/templates/*
, which now gets installed into/openils/var/templates/
Open-ILS/web/*
, which includes stylesheets underOpen-ILS/web/css
and images underOpen-ILS/web/images
that are required by the TPAC.
Navigate to http://SERVER/eg/opac/home and you should see the default server-side TPAC skin
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.