From 1cdf1ed990117bc5ff6939d4cb4fbe831c210742 Mon Sep 17 00:00:00 2001 From: rsoulliere Date: Fri, 24 Feb 2012 13:59:58 -0500 Subject: [PATCH] Add template toolkit documentation from Dan Scott. Thanks Dan! --- admin/template_toolkit.txt | 294 +++++++++++++++++++++++++++++++++++++ root.txt | 5 + 2 files changed, 299 insertions(+) create mode 100644 admin/template_toolkit.txt diff --git a/admin/template_toolkit.txt b/admin/template_toolkit.txt new file mode 100644 index 0000000000..3c624ae168 --- /dev/null +++ b/admin/template_toolkit.txt @@ -0,0 +1,294 @@ +TPac Configuration and Customization +------------------------------------ + +Template toolkit documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For more general information about template toolkit see: http://template-toolkit.org/docs/index.html[official +documentation]. + +The purpose of this chapter is to focus on the +Evergreen-specific uses of Template Toolkit ('TT') in the OPAC. + +TPAC URL +~~~~~~~ + +The URL for the TPAC on a default Evergreen system is +http://localhost/eg/opac/home (adjust `localhost` to match your hostname or IP +address, naturally!) + +Perl modules used directly by TPAC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + * `Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader.pm` + * `Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Account.pm` + * `Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Container.pm` + * `Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Record.pm` + * `Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Search.pm` + * `Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Util.pm` + +Default templates +~~~~~~~~~~~~~~~~ + +The source template files are found in `Open-ILS/src/templates/opac`. + +These template files are installed in `/openils/var/templates/opac`. + +.NOTE +You should generally avoid touching the installed default template files, +unless you are contributing changes that you want Evergreen to adopt as a new +default. Even then, while you are developing your changes, consider using +template overrides rather than touching the installed templates until you are +ready to commit the changes to a branch. See below for information on template +overrides. + +Apache configuration files +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The base Evergreen configuration file on Debian-based systems can be found in +`/etc/apache2/sites-enabled/eg.conf`. This file defines the basic virtual host +configuration for Evergreen (hostnames and ports), then single-sources the +bulk of the configuration for each virtual host by including +`/etc/apache2/eg_vhost.conf`. + +TPAC CSS and media files +~~~~~~~~~~~~~~~~~~~~~~~ + +The CSS files used by the default TPAC templates are stored in the repo in +`Open-ILS/web/css/skin/default/opac/` and installed in +`/openils/var/web/css/skin/default/opac/`. + +The media files--mostly PNG images--used by the default TPAC templates are +stored in the repo in `Open-ILS/web/images/` and installed in +`/openils/var/web/images/`. + +Mapping templates to URLs +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The mapping for templates to URLs is straightforward. Following are a few +examples, where `` is a placeholder for one or more directories +that will be searched for a match: + + * `http://localhost/eg/opac/home` => `/openils/var//opac/home.tt2` + * `http://localhost/eg/opac/advanced` => `/openils/var//opac/advanced.tt2` + * `http://localhost/eg/opac/results` => `/openils/var//opac/results.tt2` + +The template files themselves can process, be wrapped by, or include other +template files. For example, the `home.tt2` template currently involves a +number of other template files to generate a single HTML file: + +.Example Template Toolkit file: opac/home.tt2 +[source, html] +------------------------------------------------------------------------------ +[% PROCESS "opac/parts/header.tt2"; + WRAPPER "opac/parts/base.tt2"; + INCLUDE "opac/parts/topnav.tt2"; + ctx.page_title = l("Home") %] +
+ [% INCLUDE "opac/parts/searchbar.tt2" %] +
+
+
+
+ [% INCLUDE "opac/parts/homesearch.tt2" %] +
+
+
+[% END %] +------------------------------------------------------------------------------ + +We will dissect this example in some more detail later, but the important +thing to note is that the file references are relative to the top of the +template directory. + +How to override templates +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Overrides for templates go in a directory that parallels the structure of the +default templates directory. The overrides then get pulled in via the Apache +configuration. + +In the following example, we demonstrate how to create a file that overrides +the default "Advanced search page" (`advanced.tt2`) by adding a new templates +directory and editing the new file in that directory. + +.Adding an override for the Advanced search page (example) +[source, bash] +------------------------------------------------------------------------------ +bash$ mkdir -p /openils/var/templates_custom/opac +bash$ cp /openils/var/templates/opac/advanced.tt2 \ + /openils/var/templates_custom/opac/. +bash$ vim /openils/var/templates_custom/opac/advanced.tt2 +------------------------------------------------------------------------------ + +We now need to teach Apache about the new templates directory. Open `eg.conf` +and add the following `` element to each of the `` +elements in which you want to include the overrides. The default Evergreen +configuration includes a `VirtualHost` directive for port 80 (HTTP) and another +one for port 443 (HTTPS); you probably want to edit both, unless you want the +HTTP user experience to be different from the HTTPS user experience. + +.Configuring the custom templates directory in Apache's eg.conf +[source,xml] +------------------------------------------------------------------------------ + + # + + # - absorb the shared virtual host settings + Include eg_vhost.conf + + PerlAddVar OILSWebTemplatePath "/openils/var/templates_algoma" + + + # + +------------------------------------------------------------------------------ + +Finally, reload the Apache configuration to pick up the changes: + +.Reloading the Apache configuration +[source,bash] +------------------------------------------------------------------------------ +bash# /etc/init.d/apache2 reload +------------------------------------------------------------------------------ + +You should now be able to see your change at http://localhost/eg/opac/advanced + +Defining multiple layers of overrides +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can define multiple layers of overrides, so if you want every library in +your consortium to have the same basic customizations, and then apply +library-specific customizations, you can define two template directories for +each library. + +In the following example, we define the `template_CONS` directory as the set of +customizations to apply to all libraries, and `template_BR#` as the set of +customizations to apply to library BR1 and BR2. + +As the consortial customizations apply to all libraries, we can add the +extra template directory directly to `eg_vhost.conf`: + +.Apache configuration for all libraries (eg_vhost.conf) +[source,xml] +------------------------------------------------------------------------------ +# Templates will be loaded from the following paths in reverse order. +PerlAddVar OILSWebTemplatePath "/openils/var/templates" +PerlAddVar OILSWebTemplatePath "/openils/var/templates_CONS" +------------------------------------------------------------------------------ + +Then we define a virtual host for each library to add the second layer of +customized templates on a per-library basis. Note that for the sake of brevity +we only show the configuration for port 80. + +.Apache configuration for each virtual host (eg.conf) +[source,xml] +------------------------------------------------------------------------------ + + ServerName br1.concat.ca + DocumentRoot /openils/var/web/ + DirectoryIndex index.xml index.html index.xhtml + Include eg_vhost.conf + + PerlAddVar OILSWebTemplatePath "/openils/var/templates_BR1" + + + + + ServerName br2.concat.ca + DocumentRoot /openils/var/web/ + DirectoryIndex index.xml index.html index.xhtml + Include eg_vhost.conf + + PerlAddVar OILSWebTemplatePath "/openils/var/templates_BR2" + + +------------------------------------------------------------------------------ + +Changing some text in the TPAC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Out of the box, the TPAC includes a number of placeholder text and links. For +example, there is a set of links cleverly named 'Link 1', 'Link 2', and so on +in the header and footer of every page in the TPAC. Let's customize that for +our `templates_BR1` skin. + +To begin with, we need to find the page(s) that contain the text in question. +The simplest way to do that is with the handly utility `ack`, which is much +like `grep` but with built-in recursion and other tricks. On Debian-based +systems, the command is `ack-grep` as `ack` conflicts with an existing utility. +In the following example, we search for files that contain the text "Link 1": + +.Searching for text matching "Link 1" +[source,bash] +------------------------------------------------------------------------------ +bash$ ack-grep "Link 1" /openils/var/templates/opac +/openils/var/templates/opac/parts/topnav_links.tt2 +4: [% l('Link 1') %] +------------------------------------------------------------------------------ + +Next, we copy the file into our overrides directory and edit it with `vim`: + +.Copying the links file into the overrides directory +[source,bash] +------------------------------------------------------------------------------ +bash$ cp /openils/var/templates/opac/parts/topnav_links.tt2 \ + /openils/var/templates_BR1/opac/parts/topnav_links.tt2 +bash$ vim /openils/var/templates_BR1/opac/parts/topnav_links.tt2 +------------------------------------------------------------------------------ + +Finally, we edit the link text in `opac/parts/header.tt2`. + +.Content of the opac/parts/header.tt2 file +[source,html] +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ + +For the most part, the page looks like regular HTML, but note the `[%_("` +`")%]` that surrounds the text of each link. The `[% ... %]` signifies a TT +block, which can contain one or more TT processing instructions. `l(" ... ");` +is a function that marks text for localization (translation); a separate +process can subsequently extract localized text as GNU gettext-formatted PO +files. + +.NOTE +As Evergreen supports multiple languages, any customizations to Evergreen's +default text must use the localization function. Also, note that the +localization function supports placeholders such as `[_1]`, `[_2]` in the text; +these are replaced by the contents of variables passed as extra arguments to +the `l()` function. + +Once we have edited the link and link text to our satisfaction, we can load +the page in our Web browser and see the live changes immediately (assuming +we are looking at the BR1 overrides, of course). + +Troubleshooting +~~~~~~~~~~~~~~~ + +If there is a problem such as a TT syntax error, it generally shows up as a +an ugly server failure page. If you check the Apache error logs, you will +probably find some solid clues about the reason for the failure. For example, +in the following example the error message identifies the file in which the +problem occurred as well as the relevant line numbers: + +.Example error message in Apache error logs +[source,bash] +------------------------------------------------------------------------------ +bash# grep "template error" /var/log/apache2/error_log +[Tue Dec 06 02:12:09 2011] [warn] [client 127.0.0.1] egweb: template error: + file error - parse error - opac/parts/record/summary.tt2 line 112-121: + unexpected token (!=)\n [% last_cn = 0;\n FOR copy_info IN + ctx.copies;\n callnum = copy_info.call_number_label;\n +------------------------------------------------------------------------------ + diff --git a/root.txt b/root.txt index 136768b06b..3a7833b7ee 100644 --- a/root.txt +++ b/root.txt @@ -68,6 +68,11 @@ The Evergreen system allows a free range of customizations to every aspect of th // include::global_system_configuration.txt[] // include::opac_customization.txt[] + + +include::admin/template_toolkit.txt[] + + //include::staff_client_customization.txt[] // include::backing_up.txt[] -- 2.43.2