Template Toolkit

Последнюю версию Template Toolkit можно найти на CPAN: http://www.cpan.org/modules/by-module/Template/.

Если у вас не установлен AppConfig 1.55, скачайте и установите с CPAN: http://www.cpan.org/authors/Andy_Wardley/.

Следующие модули являются необязательными. Если вы их установите, то сможете использовать их через соответствующие плагины Template Toolkit. Если они вам не нужны, их можно не устанавливать, Все эти модули доступны на CPAN.

    Text::Autoformat 1.03+
    DBI 1.14+ (и подходящие драйверы DBD)
    GD 1.32+
    GD::Text 0.80+
    GD::Graph 1.33+
    GD::Graph3d 0.55+
    Pod::POM 0.1+
    XML::Parser 2.23+
    XML::DOM 1.27+ (в составе libxml-enno)
    XML::RSS 0.9+
    XML::XPath 1.00+

Для установки Template Toolkit:

    tar zxf Template-Toolkit-2.14.tar.gz
    cd Template-Toolkit-2.14
    perl Makefile.PL
    make
    make test
    make install

Makefile.PL запросит дополнительные опции конфигурации, включая установку необязательных библиотек шаблонов, документации в формате HTML и примеров. При быстрой начальной установке, можно спокойно ответить 'n' на все эти вопросы.

Если вы используете ActivePerl для Win32, вы можете использовать Perl Package Manager (PPM) для установки Template Toolkit. Крис Уинтерс (Chris Winters) поддерживает репозиторий PPM пакетов, который содержит Template Toolkit, AppConfig и другие модули. Дополнительную информацию ищите на http://openinteract.sourceforge.net/.

Подробнее смотрите ниже в разделах: 'КОНФИГУРИРОВАНИЕ', 'СБОРКА И ТЕСТИРОВАНИЕ' и 'УСТАНОВКА'.

Template Toolkit написан полностью на Perl и может использоваться на любой платформе, на которой может работать Perl. Для работы требуется Perl версии 5.005 или выше.

Утилита 'ttree' использует модуль AppConfig (версии 1.55 или выше) для разбора опций командной строки и конфигурационных файлов. Модуль доступен на CPAN: http://www.cpan.org/authors/Andy_Wardley/.

В Template Toolkit реализована архитектура "плагинов", которая позволяет включить в ваши шаблоны функциональность практически любого модуля Perl. В пакет включена часть модулей плагинов, реализующих интерфейсы к базам данных (DBI), XML файлам (XML::DOM, XML::RSS, XML::XPath), CGI скриптам (CGI), и т.д. Некоторые из этих модулей плагинов зависят от внешних модулей, которые тем не менее не являются необходимыми для установки Template Toolkit. Все модули плагинов устанавливаются независимо от неразрешенных зависимостей, таким образом, в будущем вы сможете установить внешний модуль и затем использовать плагин без необходимости переустановки Template Toolkit.

Если вы хотите разрешить использование всех плагинов, то следующие модули (все доступны на CPAN), должны быть установлены:

    Плагин		Зависит от
    ------              --------
    Autoformat          Text::Autoformat 1.03+
    DBI                 DBI 1.14+ и подходящие DBD драйверы
    GD                  GD 1.32+
    GD::Text            GD::Text 0.80+
    GD::Graph           GD::Graph 1.33+
    GD::Graph::lines3d  GD::Graph3d 0.55+
    Pod                 Pod::POM 0.1+
    XML::DOM            XML::DOM 1.27+   (требует XML::Parser 2.23+)
    XML::RSS            XML::RSS 0.9+    (тоже самое)
    XML::XPath          XML::XPath 1.00+ (тоже самое)

ПРИМЕЧАНИЕ:

Последнюю версию Template Toolkit можно загрузить с любого сайта CPAN: http://www.cpan.org/modules/by-module/Template/.

Промежуточные и разрабатываемые версии также доступны вместе с другой полезной информацией, новостями, публикациями, архивами листов рассылки и т.п. на сайте Template Toolkit: http://www.template-toolkit.org/.

Template Toolkit распространяется в виде архива tar.gz:

    Template-Toolkit-<версия>.tar.gz

где <версия> означает номер текущей версии, например, 2.14.

Для установки Template Toolkit, распакуйте архив пакета. В результате будет создан каталог установки:

    tar zxf Template-Toolkit-2.14.tar.gz

или

    gunzip Template-Toolkit-2.14.tar.gz
    tar xf Template-Toolkit-2.14.tar

Перейдите в созданый каталог,

    cd Template-Toolkit-2.14

и выполните обычную процедуру установки в Perl:

    perl Makefile.PL
    make
    make test
    make install	    # могут понадобится права root

Makefile.PL выполняет ряд необходимых проверок и затем задает ряд вопросов о конфигурации. В следующем разделе 'КОНФИГУРИРОВАНИЕ' содержится более подробная информация об этом.

Известно несколько небольших проблем в наборе тестов. Некоторые тесты завершаются неудачно при определенных условиях. Не один из них не является серьезной проблемой. Раздел 'СБОРКА И ТЕСТИРОВАНИЕ' содержит подробное описание этих ошибок.

Если вы установите дополнительные компоненты, вам может понадобиться выполнить ряд шагов после установки, чтобы обеспечить возможность просмотра через веб-броузер библиотек шаблонов, HTML документации и примеров. Это разъясняется в разделе 'УСТАНОВКА'.

Простейший путь установки Template Toolkit на платформе Win32 - использовать Perl Package Manager (ppm) дистрибутива ActiveState и собранные Крисом Уинтерсом (Chris Winters) пакеты. Более подробно смотрите на http://openinteract.sourceforge.net/ и http://activestate.com/.

Если вам так необходимо, можно установить Template Toolkit на системе Win32 вручную согласно инструкции приведенной в этом документе. Тем не менее имейте в виду, что вы скорее всего столкнетесь с проблемами при использовании 'make' и вместо нее лучше использовать утилиту 'nmake', доступную на ftp-архиве Microsoft: ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe.

В этом случае, следует заменить 'make' на 'nmake' в приведенных здесь инструкциях.

Этот раздел описывает конфигурирование Template Toolkit с помощью программы Makefile.PL. Если вы уже успешно запустили ее и у вас не возникло проблем с ответами на вопросы, вы можете пропустить чтение этого раздела.

Программа Makefile.PL выполняет конфигурирование модуля и создает Makefile, который затем используется при сборке, тестировании и установке Template Toolkit.

    perl Makefile.PL

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

    Do you want to run the DBI tests? .
    It requires access to an existing test database. [y]

    Хотите ли вы провести тесты DBI?
    Это требует доступа к существующей тестовой базе данных. [y]

Если вы ответите 'y' программа спросит вас о драйвере DBD и параметрах источника данных (имя, пользователь, пароль), требующихся для соединения с подходящей базой. Убедитесь, что сервер баз данных запущен и указанная вами база существует, перед тем как запустить 'make test' (в противном случае, тест t/dbi.t будет выполнен с ошибкой).

Сейчас Template Toolkit может похвастаться высокоскорстной реализацией модуля Template::Stash, написанной на XS. Вы можете собрать этот опциональный модуль для использования в качестве альтернативы к обычному модулю, написанному на чистом perl. Кроме того, вы можете установить XS Stash модулем по умолчанию, что обычно ускоряет Template Toolkit в два раза!

Ответьте 'y' или 'n' на вопросы: собирать ли модуль XS Stash, и дополнительно, использовать ли его по умолчанию:

    Do you want to build the XS Stash module? [y]
    Do you want to use the XS Stash for all Templates? [n]

    Хотите ли вы собрать модуль XS Stash? [y]
    Хотите ли вы использовать XS Stash для всех шаблонов? [n]

Новый, появившийся в версии 2.03, фильтр latex позволяет вам генерировать файлы PostScript, PDF или DVI прямо из исходных шаблонов LaTeX. Он зависит от 3 внешних программ, которые скрипт Makefile.PL попытается найти. Вас спросят разрешить или нет фильтр latex:

    TT2 supports PDF, DVI and PostScript output using the latex
    filter, implemented with the programs pdflatex, latex and dvips.

    Because the latex filter runs latex and pdflatex, template authors
    could use this feature to include any arbitrary file in their
    latex input, or also open an arbitrary output file, independent of
    the ABSOLUTE or RELATIVE configuration settings. This might create
    a security concern at your site. If you don't trust your template
    authors then don't enable the latex filter.

   I found the following locations for pdflatex, latex and dvips:
     + pdflatex => /usr/bin/pdflatex
     + latex    => /usr/bin/latex
     + dvips    => /usr/bin/dvips

   Do you want to enable the latex filter? [y]
   Are the pdflatex, latex and dvips paths ok? [y]

    TT2 поддерживает вывод PDF, DVI и PostScript с помощью фильтра
    latex, реализованного с помощью программ pdflatex, latex и dvips.

    Поскольку фильтр latex запускает latex и pdflatex, авторы шаблонов
    могут использовать эту возможность, чтобы включить любой файл в вывод
    latex, или открыть любой файл для вывода, независимо от установки
    опций конфигурации ABSOLUTE или RELATIVE. Это может создать угрозу
    безопасности вашего сайта. Если вы не доверяете авторам шаблонов, не
    разрешайте фильтр latex.

   Я нашел pdflatex, latex и dvips по таким путям:
     + pdflatex => /usr/bin/pdflatex
     + latex    => /usr/bin/latex
     + dvips    => /usr/bin/dvips

   Хотите ли вы разрешить фильтр latex? [y]
   Правильно ли указаны пути к pdflatex, latex и dvips? [y]

В дополнение к Perl модулям и POD документации, устанавливаемой обычным способом, Template Toolkit также содержит ряд дополнительных компонентов.

   * Template libaries for basic HTML, Pod -> HTML, and PostScript

   * Splash! - a stylish HTML user interface template library / widget set

   * HTML documentation - distributed in template form for customisation

   * Stylesheet templates to generate docs as vanilla HTML or using Splash!

   * Examples - numerous examples of using the template libraries

   * Библиотеки шаблонов для базового HTML, Pod -> HTML, и PostScript

   * Splash! - библиотека со стильным HTML-интерфейсом / набор примитивов

   * HTML документация - поставляется в виде шаблонов для возможности настройки

   * Шаблоны таблиц стилей для генерации опрятных HTML документов или использования Splash!

   * Примеры - многочисленные примеры использования библиотек шаблонов

Makefile.PL спросит, хотите ли вы установить эти компоненты.

    Do you want to install these components? [y]

    Хотите ли вы установить эти компоненты? [y]

Если вы ответите 'y', вас попросят указать каталог для установки. Этот каталог должен быть отделен от установочных каталогов Perl. Если вы используете Unix или Win32, вам предложат разумные значения по умолчанию. Предложения правильных значений для других платформ приветствуются.

Unix:

    Installation directory [/usr/local/tt2]

    Установочный каталог [/usr/local/tt2]

Win32:

    Installation directory [C:/Program Files/Template Toolkit 2]

    Установочный каталог [C:/Program Files/Template Toolkit 2]

Библиотека шаблонов Splash! использует ряд очень маленьких картинок для сборки компонентов интерфейса. Они будут установлены (когда вы запустите "make install") в каталог 'images' относительно корневого каталога установки, определенного выше. Если вы захотите использовать библиотеку Splash!, вам потребуется скопировать этот каталог картинок, определить для него алиас (например, в httpd.conf) или создать символическую ссылку на него, чтоб веб-сервер мог найти и использовать картинки из него. Раздел 'УСТАНОВКА' ниже содержит дальнейшие разъяснения, что для этого нужно сделать, но сейчас необходимо просто указать какой URL вы планируете использовать.

    URL base for TT2 images? [/tt2/images]

    Базовый URL для картинок TT2? [/tt2/images]

Если вы устанавливаете на Windows платформе, значение по умолчанию будет основано на указанном выше каталоге установки. Это позволит вам смотреть документацию и любые другие созданные вами файлы Splash! через броузер с использованием файловой системы для доступа к картинкам. Например,

    URL base for TT2 images? [C:/Program Files/Template Toolkit 2/images]

    Базовый URL для картинок TT2? [C:/Program Files/Template Toolkit 2/images]

На других платформах, подразумевается, что картинки будут отдаваться веб-сервером и значением по умолчанию будет '/tt2/images'. Другие типичные значения для этого параметра '/images/tt2', '/~yourid/tt2/images' или даже что-то вроде 'http://www.yourhost.org/images/tt2'. Если у вас нет идей, лучше принять значение по умолчанию и позаботиться об этом позже, после того как вы перейдете к разделу 'УСТАНОВКА'. Если вы не планируете использовать библиотеку Splash!, то вам вообще не нужно об этом беспокоится. Вы можете принять значение по умолчанию, или написать какую-нибудь глупость, чтобы немного оживить последующий скучный процесс.

Модули, составляющие Template Toolkit, содержат полную POD документацию, которую можно просматривать с помощью 'perldoc' или 'man' (если ваша система поддерживает эту команду). Эта документация устанавливается как обычная Perl-часть Template Toolkit.

Пакет также включает набор исходных шаблонов и элементов стиля для генерации этой же документации в формате HTML. Она будет установлена в каталог 'docs' относительно корневого установочного каталога, указанного выше.

HTML документация может быть построена во время выполнения "make install" в простом HTML формате или с использованием библиотеки Splash!. Можно посмотреть примеры различных стилей и документацию на http://www.template-toolkit.org/docs/.

Чтобы построить HTML документацию в процессе установки, ответьте 'y' на вопрос:

    Do you want to build the HTML documentation? [y]

    Хотите собрать HTML документацию? [y]

и затем уточните, хотите вы использовать опрятный стиль HTML (ответ: 'n') или использовать библиотеку Splash! (ответ: 'y'). Последняя рекомендуется для тех, кто любит приятно оформленные веб-страницы, но если вы отвечаете 'y' и выбираете Splash!, вы должны обеспечить правильную установку описанного выше URL картинок.

    Do you want to use the Splash! library? [y]

    Хотите использовать библиотеку Splash!? [y]

Если вы предпочитаете чистые и простые страницы и/или не хотите беспокоится о конфигурировании каталогов картинок, тогда выбирайте 'n', чтобы сгенерировать документы в простом стиле. Это приведет к генерации чистой текстовой HTML версии, полностью свободной от графики и содержащей только текстовые навигационные ссылки.

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

    Which Splash! colour scheme would you like to use to build the
    documentation?  Acceptable values are:

      Name     Colours
      -------------------------
      default  lilac/mauve
      aqua     aqua/marine
      blue     grey75/blue75
      green    grey75/green75
      grey     grey75/grey50
      red      grey75/red75

    Enter name of Splash scheme:  [default]

    Какую цветовую схему Splash! вы хотите использовать при сборке
    документации?  Допустимые значения:

      Название Цвета
      -------------------------
      default  lilac/mauve
      aqua     aqua/marine
      blue     grey75/blue75
      green    grey75/green75
      grey     grey75/grey50
      red      grey75/red75

    Укажите имя Splash схемы:  [default]

Примеры различных цветовых схем можно посмотреть на сайте Template Toolkit: http://www.template-toolkit.org/docs/.

Как собрать HTML документацию вручную и/или подогнать шаблоны под ваши собственные требования, можно прочитать в файле README в каталоге 'docs'.

Последний дополнительный компонент - набор примеров, показывающих использование билиотек шаблонов HTML, Splash! и PostScript. Они устанавливаются в каталог 'examples' внутри установочного каталога и также могут быть автоматически построены при выполнении "make install".

    Do you want to build the HTML example pages? [y]

    Хотите построить примеры HTML страниц? [y]

Учтите, что примеры используют библиотеку Splash! и в настоящий момент вресии, использующей обычный HTML, нет. В этом нет смысла, поскольку примеры в основном описывают Splash! и другой "продвинутый" HTML инструментарий. Имейте в виду, что примеры PostScript далеки от завершения (на самом деле только появились).

В этом разделе описываются команды "make" и "make test", которые собирают и тестируют Template Toolkit. Если вы при их запуске у вас не возникло проблем, этот раздел можно пропустить.

Команда 'make' собирает модули Template Toolkit обычным способом.

    make

Команда 'make test' запускает тестовые скрипты в подкаталоге 't'. Известна по крайней мере одна ошибка, возникающая при определенных условиях:

  * The Text::Autoformat plugin may fail on tests 23 and 25 with
    versions of Perl prior to 5.6.0 when using a locale which has a
    decimal separator other than '.'.

  * Плагин Text::Autoformat может завершить неудачно тесты 23 и 25 на
    версиях Perl ниже 5.6.0 при использовании локали, которая использует
    десятичную точку, отличную от '.'.

Можно установить флаг TEST_VERBOSE при запуске 'make test', чтобы посмотреть результаты каждого теста:

    make test TEST_VERBOSE=1

Раздел описывает заключительную часть установки Template Toolkit с помощью команды "make install" и дополнительные шаги, которые могут понадобиться, если вы дополнительно собрали HTML документацию и/или примеры.

'make install' установит модули и скрипты на вашу систему. Вам могут понадобится права администратора, чтобы это сделать. Альтернативно можно установить Template Toolkit в локальный каталог (смотри описание ExtUtils::MakeMaker), например:

    perl Makefile.PL PREFIX=/home/abw/

Если вы это сделаете не забудьте обновить переменную окружения PERL5LIB, или добавить в ваш скрипт строчку, чтобы Perl знал где искать файлы, например:

    use lib qw( /home/abw/lib/perl5/site_perl/5.6.0 );

Если вы выбрали дополнительные компоненты, они также будут установлены при выполнении "make install". Они устанавливаются в отдельный каталог Template Toolkit (независимую от расположения Perl), указанный при конфигурировании. Учтите, что у вас должны быть права для создания и/или записи в этот каталог. Если вы запускаете "make install" как администратор или другой привилегированный пользователь, каталог будет создан (если он не существует) и все файлы будут установлены в него. Владельцем файлов будет пользователь от которого производилась установка.

Если вы хотите использовать библиотеку шаблонов Splash!, вам нужно убедиться, что базовый URL картинок, указанный при конфигурировании правильно связан с подкаталогом 'images' в установочном каталоге. Если вы собрали HTML документацию, вам нужно также сделать ее доступной через веб-сервер.

Если вы устанавливаете пакет на Win32 и выбрали значения по умолчанию (смотри выше), то вы уже можете просматривать HTML документацию и примеры через броузер и она будет отображаться правильно. Иначе вам нужно подправить конфигурацию сервера, создать ссылки на файлы или скопировать их в место, где веб-сервер сможет их найти.

Если вы используете Apache вам нужно сделать в httpd.conf примерно такую запись (в секции <IfModule mod_alias.c>, предполагается что установочный каталог - /usr/local/tt2):

    Alias /tt2/images/   /usr/local/tt2/images/
    Alias /tt2/docs/     /usr/local/tt2/docs/html/
    Alias /tt2/examples/ /usr/local/tt2/examples/html/

    <Directory /usr/local/tt2/>
        Options Indexes
        AllowOverride None
        Order allow,deny
        Allow from all
    </Directory>

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

    cd /path/to/your/webserver/docroot
    mkdir tt2
    cd tt2
    ln -s /usr/local/tt2/images images
    ln -s /usr/local/tt2/docs/html docs
    ln -s /usr/local/tt2/examples/html examples

Учтите, что при использовании символических ссылок, веб-сервер должен быть сконфигурирован так, чтобы он мог следовать по ним. Например, в Apache:

    <Location /tt2>
	Options Indexes FollowSymLinks
    </Location>

После этого вы сможете получить доступ к документации Template Toolkit:

    http://www.yourserver.org/tt2/docs/

и к примерам:

    http://www.yourserver.org/tt2/examples/

Если у вас нет доступа к конфигурации веб-сервера или вы не хотите возится с этим, вы всегда можете скопировать все в пользовательский каталог (или создать в нем ссылки, если конфигурация вашего веб-сервера позволяет следовать символическим ссылкам в пользователшьских каталогах). Например:

    mkdir ~/public_html/tt2
    cd ~/public_html/tt2
    cp -R /usr/local/tt2/images .
    cp -R /usr/local/tt2/docs/html docs
    cp -R /usr/local/tt2/example/html examples

После этого они будут доступны (например):

    http://www.yourserver.org/~yourid/tt2/docs/
    http://www.yourserver.org/~yourid/tt2/examples/

И, конечно, значение базового URL картинок Template Toolkit (как должно быть установлено при конфигурировании) будет:

    /~yourid/tt2/images

Примеры и HTML документация (если вы собирали их со Splash!) будут ссылаться на картинки Splash!, используя этот URL (по умолчанию: '/tt2/images'). Если это значение неправильное вместо гладких закругленных уголков, компоненты пользовательского интерфейса будут содержать битые ссылки на картинки, цветные квадратики, или другие жуткие отклонения на страницах.

При необходимости вы можете переустановить Template Toolkit, указав другой URL картинок. Как вариант, можно поправить значение в файле 'templates/splash/config' (в каталоге установки) и перестроить документацию и/или примеры.

Makefile, сгенерированный Makefile.PL, содержит 4 дополнительных задачи: tt2_install, tt2_splash, tt2_html_docs и tt2_examples (но только если вы выбрали соответствующие опции). Они выполняются автоматически при запуске "make install" (можно сделать "make pure_install" или "make doc_install" вместо "make install" чтобы выполнить только установку Perl модулей или обычной документации). Можно также запустить их вручную, если позже вы захотите переустановить дополнительные компоненты, перестроить документацию или примеры:

    make tt2_install
    make tt2_splash
    make tt2_html_docs
    make tt2_examples

Если вам нужна более подробная информация о перестройке HTML и примеров, изучите файлы README в каталогах 'docs' и 'examples'.

Template Toolkit написан Энди Уардли (Andy Wardley <abw@andywardley.com>) при неоценимой помощи и поддержке многих других людей. Более подробно смотри в Template::Manual::Credits

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.