Typos: s/recieve/receive/
[working/Evergreen.git] / 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