1 TPac Configuration and Customization
2 ------------------------------------
4 Template toolkit documentation
5 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 For more general information about template toolkit see: http://template-toolkit.org/docs/index.html[official
10 The purpose of this chapter is to focus on the
11 Evergreen-specific uses of Template Toolkit ('TT') in the OPAC.
16 The URL for the TPAC on a default Evergreen system is
17 http://localhost/eg/opac/home (adjust `localhost` to match your hostname or IP
20 Perl modules used directly by TPAC
21 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
23 * `Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader.pm`
24 * `Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Account.pm`
25 * `Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Container.pm`
26 * `Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Record.pm`
27 * `Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Search.pm`
28 * `Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Util.pm`
33 The source template files are found in `Open-ILS/src/templates/opac`.
35 These template files are installed in `/openils/var/templates/opac`.
38 You should generally avoid touching the installed default template files,
39 unless you are contributing changes that you want Evergreen to adopt as a new
40 default. Even then, while you are developing your changes, consider using
41 template overrides rather than touching the installed templates until you are
42 ready to commit the changes to a branch. See below for information on template
45 Apache configuration files
46 ~~~~~~~~~~~~~~~~~~~~~~~~~~
48 The base Evergreen configuration file on Debian-based systems can be found in
49 `/etc/apache2/sites-enabled/eg.conf`. This file defines the basic virtual host
50 configuration for Evergreen (hostnames and ports), then single-sources the
51 bulk of the configuration for each virtual host by including
52 `/etc/apache2/eg_vhost.conf`.
54 TPAC CSS and media files
55 ~~~~~~~~~~~~~~~~~~~~~~~~
57 The CSS files used by the default TPAC templates are stored in the repo in
58 `Open-ILS/web/css/skin/default/opac/` and installed in
59 `/openils/var/web/css/skin/default/opac/`.
61 The media files--mostly PNG images--used by the default TPAC templates are
62 stored in the repo in `Open-ILS/web/images/` and installed in
63 `/openils/var/web/images/`.
65 Mapping templates to URLs
66 ~~~~~~~~~~~~~~~~~~~~~~~~~
68 The mapping for templates to URLs is straightforward. Following are a few
69 examples, where `<templates>` is a placeholder for one or more directories
70 that will be searched for a match:
72 * `http://localhost/eg/opac/home` => `/openils/var/<templates>/opac/home.tt2`
73 * `http://localhost/eg/opac/advanced` => `/openils/var/<templates>/opac/advanced.tt2`
74 * `http://localhost/eg/opac/results` => `/openils/var/<templates>/opac/results.tt2`
76 The template files themselves can process, be wrapped by, or include other
77 template files. For example, the `home.tt2` template currently involves a
78 number of other template files to generate a single HTML file:
80 .Example Template Toolkit file: opac/home.tt2
82 ------------------------------------------------------------------------------
83 [% PROCESS "opac/parts/header.tt2";
84 WRAPPER "opac/parts/base.tt2";
85 INCLUDE "opac/parts/topnav.tt2";
86 ctx.page_title = l("Home") %]
87 <div id="search-wrapper">
88 [% INCLUDE "opac/parts/searchbar.tt2" %]
90 <div id="content-wrapper">
91 <div id="main-content-home">
92 <div class="common-full-pad"></div>
93 [% INCLUDE "opac/parts/homesearch.tt2" %]
94 <div class="common-full-pad"></div>
98 ------------------------------------------------------------------------------
100 We will dissect this example in some more detail later, but the important
101 thing to note is that the file references are relative to the top of the
104 How to override templates
105 ~~~~~~~~~~~~~~~~~~~~~~~~~
107 Overrides for templates go in a directory that parallels the structure of the
108 default templates directory. The overrides then get pulled in via the Apache
111 In the following example, we demonstrate how to create a file that overrides
112 the default "Advanced search page" (`advanced.tt2`) by adding a new templates
113 directory and editing the new file in that directory.
115 .Adding an override for the Advanced search page (example)
117 ------------------------------------------------------------------------------
118 bash$ mkdir -p /openils/var/templates_custom/opac
119 bash$ cp /openils/var/templates/opac/advanced.tt2 \
120 /openils/var/templates_custom/opac/.
121 bash$ vim /openils/var/templates_custom/opac/advanced.tt2
122 ------------------------------------------------------------------------------
124 We now need to teach Apache about the new templates directory. Open `eg.conf`
125 and add the following `<Location /eg>` element to each of the `<VirtualHost>`
126 elements in which you want to include the overrides. The default Evergreen
127 configuration includes a `VirtualHost` directive for port 80 (HTTP) and another
128 one for port 443 (HTTPS); you probably want to edit both, unless you want the
129 HTTP user experience to be different from the HTTPS user experience.
131 .Configuring the custom templates directory in Apache's eg.conf
133 ------------------------------------------------------------------------------
137 # - absorb the shared virtual host settings
138 Include eg_vhost.conf
140 PerlAddVar OILSWebTemplatePath "/openils/var/templates_algoma"
145 ------------------------------------------------------------------------------
147 Finally, reload the Apache configuration to pick up the changes:
149 .Reloading the Apache configuration
151 ------------------------------------------------------------------------------
152 bash# /etc/init.d/apache2 reload
153 ------------------------------------------------------------------------------
155 You should now be able to see your change at http://localhost/eg/opac/advanced
157 Defining multiple layers of overrides
158 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
160 You can define multiple layers of overrides, so if you want every library in
161 your consortium to have the same basic customizations, and then apply
162 library-specific customizations, you can define two template directories for
165 In the following example, we define the `template_CONS` directory as the set of
166 customizations to apply to all libraries, and `template_BR#` as the set of
167 customizations to apply to library BR1 and BR2.
169 As the consortial customizations apply to all libraries, we can add the
170 extra template directory directly to `eg_vhost.conf`:
172 .Apache configuration for all libraries (eg_vhost.conf)
174 ------------------------------------------------------------------------------
175 # Templates will be loaded from the following paths in reverse order.
176 PerlAddVar OILSWebTemplatePath "/openils/var/templates"
177 PerlAddVar OILSWebTemplatePath "/openils/var/templates_CONS"
178 ------------------------------------------------------------------------------
180 Then we define a virtual host for each library to add the second layer of
181 customized templates on a per-library basis. Note that for the sake of brevity
182 we only show the configuration for port 80.
184 .Apache configuration for each virtual host (eg.conf)
186 ------------------------------------------------------------------------------
188 ServerName br1.concat.ca
189 DocumentRoot /openils/var/web/
190 DirectoryIndex index.xml index.html index.xhtml
191 Include eg_vhost.conf
193 PerlAddVar OILSWebTemplatePath "/openils/var/templates_BR1"
198 ServerName br2.concat.ca
199 DocumentRoot /openils/var/web/
200 DirectoryIndex index.xml index.html index.xhtml
201 Include eg_vhost.conf
203 PerlAddVar OILSWebTemplatePath "/openils/var/templates_BR2"
206 ------------------------------------------------------------------------------
208 Changing some text in the TPAC
209 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
211 Out of the box, the TPAC includes a number of placeholder text and links. For
212 example, there is a set of links cleverly named 'Link 1', 'Link 2', and so on
213 in the header and footer of every page in the TPAC. Let's customize that for
214 our `templates_BR1` skin.
216 To begin with, we need to find the page(s) that contain the text in question.
217 The simplest way to do that is with the handy utility `ack`, which is much
218 like `grep` but with built-in recursion and other tricks. On Debian-based
219 systems, the command is `ack-grep` as `ack` conflicts with an existing utility.
220 In the following example, we search for files that contain the text "Link 1":
222 .Searching for text matching "Link 1"
224 ------------------------------------------------------------------------------
225 bash$ ack-grep "Link 1" /openils/var/templates/opac
226 /openils/var/templates/opac/parts/topnav_links.tt2
227 4: <a href="http://example.com">[% l('Link 1') %]</a>
228 ------------------------------------------------------------------------------
230 Next, we copy the file into our overrides directory and edit it with `vim`:
232 .Copying the links file into the overrides directory
234 ------------------------------------------------------------------------------
235 bash$ cp /openils/var/templates/opac/parts/topnav_links.tt2 \
236 /openils/var/templates_BR1/opac/parts/topnav_links.tt2
237 bash$ vim /openils/var/templates_BR1/opac/parts/topnav_links.tt2
238 ------------------------------------------------------------------------------
240 Finally, we edit the link text in `opac/parts/header.tt2`.
242 .Content of the opac/parts/header.tt2 file
244 ------------------------------------------------------------------------------
245 <div id="gold-links-holder">
246 <div id="gold-links">
247 <div id="header-links">
248 <a href="http://example.com">[% l('Link 1') %]</a>
249 <a href="http://example.com">[% l('Link 2') %]</a>
250 <a href="http://example.com">[% l('Link 3') %]</a>
251 <a href="http://example.com">[% l('Link 4') %]</a>
252 <a href="http://example.com">[% l('Link 5') %]</a>
256 ------------------------------------------------------------------------------
258 For the most part, the page looks like regular HTML, but note the `[%_("`
259 `")%]` that surrounds the text of each link. The `[% ... %]` signifies a TT
260 block, which can contain one or more TT processing instructions. `l(" ... ");`
261 is a function that marks text for localization (translation); a separate
262 process can subsequently extract localized text as GNU gettext-formatted PO
266 As Evergreen supports multiple languages, any customizations to Evergreen's
267 default text must use the localization function. Also, note that the
268 localization function supports placeholders such as `[_1]`, `[_2]` in the text;
269 these are replaced by the contents of variables passed as extra arguments to
272 Once we have edited the link and link text to our satisfaction, we can load
273 the page in our Web browser and see the live changes immediately (assuming
274 we are looking at the BR1 overrides, of course).
279 If there is a problem such as a TT syntax error, it generally shows up as a
280 an ugly server failure page. If you check the Apache error logs, you will
281 probably find some solid clues about the reason for the failure. For example,
282 in the following example the error message identifies the file in which the
283 problem occurred as well as the relevant line numbers:
285 .Example error message in Apache error logs
287 ------------------------------------------------------------------------------
288 bash# grep "template error" /var/log/apache2/error_log
289 [Tue Dec 06 02:12:09 2011] [warn] [client 127.0.0.1] egweb: template error:
290 file error - parse error - opac/parts/record/summary.tt2 line 112-121:
291 unexpected token (!=)\n [% last_cn = 0;\n FOR copy_info IN
292 ctx.copies;\n callnum = copy_info.call_number_label;\n
293 ------------------------------------------------------------------------------