admin/template_toolkit.txt

   1 TPac Configuration and Customization
   2 ------------------------------------
   3
   4 Template toolkit documentation
   5 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   6
   7 For more general information about template toolkit see:  http://template-toolkit.org/docs/index.html[official
   8 documentation].
   9
  10 The purpose of this chapter is to focus on the
  11 Evergreen-specific uses of Template Toolkit ('TT') in the OPAC.
  12
  13 TPAC URL
  14 ~~~~~~~
  15
  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
  18 address, naturally!)
  19
  20 Perl modules used directly by TPAC
  21 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  22
  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`
  29
  30 Default templates
  31 ~~~~~~~~~~~~~~~~
  32
  33 The source template files are found in `Open-ILS/src/templates/opac`.
  34
  35 These template files are installed in `/openils/var/templates/opac`.
  36
  37 .NOTE
  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
  43 overrides.
  44
  45 Apache configuration files
  46 ~~~~~~~~~~~~~~~~~~~~~~~~~
  47
  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`.
  53
  54 TPAC CSS and media files
  55 ~~~~~~~~~~~~~~~~~~~~~~~
  56
  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/`.
  60
  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/`.
  64
  65 Mapping templates to URLs
  66 ~~~~~~~~~~~~~~~~~~~~~~~~~
  67
  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:
  71
  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`
  75
  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:
  79
  80 .Example Template Toolkit file: opac/home.tt2
  81 [source, html]
  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" %]
  89     </div>
  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>
  95         </div>
  96     </div>
  97 [% END %]
  98 ------------------------------------------------------------------------------
  99
 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
 102 template directory.
 103
 104 How to override templates
 105 ~~~~~~~~~~~~~~~~~~~~~~~~~
 106
 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
 109 configuration.
 110
 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.
 114
 115 .Adding an override for the Advanced search page (example)
 116 [source, bash]
 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 ------------------------------------------------------------------------------
 123
 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.
 130
 131 .Configuring the custom templates directory in Apache's eg.conf
 132 [source,xml]
 133 ------------------------------------------------------------------------------
 134 <VirtualHost *:80>
 135     # <snip>
 136
 137     # - absorb the shared virtual host settings
 138     Include eg_vhost.conf
 139     <Location /eg>
 140         PerlAddVar OILSWebTemplatePath "/openils/var/templates_algoma"
 141     </Location>
 142
 143     # <snip>
 144 </VirtualHost>
 145 ------------------------------------------------------------------------------
 146
 147 Finally, reload the Apache configuration to pick up the changes:
 148
 149 .Reloading the Apache configuration
 150 [source,bash]
 151 ------------------------------------------------------------------------------
 152 bash# /etc/init.d/apache2 reload
 153 ------------------------------------------------------------------------------
 154
 155 You should now be able to see your change at http://localhost/eg/opac/advanced
 156
 157 Defining multiple layers of overrides
 158 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 159
 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
 163 each library.
 164
 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.
 168
 169 As the consortial customizations apply to all libraries, we can add the
 170 extra template directory directly to `eg_vhost.conf`:
 171
 172 .Apache configuration for all libraries (eg_vhost.conf)
 173 [source,xml]
 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 ------------------------------------------------------------------------------
 179
 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.
 183
 184 .Apache configuration for each virtual host (eg.conf)
 185 [source,xml]
 186 ------------------------------------------------------------------------------
 187 <VirtualHost *:80>
 188     ServerName br1.concat.ca
 189     DocumentRoot /openils/var/web/
 190     DirectoryIndex index.xml index.html index.xhtml
 191     Include eg_vhost.conf
 192     <Location /eg>
 193         PerlAddVar OILSWebTemplatePath "/openils/var/templates_BR1"
 194     </Location>
 195 </VirtualHost>
 196
 197 <VirtualHost *:80>
 198     ServerName br2.concat.ca
 199     DocumentRoot /openils/var/web/
 200     DirectoryIndex index.xml index.html index.xhtml
 201     Include eg_vhost.conf
 202     <Location /eg>
 203         PerlAddVar OILSWebTemplatePath "/openils/var/templates_BR2"
 204     </Location>
 205 </VirtualHost>
 206 ------------------------------------------------------------------------------
 207
 208 Changing some text in the TPAC
 209 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 210
 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.
 215
 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 handly 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":
 221
 222 .Searching for text matching "Link 1"
 223 [source,bash]
 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 ------------------------------------------------------------------------------
 229
 230 Next, we copy the file into our overrides directory and edit it with `vim`:
 231
 232 .Copying the links file into the overrides directory
 233 [source,bash]
 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 ------------------------------------------------------------------------------
 239
 240 Finally, we edit the link text in `opac/parts/header.tt2`.
 241
 242 .Content of the opac/parts/header.tt2 file
 243 [source,html]
 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>
 253         </div>
 254     </div>
 255 </div>
 256 ------------------------------------------------------------------------------
 257
 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
 263 files.
 264
 265 .NOTE
 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
 270 the `l()` function.
 271
 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).
 275
 276 Troubleshooting
 277 ~~~~~~~~~~~~~~~
 278
 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:
 284
 285 .Example error message in Apache error logs
 286 [source,bash]
 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 ------------------------------------------------------------------------------
 294