| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| dev:opac:template-toolkit [2011/08/03 12:08] – update templates path for oils_web.xml erickson | dev:opac:template-toolkit [2022/02/10 13:34] (current) – external edit 127.0.0.1 |
|---|
| * Create Date: 2011-03-08 | * Create Date: 2011-03-08 |
| |
| * [[dev:opac:template-toolkit:todos|Development todos]] | * <del>[[dev:opac:template-toolkit:todos|Development todos]]</del> deprecated |
| | * [[dev:opac:template-toolkit:plan|Development plan]] |
| |
| ===== The Code ===== | ===== The Code ===== |
| |
| The code currently lives in an ESI Git branch called "template-toolkit-opac". You can view the code and watch changes [[http://git.evergreen-ils.org/?p=evergreen/equinox.git;a=shortlog;h=refs/heads/template-toolkit-opac|here]]. | On 2011-09-11, the code was merged to the master branch of the Evergreen git repository at http://git.evergreen-ils.org. |
| | |
| Downloading the code by creating a git clone of the branch | |
| | |
| <code> | |
| $ git clone git://git.evergreen-ils.org/evergreen/equinox.git | |
| $ cd equinox | |
| $ git checkout -tb template-toolkit-opac origin/template-toolkit-opac | |
| </code> | |
| | |
| The code changes frequently. You can update the code by pulling changes from the repository. | |
| <code> | |
| $ git checkout template-toolkit-opac # just in case | |
| $ git pull | |
| </code> | |
| ===== Installation ===== | ===== Installation ===== |
| |
| * Locale::Maketext::Lexicon | * Locale::Maketext::Lexicon |
| |
| ==== Installing Over an existing Evergreen installation (2.1+) ==== | ==== Installing over an existing Evergreen installation ==== |
| |
| - Copy these files from the repository into place on the file system. Your mileage may vary on OS-dependent paths. **Note:** Be careful not to clobber local changes you didn't want clobbered. | The TPAC needs to be installed as part of an overall system upgrade to master; it will be an integrated part of the Evergreen 2.2 release. |
| *<code> | |
| $ sudo cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/ | Pay close attention to the following files on upgrade: |
| $ sudo -u opensrf cp Open-ILS/examples/oils_web.xml.example /openils/conf/oils_web.xml | * ''Open-ILS/examples/apache/eg_vhost.conf'' |
| $ sudo cp -r Open-ILS/src/perlmods/lib/OpenILS/WWW/* /usr/local/share/perl/5.10.1/OpenILS/WWW/ | * Perl modules, including the previously mentioned prerequisites |
| $ sudo -u opensrf cp -r Open-ILS/src/templates* /openils/var/</code> | * ''Open-ILS/src/templates/*'', which now gets installed into ''/openils/var/templates/'' |
| - Reload or restart Apache. | * ''Open-ILS/web/*'', which includes stylesheets under ''Open-ILS/web/css'' and images under ''Open-ILS/web/images'' that are required by the TPAC. |
| - Navigate to http://SERVER/eg/opac/home and you should see the KCLS-skinned server-side OPAC. | |
| | Navigate to http://SERVER/eg/opac/home and you should see the default server-side TPAC skin |
| |
| ==== Staff Client Integration ==== | ==== Staff Client Integration ==== |
| |
| * The eventual goal is to fully integrate the TT OPAC into the staff client. Until it's complete, it's necessary to manually configure the staff client to use the new OPAC. | * The eventual goal is to fully integrate the TT OPAC into the staff client. Until it's complete, it's necessary to manually configure the staff client to use the new OPAC. |
| * To use the Template Toolkit OPAC as the catalog in the staff client, as opensrf:<code> | * To use the Template Toolkit OPAC as the catalog in the staff client, click the **Toggle Template Toolkit OPAC** link on the staff client landing page. You might need to restart the staff client to make the change take effect. |
| echo "urls['opac'] = '/eg/opac/advanced'; | |
| urls['opac_rdetail'] = '/eg/opac/record/'; | |
| urls['opac_rresult'] = '/eg/opac/results'; | |
| urls['opac_rresult_metarecord'] = '/eg/opac/results?metarecord='; | |
| urls['browser'] = urls.opac;" > /openils/var/web/xul/server/skin/custom.js;</code> | |
| |
| ==== Customizing ==== | ==== Customizing ==== |
| Skinning the TT OPAC is much easier than skinning previous incarnations of the Evergreen OPAC. | Skinning the TT OPAC is much easier than skinning previous incarnations of the Evergreen OPAC. |
| |
| * Create a directory where you will store your template customizations, let's say ''/openils/var/web/my_own_templates''. | * Create a directory where you will store your template customizations, let's say ''/openils/var/my_own_templates''. |
| | * Edit your Apache configuration to include the overriding template directory _after_ the main template directory:<code> |
| | # Templates will be loaded from the following paths in reverse order. |
| | PerlAddVar OILSWebTemplatePath "/openils/var/templates" |
| | PerlAddVar OILSWebTemplatePath "/openils/var/my_own_templates" |
| | </code> |
| | * You can, for example, customize skins on the basis of the hostname being used via virtual hosts; note that the base template directory gets loaded first in eg_vhost.conf, so you're just specifying the customizations here:<code> |
| | <VirtualHost *:80> |
| | ServerName myhostname |
| | DocumentRoot /openils/var/web/ |
| | DirectoryIndex index.xml index.html index.xhtml |
| | Include eg_vhost.conf |
| | <Location /eg> |
| | PerlAddVar OILSWebTemplatePath "/openils/var/my_own_templates" |
| | </Location> |
| | </VirtualHost> |
| | </code> |
| | * Place your version of all ''.tt2'' files that you would edit into a directory structure that mirrors that of the stock template path. That is, if you want to have your own version of ''/openils/var/templates/default/opac/parts/topnav.tt2'', put it at ''/openils/var/**my_own_templates**/default/opac/parts/topnav.tt2''. |
| |
| * Look for the node ''<template_paths>'' in your ''/openils/conf/oils_web.xml'' file. | * Do **not** copy every file under ''/openils/var/templates'' into ''my_own_templates'' -- that is not necessary. |
| |
| * Add a new ''<path>'' child node directly //above// all existing ones so that everything within ''<template_paths>'' now looks something like this: | * Reload Apache. |
| |
| <code> | === String Localization === |
| <template_paths> | |
| <path>/openils/var/my_own_templates</path> | * Create a ''.po'' file for your locale. Requires the ''Locale::Maketext::Extract::Plugin::TT2'' Perl module:<code> |
| <path>/openils/var/templates</path> | sudo -u opensrf xgettext.pl --plugin=tt2 --directory=Open-ILS/src/templates/opac/ --output-dir=/openils/var/templates/locale --output=tpac.fr_CA.po</code> |
| </template_paths> | * Add your .po file to the Apache ''eg_vhost.conf'' file in the ''<Location /eg>'' section:<code> |
| | PerlAddVar OILSWebLocale "en_ca" |
| | PerlAddVar OILSWebLocale "/openils/var/templates/locale/tpac.en_CA.po" |
| | PerlAddVar OILSWebLocale "fr_ca" |
| | PerlAddVar OILSWebLocale "/openils/var/templates/locale/tpac.fr_CA.po" |
| </code> | </code> |
| | * Edit strings in your new .po file. For example:<code> |
| * Place your version of all ''.tt2'' files that you would edit into a directory structure that mirrors that of the stock template path. That is, if you want to have your own version of ''/openils/var/web/templates/default/opac/parts/topnav.tt2'', put it at ''/openils/var/web/**my_own_templates**/default/opac/parts/topnav.tt2''. | ... |
| | #: Open-ILS/src/templates/opac/parts/topnav.tt2:34 |
| * Do **not** copy every file under ''/openils/var/web/templates'' into ''my_own_templates'' -- that is not necessary. | msgid "My Account" |
| | msgstr "Mon compte" |
| * Reload Apache. | ...</code> |
| | * Reload Apache. (Translations are cached in the browser) |
| | * To test, reload the page with fr-CA as the browser's default locale |
| |
| === Custom Perl Handler === | === Custom Perl Handler === |
| </Location></code> | </Location></code> |
| * Reload Apache | * Reload Apache |
| | |
| | ===== Development conventions ===== |
| | * Use the localization macro (''l()'') to mark text that needs to be translated:<code html> |
| | <h1>[% l('Search results') %]</h1> |
| | </code> The localization macro accepts parameters so that you can create complex strings that represent a complete sentence or translatable phrase. In the following example, variable ''[_1]'' is replaced by the value of the first argument, //user_name//, and ''[_2]'' is replaced by the value of the second argument, //library_name//:<code html> |
| | [% l('Hello [_1]! You are browsing the [_2] catalog', user_name, library_name) %] |
| | </code> |
| | * Escape output to prevent XSS vulnerabilities and broken HTML.Use the ''html'' filter to escape text generated from outside of the template in HTML, and the ''uri'' filter to escape URIs. For example, in the following example the text in the first table cell is not escaped because it is static text from the template itself, while the **attrs.author** text comes from the database and therefore should be escaped:<code html> |
| | <td>[% l("Author:") %]'</td><td>[% attrs.author | html %]</td> |
| | </code> Note that the ''uri'' filter is not necessary in cases where the URI has passed through the CGI plugin, such as in the ''mkurl()'' macro. |
| |
