ОПИСАНИЕ
Этот пособие представляет собой введние в Template Toolkit и показывает несколько типичных способов использования этой библиотеки для генерации контента сайта. Пособие описывает генерацию статических страниц с использованием утилит tpage и ttree и динамических страниц с использованием CGI скриптов и обработчиков Apache/mod_perl.
Знакомство, краткое описание и объяснение с использованием примеров различных возможностей Template Toolkit. Дополнительная информация приведена в pod-документации Template, Template::Manual и в подразделах, например
perldoc Template # использование модуля Template.pm
perldoc Template::Manual # содержание документации
perldoc Template::Manual::Config # опции конфигурации
Документация также поставляется в HTML формате (или точнее, в форме HTML шаблонов). Смотрите каталог 'docs' пакета для получения дополнительной информации о построении HTML документации.
Если же вы читаете это руководство как часть HTML документации, значит вам не нужно беспокоится об этом. Вы можете присесть, расслабиться и наслаждаться чтением остальной части пособия...
ВВЕДЕНИЕ
Template Toolkit - это набор модулей Perl, который в совокупности реализуют систему по обработке шаблонов. В данном контексте шаблон - это текстовый документ, содержащий специальные разметочные теги, называемые 'директивами'. Директива это инструкция процессору шаблонов выполнить некоторое действие и заменить директиву в документе на результат этого действия. Директивы используются для определения или вывода значения переменной, выполнения циклических операций с массивами (FOREACH), выполнения условных операций (IF/UNLESS/ELSE), включения и выполнения других шаблонов (INCLUDE) и т.д.
Во всем остальном, документ это обычный текстовый файл и может иметь любое содержимое (например HTML, XML, RTF, LaTeX, и т.п.). Директивы включаются в документ внутри специальных разметочных тегов. По умолчанию, в качестве таких тегов используются [% и %], но они могут быть заменены на другие через опции конфигурации модуля. Пример HTML документа с дополнительными директивами Template Toolkit.
[% INCLUDE header
title = 'This is an HTML example'
%]
<h1>Some Interesting Links</h1>
[% webpages = [
{ url => 'http://foo.org', title => 'The Foo Organisation' }
{ url => 'http://bar.org', title => 'The Bar Organisation' }
]
%]
Links:
<ul>
[% FOREACH link = webpages %]
<li><a href="[% link.url %]">[% link.title %]</a>
[% END %]
</ul>
[% INCLUDE footer %]
Этот пример показывает как директива INCLUDE используется для загрузки, обработки и включения в текущий документ отдельных шаблонов 'header' и 'footer'. Эти файлы могут выглядеть например так:
header:
<html>
<head>
<title>[% title %]</title>
</head>
<body bgcolor="#ffffff">
footer:
<hr>
<center>
© Copyright 2000 Me, Myself, I
</center>
</body>
</html>
Также в примере показано использование директивы FOREACH для построения таблицы ссылок с помощью цикла по массиву 'webpages'. Мы определяем внутри шаблона массив, содержащий несколько ссылок на хэши, состоящих из двух элементов 'url' и 'title'. Директива FOREACH проходит по массиву, используя 'link' в качестве указателя на каждый элемент массива (ссылка на хэш). Затем директивы [% link.url %] и [% link.title %] получают соответсвующие значения хэша и вставляют их в документ.
В следующих разделах показаны другие способы определения данных, которые используются в шаблонах.
ГЕНЕРАЦИЯ СТАТИЧЕСКИХ СТРАНИЦ
Создав шаблон, мы теперь можем обработать его и получить некоторый вывод. Наиболее быстрый и простой способ для этого использование утилиты tpage. Она поставляется как часть библиотеки Template Toolkit и должна быть установлена в каталог с исполняемыми файлами perl.
Если вы сохранили свой шаблон как файл 'mypage.html', вам нужно выполнить команду:
tpage mypage.html
Эта команда запустит обработку шаблона, а вывод будет отправлен на STDOUT (т.е. пролетит по вашему экрану). Вы может перенаправить вывод в файл, но будьте осторожны, не указывайте то же имя файла, что и имя шаблона, иначе вы перезапишите его. Вы можете использовать для шаблонов и обычных файлов различные расширения. Например, для шаблонов используйте расширение '.atml' (видимо 'Another Template Markup Language'?) и привычное '.html' для выходных файлов (преполагается, что вы создаете HTML). Или, вы можете перенаправить вывод в другой каталог, например
tpage mypage.atml > mypage.html
tpage templates/mypage.html > html/mypage.html
Утилита tpage довольно проста и предназначена для того, чтобы дать возможность просто обработать шаблон без необходимости писать perl-код. Более гибкая утилита ttree описанна ниже, но сейчас нам достаточно вывода сгенерированного командой из примера выше (для краткости пустые строки удалены):
<html>
<head>
<title>This is an HTML example</title>
</head>
<body bgcolor="#ffffff">
<h1>Some Interesting Links</h1>
Links:
<ul>
<li><a href="http://foo.org">The Foo Organisation</a>
<li><a href="http://bar.org">The Bar Organisation</a>
</ul>
<hr>
<center>
© Copyright 2000 Me, Myself, I
</center>
</body>
</html>
Шаблоны header и footer включены (предполагается, что вы их создали и они находятся в текущем каталоге) и данные о ссылках преобразованы в список в HTML-файле.
Утилита ttree, также поставляемая в составе библиотеки Template Toolkit, предоставляет более гибкий способ обработки шаблонов. При первом запуске утилиты, вам будет предложено создать конфигурационный файл, в большинстве случаев называемый '.ttreerc' в вашем домашнем каталоге. Ответьте 'y', чтобы создать файл.
Документация по ttree описывает, как вы можете изменить расположение это файла, а также описывает синтаксис и назначение различных опций в этом файле. Конфигурационный файл, приведенный в качестве примера, содержит комментарии, которые также могут помочь.
perldoc ttree
ttree -h
Коротко говоря, конфигурационный файл описывает каталоги, в которых хранятся шаблоны (src), и куда будут сохраняться соответсвующие файлы (dest), и некоторые другие каталоги (lib), которые могут содержать файлы шаблонов, которые вы планируете включать с помощью директивы INCLUDE в ваши исходные шаблоны. Также в конфигурационном файле можно указать опции парсера (такие как 'verbose' и 'recurse') и при помощи регулярных выражений ограничить список файлов, которые необходимо обрабатывать парсером (ignore, accept) или указать файлы, которые вместо обработки нужно скопировать (copy).
Пример файла .ttreerc:
$HOME/.ttreerc:
verbose
recurse
# каталог, в котором хранятся другие конфигурационные файлы ttree
cfg = ~/.ttree
src = ~/websrc/src
lib = ~/websrc/lib
dest = ~/public_html/test
ignore = b(CVS|RCS)b
ignore = ^#
Можно создать много других конфигурационных файлов и сохранить их в каталоге, указанном в опции 'cfg', как показано выше. Затем вы можете указать команде ttree опцию '-f filename', чтобы использовать файлы из этого каталога.
Когда вы запускаете скрипт, он сравнивает все файлы в каталоге 'src' (включая файлы в подкаталогах, если установлена опция 'recurse') с файлами в каталоге 'dest'. Если выходного файла не существует или он имеет более раннее время модификации, чем соответсвующий исходный файл (шаблон), то исходный файл будет обработан парсером и вывод записан в выходной файл. Опция '-a' вынуждает скрипт обработать все файлы вне зависимости от времени модификации.
Скрипт не обрабатывает файлы из каталога 'lib', но он включает каталог в переменную INCLUDE_PATH, передаваемую процессору шаблонов для того чтобы он мог определить местонахождение файлов, указываемых в директивах INCLUDE или PROCESS. Таким образом, каталог 'lib' - хорошее место для хранения элементов, используемых в шаблонах, таких как header, footer, и т.п., которые не являются документами в полном смысле этого слова.
Также в конфигурационном файле можно указать различные опции Template Toolkit. Для получения подробной информации обратитесь к документации ttree и краткой справке ('ttree -h'). Например,
$HOME/.ttreerc:
pre_process = config
interpolate
post_chomp
Опция 'pre_process' позволяет указать шаблон, который будет обработан перед каждым файлом. Неудивительно, что также есть опция 'post_process' для добавления шаблона, обрабатываемого после обработки файла. В приведенном выше фрагменте мы указываем, что шаблон 'config' будет использован в качестве префиксного шаблона. Мы можем создать этот файл в каталоге 'lib' и использовать его для определния некоторых общих переменных, включая определенные ранее ссылки на веб-страницы и которые мы можем захотеть использовать в других шаблонах. Также в этот файл мы можем включить голову и заголовок HTML-документа, или меню, которые затем будут включаться в начало любого шаблона, но пока мы будем использовать для этих целей отдельный файл 'header'.
$lib/config:
[% root = '~/abw'
home = "$root/index.html"
images = "$root/images"
email = '
[email protected]'
graphics = 1
webpages = [
{ url => 'http://foo.org', title => 'The Foo Organsiation' }
{ url => 'http://bar.org', title => 'The Bar Organsiation' }
]
%]
Подготовив шаблоны 'header' и 'footer' из приведенного ранее примера и поместив их в каталог 'lib', вы можете начинать создавать в вашем каталоге 'src' веб-страницы, подобные приведенной ниже, и обрабатывать их с помощью ttree.
$src/newpage.html:
[% INCLUDE header
title = 'Another Template Toolkit Test Page'
%]
<a href="[% home %]">Home</a>
<a href="mailto:[% email %]">Email</a>
[% IF graphics %]
<img src="[% images %]/logo.gif" align=right width=60 height=40>
[% END %]
[% INCLUDE footer %]
Здесь мы показали, как использовать предопределенные переменные в качестве флагов для включения различных возможностей (например, 'graphics') и определять общие переменные, такие как адрес email, URLы домашней страницы, каталога с картинками и т.д. Такой подход позволяет определить эти перемнные один раз, и таким образом поддерживать их целостность на всех страницах и обеспечить возможность легко изменить их значения на новые.
После запуска ttree, вы должны увидеть схожий с приведенным ниже вывод (предполагается, что флаг verbose установлен).
ttree 1.14 (Template Toolkit version 1.02a)
Source: /home/abw/websrc/src
Destination: /home/abw/public_html/test
Include Path: [ /home/abw/websrc/lib ]
Ignore: [ b(CVS|RCS)b, ^# ]
Copy: [ ]
Accept: [ * ]
+ newpage.html
'+' перед 'newpage.html' показывает что файл был обработан процессором, а вывод сохранен в каталоге назначения. Если вы снова запустите эту команду, вы увидите, что в этой строке вывода вместо '+' будет выведен '-' и будет приведена причина по которой файл не был обработан процессором.
- newpage.html (not modified)
Процессор обнаружил страницу 'newpage.html' в каталоге назначения с датой модификации большей, чем у исходного файла, и не стал тратить время на его повторную обработку. Для того, чтобы принудительно обработать все исходные файлы, используйте опцию '-a'. Дополнительно вы можете один или более исходных файлов в качестве аргументов командной строки для утилиты ttree:
ttree newpage.html
Полученный после обработки процессором файл будет выглядет следующим образом.
$dest/newpage.html:
<html>
<head>
<title>Another Template Toolkit Test Page</title>
</head>
<body bgcolor="#ffffff">
<a href="~/abw/index.html">Home</a>
<a href="mailto:
[email protected]">Email</a>
<img src="~/abw/images/logo.gif" align=right width=60 height=40>
<hr>
<center>
© Copyright 2000 Me, Myself, I
</center>
</body>
</html>
Вы можете добавить сколько угодно документов в каталог 'src' и ttree обработает их аналогично. Таким образом можно полностью построить статическое содержимое сайта с помощью одной команды. Дополнительная выгода заключается в том, что вы можете быть уверены в целостности ссылок, едином стиле шапки и всех прочих компонентов, реализованных через общие шаблоны и переменные.
ДИНАМИЧЕСКАЯ ГЕНЕРАЦИЯ СТРАНИЦ С ПОМОЩЬЮ CGI СКРИПТОВ
Модуль Template обеспечивает простой интерфейс к библиотеке Template Toolkit для использования в CGI-скриптах и обработчиках Apache/mod_perl. Просто включите в ваши скрипты модуль Template с помощью команды 'use', создайте экземпляр объекта с помощью метода new(), а затем вызывайте метод объекта process(), передавая в качестве параметра имя файла шаблона. Второй передаваемый параметр - ссылка на хэш с переменными, которые мы хотим сделать доступными в шаблоне:
#!/usr/bin/perl -w
use strict;
use Template;
my $file = 'src/greeting.html';
my $vars = {
message => "Hello Worldn"
};
my $template = Template->new();
$template->process($file, $vars)
|| die "Template process failed: ", $template->error(), "n";
Для того чтобы наши скрипты работали с шаблонами из предыдущих примеров, мы можем добавить некоторые опции конфигурации в вызове конструктора, чтобы сообщить парсеру о нашем окружении:
my $template->new({
# где искать файлы шаблонов
INCLUDE_PATH => '/home/abw/websrc/src:/home/abw/websrc/lib',
# предварительно обработать lib/config, чтобы определить дополнительные переменные
PRE_PROCESS => 'config',
});
Заметьте, что здесь мы определяем в опции PRE_PROCESS файл 'config'. Это означает, что шаблоны, которые мы будем обрабатывать могут использовать те же глобальные переменные, которые мы определили раньше для использования в статических страницах. Нам не нужно повторно определять их в скрипте. Тем не менее, мы можем предоставить дополнительные данные и функциональность, специфичную для скрипта через хэш переменных, передаваемый методу process().
Элементы хэша могут содержать обычный текст или другие переменные, ссылки на массивы, другие хэши, функции или объекты. Template Toolkit автоматически применит нужную процедуру для доступа к данным различного типа, когда вы будете использовать переменные в шаблоне.
Приведем более детальный пример для дальнейшего рассмотрения. Среди различных переменных шаблона, определенных в '$vars', мы создали ссылку на объект CGI и ссылку на функцию 'get_user_projects'.
#!/usr/bin/perl -w
use strict;
use Template;
use CGI;
$| = 1;
print "Content-type: text/htmlnn";
my $file = 'userinfo.html';
my $vars = {
'version' => 3.14,
'days' => [ qw( mon tue wed thu fri sat sun ) ],
'worklist' => &get_user_projects,
'cgi' => CGI->new(),
'me' => {
'id' => 'abw',
'name' => 'Andy Wardley',
},
};
sub get_user_projects {
my $user = shift;
my @projects = ... # заполняем данными
return @projects;
}
my $template = Template->new({
INCLUDE_PATH => '/home/abw/websrc/src:/home/abw/websrc/lib',
PRE_PROCESS => 'config',
});
$template->process($file, $vars)
|| die $template->error();
Ниже приведен пример шаблона, который мы можем использовать в скрипте.
$src/userinfo.html:
[% INCLUDE header
title = 'Template Toolkit CGI Test'
%]
<a href="mailto:[% email %]">Email [% me.name %]</a>
<p>This is version [% version %]</p>
<h3>Projects</h3>
<ul>
[% FOREACH project = worklist(me.id) %]
<li> <a href="[% project.url %]">[% project.name %]</a>
[% END %]
</ul>
[% INCLUDE footer %]