В разделе описываются различные способы связывания данных Perl с переменными шаблона и доступа к ним через директивы Template Toolkit.

В качестве второго параметра методу process() можно передать ссылку на хеш, содержащий определения переменных шаблона. Опция VARIABLES (раньше называвшаяся PRE_DEFINE) используется для предварительного определения переменных для всех шаблонов, обрабатываемых объектом.

    my $tt = Template->new({
	VARIABLES => {
	    version => 3.14,
	    release => 'Sahara',
	},
    });

    my $vars = {
	serial_no => 271828,
    };

    $tt->process('myfile', $vars);

'myfile':

    This is version [% version %] ([% release %]).
    Serial number: [% serial_no %]

вывод:

    This is version 3.14 (Sahara)
    Serial number: 271828

Имена переменных могут содержать цифры, латинские буквы и знаки подчеркивания. Они могут быть записаны в нижнем, верхнем или смешанном регистрах, хотя общепринятой договоренностью является использование нижнего регистра. Тем не менее регистр важен, и 'foo', 'Foo' и 'FOO' являются именами разных переменных. Имена в верхнем регистре разрешены, но их использование не рекомендуется из-за возможных конфликтов с существующими или будущими зарезервированными словами. Начиная с версии 2.00 такими являются:

    GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER
    IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE
    USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META
    TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP
    CLEAR TO STEP AND OR NOT MOD DIV END

Значения переменных могут быть практически любого типа, используемого в Perl, включая обычные скаляры, ссылки на массивы, хеши, функции или объекты. Template Toolkit автоматически применит правильную функцию для доступа к значениям этих переменных, как только они будут использованы в шаблоне.

Пример:

    my $vars = {
	article => 'The Third Shoe',
	person  => {
	    id    => 314,
	    name  => 'Mr. Blue',
	    email => 'blue@nowhere.org',
	},
	primes  => [ 2, 3, 5, 7, 11, 13 ],
	wizard  => sub { return join(' ', 'Abracadabra!', @_) },
	cgi     => CGI->new('mode=submit&debug=1'),
    };

шаблон:

    [% article %]

    [% person.id %]: [% person.name %] <[% person.email %]>

    [% primes.first %] - [% primes.last %], including [% primes.3 %]
    [% primes.size %] prime numbers: [% primes.join(', ') %]

    [% wizard %]
    [% wizard('Hocus Pocus!') %]

    [% cgi.param('mode') %]

вывод:

    The Third Shoe

    314: Mr. Blue <blue@nowhere.org>

    2 - 13, including 7
    6 prime numbers: 2, 3, 5, 7, 11, 13

    Abracadabra!
    Abracadabra! Hocus Pocus!

    submit

Доступ к обычным скалярным переменным обеспечивается простым указанием их имен. Поскольку они являются всего лишь элементами хеша переменных верхнего уровня, их можно рассматривать как частный случай описанных ниже ссылок на хеши, подразумевая, что они автоматически относятся к главному пространству имен хеша.

    [% article %]

К элементам хеша можно обратиться, указывая ссылку на хеш и ключ, отделенный оператором '.'.

    my $vars = {
  	'home' => 'http://www.myserver.com/homepage.html',
  	'page' => {
  	    'this' => 'mypage.html',
  	    'next' => 'nextpage.html',
  	    'prev' => 'prevpage.html',
  	},
    };

шаблон:

    <a href="[% home %]">Home</a>
    <a href="[% page.prev %]">Previous Page</a>
    <a href="[% page.next %]">Next Page</a>

вывод:

    <a href="http://www.myserver.com/homepage.html">Home</a>
    <a href="prevpage.html">Previous Page</a>
    <a href="nextpage.html">Next Page</a>

Любой ключ хеша. начинающийся с симоволов '_' или '.' будет считаться приватным и его значение не может быть вычислено внутри шаблона. Вместо этого Template Toolkit проигнорирует такую переменную (за исключением случая, когда включена опция DEBUG) и возвратит неопределенное значение.

    my $vars = {
	message => 'Hello World!',
	_secret => "On the Internet, no-one knows you're a dog",
	thing   => {
	     public  => 123,
	    _private => 456,
	   '.hidden' => 789,
	},
    };

шаблон:

    [% message %]		# выводит "Hello World!"
    [% _secret %]               # ничего не выводит
    [% thing.public %]          # выводит "123"
    [% thing._private %]        # ничего не выводит
    [% thing..hidden %]         # ERROR: unexpected token (..)

Чтобы получить доступ к элементу хеша с ключом, значение которого сохранено в другой переменной, используйте '$' перед переменной, чтобы вычислить ее перед использованием (смотри Интерполяция переменных).

    [% pagename = 'next' %]
    [% page.$pagename %]       # тоже что и [% page.next %]

Когда установлена переменная, которая содержит элементы пространств имен (т.е. имеет один и более символов '.' в имени), любые хеши, необходимые для представления промежуточных пространств имен будут созданы автоматически. В следующем примере хеш 'product' будет автоматически создан, даже если он не был определен ранее.

    [% product.id    = 'XYZ-2000'
       product.desc  = 'Bogon Generator'
       product.price = 666
    %]

    The [% product.id %] [% product.desc %]
    costs $[% product.price %].00

вывод:

    The XYZ-2000 Bogon Generator
    costs $666.00

Можно использовать знакомую в Perl конструкцию '{' ... '}', чтобы явно определить хеш и присвоить его переменной. Учтите, что запятые не являются обязательными между парами ключ/значение и вместо '=>' можно использовать '='.

    [% product = {
  	 id    => 'XYZ-2000',
  	 desc  => 'Bogon Generator',
  	 price => 666,
       }
    %]

Оператор точка также используется для доступа к элементам массива.

    my $vars = {
  	'people' => [ 'Tom', 'Dick', 'Larry' ],
    };

шаблон:

    [% people.0 %]			# Tom
    [% people.1 %]			# Dick
    [% people.2 %]			# Larry

Для прохода по элементам массива используется директива FOREACH.

    [% FOREACH person = people %]
    Hello [% person %]
    [% END %]

вывод:

    Hello Tom
    Hello Dick
    Hello Larry

Массивы можно создавать по месту, с использованием обычной конструкции анонимного массива '[' ... ']'. Запятые между элементами не являются обязательными.

    [% cols = [ 'red', 'green', 'blue' ] %]

    [% FOREACH c = cols %]
       ...

или:

    [% FOREACH c = [ 'red', 'green', 'blue' ] %]
       ...

Простую последовательность чисел можно создать с использованием знакомого оператора '..':

    [% n = [ 1 .. 4 ] %]    # n принимает значения [ 1, 2, 3, 4 ] 

    [% x = 4
       y = 8
       z = [x..y]
    %]                      # z принимает значения [ 4, 5, 6, 7, 8 ]

Переменные шаблона могут содержать ссылки на функции Perl. При использовании такой переменной Template Toolkit автоматически вызывает функцию, передавая ей указанные дополнительные аргументы. Значение, возвращаемое функцией, используется в качестве значения переменной и вставляется в вывод документа.

    my $vars = {
	wizard  => sub { return join(' ', 'Abracadabra!', @_) },
    };	

шаблон:

    [% wizard %]			# Abracadabra!
    [% wizard('Hocus Pocus!') %]	# Abracadabra! Hocus Pocus!

Переменные шаблона также могут содержать ссылки на объекты Perl. Методы вызываются с помощью оператора '.' после переменной объекта. Дополнительные аргументы указываются также как и для функций.

    use CGI;

    ...

    my $vars = {
	# жестко задаем параметры CGI для демонстрации примера
	cgi  => CGI->new('mode=submit&debug=1'),
    };

шаблон:

    [% FOREACH p = cgi.param %]		# возвращает список ключей параметров
    [% p %] => [% cgi.param(p) %]	# получаем значение каждого параметра
    [% END %]

вывод:

    mode => submit
    debug => 1

Методы объекта также могут вызываться как L-значения. Другими словами, они могут появляться в левой части операции присваивания. Будет вызван метод, а присваиваемое значение будет передано как аргумент.

    [% myobj.method = 10 %]

эквивалентно:

    [% myobj.method(10) %]

Функциям и методам передаются любые аргументы, указанные в шаблоне. Любые переменные шаблона в списке аргументов будут предварительно вычислены и результирующие значения переданы в код.

    my $vars = {
	mycode => sub { return 'received ' . join(', ', @_) },
    };

шаблон:

    [% foo = 10 %]
    [% mycode(foo, 20) %]		# получает 10, 20

Также можно задавать именованные параметры. Они автоматически собираются в единственный хеш, который передается по ссылке как последний аргумент вызова функции. Именованные параметры могут быть указаны с помощью '=>' или '=' и могут указываться в любом месте списка аргументов.

    my $vars = {
	myjoin => \&myjoin,
    };

    sub myjoin {
	# проверяем, является ли последний аргумент ссылкой на хеш
	my $params = ref $_[-1] eq 'HASH' ? pop : { };
	return join($params->{ joint } || ' + ', @_);
    }

шаблон:

    [% myjoin(10, 20, 30) %]
    [% myjoin(10, 20, 30, joint = ' - ' %]
    [% myjoin(joint => ' * ', 10, 20, 30 %]

вывод:

    10 + 20 + 30
    10 - 20 - 30
    10 * 20 * 30

Аргументы в скобках можно передавать любым элементам переменной, не только тем которые связаны с кодом или методами. В настоящий момент, параметры игнорируются, если переменная не является "вызываемой", но это может быть использовано в будущих расширениях. Рассматривайте их как "подсказки" к таким переменным, а не как аргументы, передаваемые функции.

    [% r = 'Romeo' %]
    [% r(100, 99, s, t, v) %]		# выводит "Romeo"

Пользовательский код должен возвращать значение переменной, которую он представляет. Это может быть любой описанный выше тип данных Perl: скаляр, или ссылка на массив, хеш, функцию или объект. Если код возвращает список значений, эти значения автоматически сохраняются в массив, к которому можно обратиться обычным образом через ссылку.

    my $vars = {
	# хотя оба варианта правильные, рекомендуется первый
	items1 => sub { return [ 'foo', 'bar', 'baz' ] },
	items2 => sub { return ( 'foo', 'bar', 'baz' ) },
    };

шаблон:

    [% FOREACH i = items1 %]
       ...
    [% END %]

    [% FOREACH i = items2 %]
       ...
    [% END %]

Сообщения об ошибках можно создавать в пользовательском коде с помощью die(). Исключения, возбужденные таким способом, перехватываются Template Toolkit и преобразуются в структурированные исключения, которые могут быть обработаны внутри шаблона. Ссылка на объект исключения доступна затем через переменную 'error'.

    my $vars = {
	barf => sub {
	    die "a sick error has occurred\n";
	},
    };

шаблон:

    [% TRY %]
       [% barf %]	    # вызываем функцию, которая генерирует ошибку через die()
    [% CATCH %]
       [% error.info %]	    # выводит "a sick error has occurred\n"
    [% END %]

Сообщения об ошибках, сгенерированные через die(), преобразуются в исключения типа 'undef'. Исключения определенных пользователем типов могут быть сгенерированы вызовом die() со ссылкой на объект Template::Exception.

    use Template::Exception;

    ...

    my $vars = {
	login => sub {
	    ...
	    die Template::Exception->new('badpwd',
					 'password too silly');
	},
    };

шаблон:

    [% TRY %]
       [% login %]
    [% CATCH badpwd %]
       Bad password: [% error.info %]
    [% CATCH %]
       Some other '[% error.type %]' error: [% error.info %]
    [% END %]

Исключения типов 'stop' и 'return' используются для реализации директив STOP и RETURN. Возбуждение исключения:

    die (Template::Exception->new('stop'));

оказывает тот же эффект, что и директива:

    [% STOP %]

Функции и методы также могут генерировать ошибки, возвращая массив или ссылку на массив, содержащий неопределенное значение (undef), следом за которым идет объект-исключение или сообщение об ошибке. Это поддерживается для обратной совместимости с версией 1, но может быть изменено в будущих версиях.

    my $vars = {
	# в настоящий момент эквивалентно
	barf => sub {
	    die "I'm sorry Dave, I can't do that";
	},
	yack => sub {
	    return (undef, "I'm sorry Dave, I can't do that");
	},
    };

Template Toolkit реализует ряд "виртуальных методов", которые можно применять к скалярам, хешам или массивам. Например:

    [% mylist = [ 'foo', 'bar', 'baz' ] %]
    [% newlist = mylist.sort %]

Здесь 'mylist' - обычная ссылка на массив, а 'sort' - виртуальный метод, который возвращает новый массив элементов в отсортированном порядке. Виртуальные методы можно связывать в цепочку. Например:

    [% mylist.sort.join(', ') %]

Здесь 'join' - виртуальный метод, объединяющий отсортированный список в одну строку, генерируя следующий вывод:

    bar, baz, foo

Подробнее о доступных виртуальных методах смотри Template::Manual::VMethods.

Template Toolkit использует '$' для однозначного указания, что переменная должна быть вычислена на месте. Чаще всего это можно встретить в строках в двойных кавычках:

    [% fullname = "$honorific $firstname $surname" %]

Или как включения в обычном тексте при установленной опции INTERPOLATE:

    Dear $honorific $firstname $surname,

Те же правила действуют внутри директив. Если переменной предшествует '$', она перед использованием заменяется на свое значение. Наиболее часто это используется для получения элемента хеша, когда значение ключа сохранено в переменной.

    [% uid = 'abw' %]
    [% userlist.$uid %]		    # тоже что и 'userlist.abw'

Фигурные скобки используются при необходимости для выделения имен интерполируемых переменных.

    [% userlist.${me.id}.name %]    

Такие директивы как INCLUDE, PROCESS, и т.д., которые принимают в качестве первого аргумента имя шаблона, для удобства автоматически заключают его в двойные кавычки.

    [% INCLUDE foo/bar.txt %]

эквивалентно:

    [% INCLUDE "foo/bar.txt" %]

Чтобы включить (INCLUDE) шаблон, чье имя сохранено в переменной, можно просто указать имя переменной с префиксом '$', и оно будет вычислено.

    [% myfile = 'header' %]
    [% INCLUDE $myfile %]

эквивалентно:

    [% INCLUDE header %]

Имейте ввиду, что таким же способом можно обработать переменную, содержащую ссылку на объект Template::Document.

    my $vars = {
	header => Template::Document->new({ ... }),
    };

шаблон:

    [% INCLUDE $header %]

Любая простая переменная, которую вы создадите, или любое изменение в существующих переменных, будут существовать только во время обработки шаблона. Перед обработкой шаблона хеш верхнего уровня копируется, и все изменения, сделанные в этой копии, не затрагивают оригинал. Тоже самое происходит при включении другого шаблона с помощью INCLUDE. Хеш текущего пространства имен копируется, чтобы предотвратить влияние любых изменений, сделанных с переменными во включаемом шаблоне. Директива PROCESS пропускает этот шаг локализации, с одной стороны делая процесс более быстрым, но с другой требуя большего внимания к возможным побочным эффектам, вызванным созданием или изменением любых переменных внутри обрабатываемого шаблона.

    [% BLOCK change_name %]
       [% name = 'bar' %]
    [% END %]

    [% name = 'foo' %]
    [% INCLUDE change_name %]
    [% name %]			    # foo
    [% PROCESS change_name %]
    [% name %]			    # bar

Структурированные переменные ведут себя немного иначе, поскольку локализация проводится только поверхностно. Копируется текущее пространство имен хеша, но попытки сделать глубокое копирование структур внутри него (хеши, массивы, объекты и т.д.) не предпринимается. Например, ссылка на хеш будет скопирована и будет создана новая ссылка, но указывать она будет на тот же самый хеш. Таким образом, общее правило таково: простые переменные (переменные без точки) локализуются, а существующие комплексные структуры (переменные с точкой) - нет.

    [% BLOCK all_change %]
       [% x = 20 %]		    # изменяет копию
       [% y.z = 'zulu' %]	    # изменяет оригинал
    [% END %]

    [% x = 10
       y = { z => 'zebra' }
    %]
    [% INCLUDE all_change %]
    [% x %]			    # все еще '10'
    [% y.z %]			    # теперь 'zulu'

Если вы создаете комплексную структуру, такую как ссылка на хеш или массив, в локальном контексте шаблона, он прекратит свое существование после завершения обработки шаблона.

    [% BLOCK new_stuff %]
       [% # определяем в локальном контексте новый хеш 'y'
          y = { z => 'zulu' }
       %]
    [% END %]

    [% x = 10 %]
    [% INCLUDE new_stuff %]
    [% x %]			    # выводит '10'
    [% y %]			    # ничего, y неопределено

Аналогично, если вы обновляете элемент составной переменной, которая до сих пор не существовала, то хеш будет создан автоматически и снова удален в конце блока.

    [% BLOCK new_stuff %]
       [% y.z = 'zulu' %]
    [% END %]

Тем не менее, если хеш уже существовал, то изменения обязательно отразятся на оригинале. Во избежание возможных недоразумений, рекомендуется не обновлять элементы комплексных переменных внутри блоков или шаблонов, включаемых другими.

Если необходимо создать и изменять по настоящему глобальные переменные, можно использовать пространство имен 'global'. Этот хеш автоматически создается в пространстве имен верхнего уровня, ссылка на него одинакова во всех шаблонах, локализованных или нет. Изменения, сделанные в переменных внутри этого хеша, будут видимы во всех шаблонах.

    [% global.version = 123 %]

В дополнение к переменным, которые разрешаются каждый раз при обработке шаблона, можно определить переменные, которые разрешаются только один раз во время компиляции. В общем случае это приводит к уменьшению времени обработки шаблонов, поскольку работы для парсера становится меньше.

Определить константы времени компиляции можно в хеше CONSTANTS, передаваемом аналогично VARIABLES в качестве аргумента конструктору. Хеш CONSTANTS может содержать любые комплексные, вложенные или динамические типы данных, как и обычные переменные.

    my $tt = Template->new({
	CONSTANTS => {
	    version => 3.14,
	    release => 'skyrocket',
	    col     => {
		back => '#ffffff',
		fore => '#000000',
	    },
	    myobj => My::Object->new(),
	    mysub => sub { ... },
	    joint => ', ',
	},
    });

Внутри шаблона, доступ к этим переменным осуществляется через пространство имен 'constants'.

    Version [% constants.version %] ([% constants.release %])

    Background: [% constants.col.back %]

Когда шаблон компилируется, ссылки на эти переменные заменяются на соответствующие значения. В дальнейшем при обработке шаблона поиск этих переменных не требуется.

С константами можно вызывать функции, методы объектов, и даже виртуальные методы.

    [% constants.mysub(10, 20) %]
    [% constants.myobj(30, 40) %]
    [% constants.col.keys.sort.join(', ') %]

Единственное важное исключение - любые аргументы, передаваемые этим функциям или методам, должны быть либо литеральными величинами, либо константами времени компилияции.

Оба примера будут работать:

    # литеральный аргумент
    [% constants.col.keys.sort.join(', ') %]

    # аргумент - константа
    [% constants.col.keys.sort.join(constants.joint) %]

Но следующий пример сгенерирует исключение во время разбора, потому что 'joint' - перменная времени испольнения и не может быть вычислена на этапе компиляции.

    # ERROR: runtime variable argument!
    [% constants.col.keys.sort.join(joint) %]

Опция CONSTANTS_NAMESPACE может быть использована для определения другого префикса пространства имен для констант. Например:

    my $tt = Template->new({
	CONSTANTS => {
	    version => 3.14,
	    # ...etc...
	},
	CONSTANTS_NAMESPACE => 'const',
    });

После этого константы внутри шаблона будут выглядеть следующим образом:

    [% const.version %]

Template Toolkit автоматически определяет ряд специальных перменных.

• template
  

  Переменная 'template' содержит ссылку на главный обрабатываемый шаблон в виде объекта Template::Document. Эта переменная правильно определена внутри шаблонов PRE_PROCESS, PROCESS и POST_PROCESS, что позволяет использовать метаданные из главного шаблона использовать в стандартных шапках, подвалах и т.п. Автоматически предоставляются элементы метаданных 'name' и 'modtime', которые соответственно содержат имя шаблона и время его модификации в секундах, прошедших с ключевого момента (1 января 1970 года для Unix-систем).

  Имейте ввиду, что переменная 'template' всегда ссылается на шаблон верхнего уровня, даже при обработке других компонентов шаблона через INCLUDE, PROCESS и т.п.

• component
  

  Переменная 'component' аналогична 'template', но всегда содержит ссылку на текущий обрабатываемый шаблон. В главном шаблоне, переменные 'template' и 'component' совпадают и ссылаются на один и тот же объект Template::Document. В любом другом шаблоне, вызываемом из главного, переменная 'template' сохарнится без изменений, а 'component' будет содержать новую ссылку на текущий компонент.

  Этот пример должен продемонстрировать разницу:

      $template->process('foo')
  	|| die $template->error(), "\n";

  'foo':

      [% template.name %]		    # foo
      [% component.name %]	    # foo
      [% PROCESS footer %]

  'footer':

      [% template.name %]		    # foo
      [% component.name %]            # footer

  Дополнительно, переменная 'component' имеет два специальных поля: 'caller' and 'callers'. 'caller' содержит имя шаблона, который вызвал текущий шаблон (или undef, если значения 'template' и 'component' совпадают). 'callers' содержит ссылку на список всех шаблонов, которые вызывались по пути к текущему шаблону (аналогично стеку вызовов). Первым элементом списка является самый внешний шаблон.

  Вот пример:

  'outer.tt2':

      [% component.name %]        # 'outer.tt2'
      [% component.caller %]      # undef
      [% component.callers %]     # undef
      [% PROCESS 'middle.tt2' %]

  'middle.tt2':

      [% component.name %]        # 'middle.tt2'
      [% component.caller %]      # 'outer.tt2'
      [% component.callers %]     # [ 'outer.tt2' ]
      [% PROCESS 'inner.tt2' %]

  'inner.tt2':

      [% component.name %]        # 'inner.tt2'
      [% component.caller %]      # 'middle.tt2'
      [% component.callers %]     # [ 'outer.tt2', 'middle.tt2' ]

• loop
  

  Внутри цикла FOREACH переменная 'loop' ссылается на объект Template::Iterator, отвечающий за управление циклом.

      [% FOREACH item = [ 'foo', 'bar', 'baz' ] -%]
         [% "Items:\n" IF loop.first -%]
         [% loop.count %]/[% loop.size %]: [% item %]
      [% END %]

• error
  

  Внутри блока CATCH переменная 'error' содержит ссылку на объект Template::Exception, содержащий исключение, сгенерированное внутри блока TRY. У переменной можно использовать методы 'type' и 'info', либо можно вывести саму переменную. При этом она автоматически преобразуется в строку, содержащую сообщение вида "$type error - $info". Более подробно смотри Template::Exception.

      [% TRY %]
         ...
      [% CATCH %]
         [% error %]
      [% END %]

• content
  

  Директива WRAPPER перехватывает вывод блока в шаблоне, а затем включает указанный шаблон, передавая в него перехваченный вывод как переменную 'content'.

      [% WRAPPER box %]
      Be not afeard; the isle is full of noises,
      Sounds and sweet airs, that give delight and hurt not.
      [% END %]

      [% BLOCK box %]
      <table border=1>
      <tr>
        <td>
        [% content %]
        </td>
      </tr>
      </table>
      [% END %]

Составные 'точечные' переменные могут содержать любое число независимых элементов. Каждый элемент может вычисляться в любой из разрешенных типов переменных и процессор корректно использует это значение для вычисления оставшейся части переменной. Каждому из промежуточных элементов можно передавать аргументы.

    [% myorg.people.sort('surname').first.fullname %]

Можно использовать промежуточные переменные, и их поведение будет полностью соответствовать ожидаемому.

    [% sorted = myorg.people.sort('surname') %]
    [% sorted.first.fullname %]

Эта упрощенная точечная нотация позволяет скрыть детали реализации ваших данных. Например, можно реализовать структуру данных как хеш, а затем заменить ее на объект без необходимости вносить какие-то изменения в шаблоны.

Энди Уардли (Andy Wardley <abw@andywardley.com>)

http://www.andywardley.com/

Template Toolkit версия 2.14, дата релиза - 4 октября 2004.

  Copyright (C) 1996-2004 Andy Wardley.  All Rights Reserved.
  Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.

Этот модуль является свободно-распространяемым программным обеспечением; вы можете распространять и/или модифицировать его на тех же условиях, что и Perl.