Table of Contents
Template Toolkit OPAC
- Author: Bill Erickson
- Create Date: 2011-03-08
Development todosdeprecated
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, click the Toggle Template Toolkit OPAC link on the staff client landing page. You might need to restart the staff client to make the change take effect.
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
. - Edit your Apache configuration to include the overriding template directory _after_ the main template directory:
# Templates will be loaded from the following paths in reverse order. PerlAddVar OILSWebTemplatePath "/openils/var/templates" PerlAddVar OILSWebTemplatePath "/openils/var/my_own_templates"
- You can, for example, customize skins on the basis of the hostname being used via virtual hosts; note that the base template directory gets loaded first in eg_vhost.conf, so you're just specifying the customizations here:
<VirtualHost *:80> ServerName myhostname DocumentRoot /openils/var/web/ DirectoryIndex index.xml index.html index.xhtml Include eg_vhost.conf <Location /eg> PerlAddVar OILSWebTemplatePath "/openils/var/my_own_templates" </Location> </VirtualHost>
- 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 theLocale::Maketext::Extract::Plugin::TT2
Perl module:sudo -u opensrf xgettext.pl --plugin=tt2 --directory=Open-ILS/src/templates/opac/ --output-dir=/openils/var/templates/locale --output=tpac.fr_CA.po
- Add your .po file to the Apache
eg_vhost.conf
file in the<Location /eg>
section:PerlAddVar OILSWebLocale "en_ca" PerlAddVar OILSWebLocale "/openils/var/templates/locale/tpac.en_CA.po" PerlAddVar OILSWebLocale "fr_ca" PerlAddVar OILSWebLocale "/openils/var/templates/locale/tpac.fr_CA.po"
- 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.