Template Toolkit OPAC

• Author: Bill Erickson
• Create Date: 2011-03-08

• Development todos deprecated
• Development plan

On 2011-09-11, the code was merged to the master branch of the Evergreen git repository at http://git.evergreen-ils.org.

1. Install the following additional Perl modules via OS package manager or CPAN:
   • Template::Plugin::POSIX
   • Locale::Maketext::Lexicon

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 under Open-ILS/web/css and images under Open-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

• 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.

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 into my_own_templates – that is not necessary.

• Reload Apache.

• Create a .po file for your locale. Requires the Locale::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

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

• 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 the uri 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 the mkurl() macro.