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

• Development todos

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

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

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/

2. Edit /openils/conf/oils_web.xml and change <path>/openils/var/web/templates</path> to <path>/openils/var/templates</path>
3. Reload or restart Apache.
4. Navigate to http://SERVER/eg/opac/home and you should see the KCLS-skinned server-side OPAC.

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

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

• Reload Apache.

• 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/ --output-dir=/openils/var/data/locale --output=messages.fr_CA.po

• Add your .po file to /openils/conf/oils_web.xml

      <locales>
          <en_US/>
          <en_CA>/openils/var/data/locale/messages.en_CA.po</en_CA>
          <fr_CA>/openils/var/data/locale/messages.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

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.