Раздел описывает синтаксис, структуру и семантику директив и языка общего представления Template Toolkit.

По умолчанию директивы шаблона заключены между последовательностями символов '[%' и '%]'. Например,

    [% PROCESS header %]

    <h1>Hello World!</h1>
    <a href="[% page.next %]"><img src="[% icon.next %].gif"></a>

    [% PROCESS footer %]

Вы можете изменить символы тегов с помощью опций конфигурации START_TAG, END_TAG и TAG_STYLE. Также можно использовать внутри шаблона директиву TAGS для определния стиля тегов для текущего файла шаблона.

Также вы можете установить опцию INTERPOLATE, чтобы разрешить использовать непосредственно внутри шаблонов обычные (с префиксом '$') ссылки на переменные.

    # INTERPOLATE => 0
    <td>[% name %]</td>  <td>[% email %]</td>

    # INTERPOLATE => 1
    <td>$name</td>  <td>$email</td>

Директивы можно включать в любом месте текста и можно разбивать на несколько строк. Дополнительные пробельные символы внутри директивы в общем случае несущественны.

    [% INCLUDE header
       title = 'Hello World'
       bgcol = '#ffffff'
    %]

    [% INCLUDE menu align='right'%]

    Name: [% name %]  ([%id%])

Символ '#' используется для обозначения комментария внутри директивы. Если вставить символ сразу за открывающим тегом вся директива целиком будет проигнорирована парсером.

    [%# вся директива целиком игнорируется
        вне зависимости от того на сколько строк она разбита
    %]

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

    [% # это комментарий
       theta = 20      # so is this
       rho   = 30      # <aol>me too!</aol>
    %]

Вы можете добавить '-' или '+' в открывающем или завершающем теге директивы, чтобы управлять удалением переводов строки до и после директивы. Подробности смотрите в описании опций PRE_CHOMP и POST_CHOMP.

    [% BLOCK foo -%]		# удаляет замыкающий перевод строки
    This is block foo
    [%- END %]			# удаляет предшествующий перевод строки

Простейшие директивы GET и SET получают и устанавливают значения переменных соответственно. Ключевые слова GET и SET фактически являются опциональными так как парсер достаточно умен, чтобы распознать их без явного указания (однако обратите внимание на приведенное ниже предупреждение об использовании обратной нотации). Таким образом:

    [% SET foo = 10 %]
    [% GET foo %]

вы чаще встретите в таком виде:

    [% foo = 10 %]
    [% foo %]

Также вы можете использовать простейшие логические выражения в неявной директиве GET:

    [% title or template.title or 'Default Title' %]

    [% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %]

Все остальные директивы должны начинаться с ключевого слова, записанного в ВЕРХНЕМ РЕГИСТРЕ (исключением является использование опции ANYCASE, смотри далее). Все директивы записываются в ВЕРХНЕМ РЕГИСТРЕ для лучшей визуализации и для того чтобы отличать их от переменных с тем же именем, записанным в другом регистре. Например, совершенно законно использование переменной с именем 'stop' которая полностью отличается от директивы STOP.

    [% stop = 'Clackett Lane Bus Depot' %]

    The bus will next stop at [% stop %]    # переменная

    [% STOP %]                              # директива

Такие директивы как FOREACH, WHILE, BLOCK, FILTER и т.д. обозначают начало блока, который может содержать текст или другие директивы, и который завершается соответствующей директивой END. Вложенность блоков не ограничена. Директивы IF, UNLESS, ELSIF и ELSE также определяют блоки и могут использоваться друг с другом по обычным правилам.

    [% FOREACH item = [ 'foo' 'bar' 'baz' ] %]
       * Item: [% item %]
    [% END %]

    [% BLOCK footer %]
       Copyright 2000 [% me %]
       [% INCLUDE company/logo %]
    [% END %]

    [% IF foo %]
       [% FOREACH thing = foo.things %]
	  [% thing %]
       [% END %]
    [% ELSIF bar %]
       [% INCLUDE barinfo %]
    [% ELSE %]
       do nothing...
    [% END %]

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

    [% INCLUDE userinfo FOREACH user = userlist %]

    [% INCLUDE debugtxt msg="file: $error.info"
         IF debugging %] 

    [% "Danger Will Robinson" IF atrisk %]

Сравните с:

    [% FOREACH user = userlist %]
       [% INCLUDE userinfo %]
    [% END %]

    [% IF debugging %]
       [% INCLUDE debugtxt msg="file: $error.info" %]
    [% END %]

    [% IF atrisk %]
    Danger Will Robinson
    [% END %]

Вывод директивы может быть захвачен простым присваиванием директивы перменной.

    [% headtext = PROCESS header title="Hello World" %]

    [% people = PROCESS userinfo FOREACH user = userlist %]

В связке с директивой BLOCK это можно использовать для определения больших блоков текста или другого контента.

    [% poem = BLOCK %]
       The boy stood on the burning deck,
       His fleece was white as snow.
       A rolling stone gathers no moss,
       And Keith is sure to follow.
    [% END %]

Важное предупреждение относительно использования этого синтаксиса в связке с обратной нотацией. Следующая директива ведет себя не так как можно предполагать:

    [% var = 'value' IF some_condition %]

В данном случае, директива интерпретируется как (для ясности добавлены пробелы)

    [% var = IF some_condition %]
       value
    [% END %]

а не как

    [% IF some_condition %]
       [% var = 'value' %]
    [% END %]

Переменной присваивается вывод блока IF, который вернет 'value', если условие выполняется и ничего, если условие ложно. Другими словами, следующая директива всегда будет приводить к очистке переменной 'var'.

    [% var = 'value' IF 0 %]

Для того чтобы добиться ожидаемого поведения, директиву следует записать так:

    [% SET var = 'value' IF some_condition %]

Несколько директивы FILTER могут быть выстроены в цепочку. Они вызываются согласно определенному порядку и выходной поток одного передается на входной поток следующего.

    [% PROCESS somefile FILTER truncate(100) FILTER html %]

В качестве замены FILTER можно использовать символ '|' (pipe).

    [% PROCESS somefile | truncate(100) | html %]

Несколько директив, разделенных символом ';', могут быть заключены между одной парой тегов. Исключение составляет директива TAGS, которая всегда должна быть указана отдельно.

    [% IF title;
          INCLUDE header;
       ELSE;
	  INCLUDE other/header  title="Some Other Title";
       END
    %]

Сравните с:

    [% IF title %]
       [% INCLUDE header %]
    [% ELSE %]
       [% INCLUDE other/header  title="Some Other Title" %]
    [% END %]

Энди Уардли (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.