The Template Toolkit OPAC (TPAC) is a new catalog built for low-bandwidth connections and easy customization. This session will teach you how it is constructed and how to customize and contribute to it yourself.

This talk is licensed under a Creative Commons, Attribution, Share Alike license.

Slides and sources available at git.evergreen-ils.org:working/random.git

Why TPAC?

Thus spake Dan Scott on January 7, 2011, in the thread Planning for Evergreen development, post 2.0:

Provide a full-featured OPAC that requires no JavaScript, but uses
JavaScript for enhancements

Why: The current OPAC takes an agonizing amount of time to load when
the JavaScript is not cached: 10 - 15 seconds on a DSL connection is
pretty normal http://www.useit.com/alertbox/response-times.html has
some interesting observations on Web response times, but we all know
that 10 seconds is not fast. The underlying HTML of the current OPAC
is also useless to Google and other search engines; a rewrite that
generated semantically meaningful HTML could actually provide
another entry point into our catalogues.

On March 4th, 2011, Bill Erickson said in the thread Server-side OPAC development project: an introduction:

As some of you may know from various IRC discussions, etc., Equinox
(ESI) is partnering with the King County Library System to build a
server-side (i.e.  non-Javascript driven) Template Toolkit OPAC.
The purpose of this project is to re-architect the OPAC with a set
of web development tools that will allow us to manage the logic of
data retrieval and display on the server instead of in the client
to provide a faster and more consistent OPAC experience.  This work
will improve OPAC rendering across browsers as well as have a
significant impact on overall performance, particularly for users
on slower networks.

Why TPAC (as of April 2012)

Evergreen already uses Template Toolkit
Speed (initial page loading and rendering)
Reduced per-feature speed cost
Cross-browser consistency
Flexible template engine (overlays, etc.) improves skinning
Accessibility
Dynamic, gettext-based string translations
Simplified error detection. Errors occur on the server.
Reduced variability of code in the wild (JS caching)
Reduced bandwidth requirements
Reduced client resources (RAM/CPU) requirements
JavaScript/AJAX is still an option when needed (autosuggest, added content, staff client integration)

TPAC vs JSPAC Crude Speed Comparison

Very professional test methodology
- Timing data collected from Chrome’s Developer Tools → Network pane
- Performed a search to pre-cache the search and page elements (images, JS, etc.), then collected timing from 3 page reloads each.
- Average times are for full page load.
- Test server was 350 miles away.
JSPAC
- 6.92 seconds.
- 494 KB transferred
TPAC
- 2.49 seconds.
- 118 KB transferred
TPAC with AutoSuggest enabled (i.e. Dojo).
- 2.84 seconds.
- 130 KB transferred (note: dojo.js is already cached)

Why the difference?

JSPAC vs TPAC Network

*100% Accurate Representation.

Instrumenting TPAC

Lesson: Hackfests can produce working code!

2.5 seconds is better than JSPAC, but still slower than ideal. So where’s the bottleneck?
Approach: if debug timing is enabled, capture timing & event descriptions from the Perl modules behind the scenes in a context variable, then display those results in the page footer

OpenILS/WWW/EGCatLoader.pm

use constant DEBUG_TIMING => 1;

$self->timelog("Returned from get_records_and_facets()");

Page footer timings

Template Toolkit (TT) Syntax

Template-Toolkit.org

TT Syntax - Blocks

[% starts a TT block; %] ends a block
[%- starts a block and gobbles up the preceding whitespace and newline
-%] ends a block and gobbles up the subsequent whitespace and newline
Use as much whitespace as you like within a block; output is unaffected.
Delimit multiple statements in a single block with a semicolon

<div>
[%-
    "nothing";
    'doing';
-%]
</div>
<!-- Results in -->
<div>nothingdoing</div>

TT Syntax - Variables

Arrays, hashes, and objects simplify to dotted notation:

Perl source object

my $martini = {
    vermouth => 1,
    gin => 99,
    garnish => ["olive", "lemon peel"]
}

TT variable

<p>Give me an [% martini.garnish.0 %]!</p>
<!-- Results in -->
<p>Give me an olive!</p>

TT Syntax - Conditionals and Loops

(All structures end with an END block)

IF / UNLESS / ELSE / ELSIF
FOREACH, WHILE

TT variable

<ul>
[%- FOREACH ingredient IN martini %]
    [%- IF ingredient.key != 'garnish' %]
    <li>[% ingredient.key %] = [% ingredient.value %]</li>
    [%- END # if %]
[%- END # for loop %]
</ul>
<!-- Results in -->
<ul>
    <li>gin = 99</li>
    <li>vermouth = 1</li>
</ul>

Template Toolkit Syntax: I18N

Bad

<h1>Hello, [% world_string %]!</h1>

Good

<p>[% l('Hello, [_1]!', world_string) %]</p>

Template Toolkit Syntax: I18N / Plurals

Plural

[% l("I would like [quant,_1,apple,apples], please.", num_apples); %]

Paragraph

[% |l(num_apples) %]
I would like [quant,_1,apple,apples] and a bag of peaches, please.  Also,
four score and seven years ago (minus four score plus 1 year), Evergreen
went live in Georgia.  It is a period of civil war.  Rebel spaceships,
striking from a hidden base...
[% END %]

Context Data: OpenILS::WWW::EGCatLoader

Most of the data is pre-fetched by the page handlers within the EGCatLoader class and inserted into a global hash called "ctx".
3 generic classes of data retrieval functions are passed into the template environment. For each, replace HINT with the class hint of the desired object.
- ctx.get_HINT
  - inherited_vis = ctx.get_cgf("opac.org_unit.non_inheritied_visibility").enabled == "f";
- ctx.search_HINT
  - item_langs = ctx.search_ccvm("ctype", "item_lang");
- ctx.HINT_list
  - copy_status_list = ctx.ccs_list;
ctx.aou_tree provides the canonical org unit tree
ctx.aouct_tree provides the OPAC custom org unit tree (when present)
ctx.get_org_setting(org_id, setting_name)
- Returns the org unit setting value
ctx.parse_datetime(ISO_date)
- Returns a date compatible with the Template Toolkit DATE plugin.

Skinning and Localization with Apache Virtual Hosts

Template paths and translations are all specified within the Apache configuration.
Applying template overrides from additional directories and using alternate translations (for a given language) can be managed with Apache virtual hosts.

<VirtualHost *:80>
    ServerName libraryABC.example.org:80
    DocumentRoot /openils/var/web/
    DirectoryIndex index.xml index.html index.xhtml

    # - Load the default virtualhost configuration
    Include eg_vhost.conf

    # - Selectively override OPAC settings
    <Location /eg/opac>
        #PerlAddVar OILSWebTemplatePath "/openils/var/templates"
        PerlAddVar OILSWebTemplatePath "/openils/var/templates_SYSA"
        PerlAddVar OILSWebTemplatePath "/openils/var/templates_LIBABC"
        PerlAddVar OILSWebLocale "en"
        PerlAddVar OILSWebLocale "/openils/var/data/locale/SYSA/kpac.en.po"
    </Location>
</VirtualHost>

Overriding Templates

Overriding individual templates is 2-step process
Tell Apache where to look for template overrides in eg_vhost.conf

PerlAddVar OILSWebTemplatePath "/openils/var/templates"
PerlAddVar OILSWebTemplatePath "/openils/var/templates_myskin"

Copy and edit individual templates to override.

mkdir -p /openils/var/templates_myskin/opac/
cp /openils/var/templates/opac/home.tt2 /openils/var/templates_myskin/opac/
# edit /openils/var/templates_myskin/opac/home.tt2

Overriding Templates Example

images/tmpl_override_home_tmpl.png

images/tmpl_override_home_tpac.png

Common customizations - styles

TPAC CSS lives in /openils/var/web/css/skin/default/opac/style.css
- Could then create variants for each required skin and point to it from the template overrides
- Or create individual CSS files for each skin that override aspects of the core skin
Or you could template the CSS itself:
1. Hack EGWeb.pm to return content-type "text/css" for some file name(s) and move the CSS file into a TT-aware directory
2. Define colors in templated CSS based on CGI.virtual_host() value
3. Change templates/opac/parts/base.tt2 to point to the templated CSS
4. Stop maintaining many slight variations of the same CSS
To-do: Enhance the templated CSS to separate foreground from background colors

Debugging TPAC

Ensure the following is set in eg_vhost.conf. With this, error output will be sent to the Apache error log for all fatal TT errors.

PerlSetVar OILSWebDebugTemplate "true"

The Apache error log (e.g. /var/log/apache2/error.log) is the starting point for debugging practically all TPAC errors.
Template Error

[Mon Apr 23 14:26:22 2012] [warn] [client 71.70.141.149]
egweb: template error: file error - parse error -
opac/home.tt2 line 16: unexpected token (END)\n  [% END %]

Perl module error

[Mon Apr 09 10:36:21 2012] [warn] [client 50.79.238.214]
egweb: template error: undef error - Can't call
method "org_unit" on an undefined value at
/usr/local/share/perl/5.10.1/OpenILS/WWW/EGCatLoader/Util.pm line 166.\n

Experimenting With TPAC As a Platform

Building Something From "Nothing"

Let’s see what it takes to create a new interface.
For this example, we’re building a simple mobile catalog.
Code Name: Beanstalk.
Code Lives at git.evergreen-ils.org

Step 1: Beanstalk.pm

Start with just enough Perl code to implement the pages you want.

Subclass OpenILS::WWW::EGCatLoader
Create/attach handlers for each page

Step 2: Apache Configuration

Tell Apache about the new Perl module.

# eg_vhost.conf
<Location /eg/beanstalk>
    PerlSetVar OILSWebContextLoader "OpenILS::WWW::Beanstalk"
</Location>

Step 3: Templates

Copy templates from TPAC into OpenILS/src/templates/beanstalk and edit.

[%  PROCESS 'opac/parts/header.tt2';    # global imports, locale stuff, mkurl()
    WRAPPER 'beanstalk/base.tt2';       # slimmer base + mobile CSS
    PROCESS 'opac/parts/misc_util.tt2'; # MARC extraction
    PROCESS 'beanstalk/paginate.tt2';   # modified paginator
    ctx.page_title = l("Search Results: ") _ CGI.param('query') | html %]

<table class='results_table'>

    [%  FOR rec IN ctx.records;
            attrs = {marc_xml => rec.marc_xml};
            PROCESS get_marc_attrs args=attrs %]

    <tr class="result_table_row">
        <!-- Draw Record -->
        <!-- Aggressively introduce machete to TPAC template -->
    </tr>

    [% END %]

</table>

Home and Search Results

images/beanstalk_home.png

images/beanstalk_results.png

Record Detail

images/beanstalk_record.png

images/beanstalk_record2.png

images/beanstalk_copies.png

Lessons from the Beanstalk experiment

Relying on the EGCatLoader.pm for backend processing means you have very little Perl to write, so you can focus on HTML.
Create new templates from existing templates. Removing and altering existing code is much easier than creating new code.
Link to as many of the existing templates as you can, particularly those that do not create visible output.
Mobile CSS mostly boils down to something like this:

<meta name="viewport"
    content="format-detection=no,initial-scale=1.0,
    maximum-scale=1.0,user-scalable=0,width=device-width" />

Wither JSPAC / Whither TPAC

Per developer meeting on April 2, 2012:

Release / Date	JSPAC	TPAC
2.2 (April 2012)	Maintained	Identify and fill feature gaps
2.3 (October 2012)	Deprecated	Primary public interface
2.4 (April 2013)	Removed	Only public interface

TPAC Feature Gaps

Metarecord Searching
Search Ranges
Some added content work remains
Org unit hiding depth
Spell Check (needs improvement, less important w/ autosuggest)
Bookbag / BB Contents Paging

Template Toolkit OPAC Customization : Nuts and Bolts