Template Toolkit: Модули: Template::Provider

Template Toolkit

(русская редакция)

[ Пособия ] [ Руководство ] [ Модули ] [ Библиотеки ] [ Утилиты ] [ Вопросы ] [ Релиз ] [ Perl-ресурсы ] Форум ]
 
Поиск
Template Toolkit | Модули | Template::Provider

Template::Provider

[ ◄ Template::Plugins ] [ Template::Service ► ]
Модуль поставщика для загрузки/компиляции шаблонов.

Оглавление

ОБЗОР

Индекс ] [ Модули ] [ Наверх ]

    $provider = Template::Provider->new(\%options);
    ($template, $error) = $provider->fetch($name);

ОПИСАНИЕ

Индекс ] [ Модули ] [ Наверх ]

Template::Provider используется для загрузки, разбора, компиляции и кеширования документов-шаблонов. Этот класс можно наследовать, чтобы обеспечить более специфические возможности для загрузки или, напротив, получить доступ к шаблонам.

Объекты Template::Context поддерживают список объектов Template::Provider, которые по очереди опрашиваются (через fetch()) для получения необходимого шаблона. Каждый поставщик может вернуть скомпилированный шаблон, возбудить исключение или отклонить запрос, дав таким образом возможность выполнить его следующим поставщикам.

Это модель "Цепочка Ответственности" ("Chain of Responsiblity"). Более подробную информацию можно получить в 'Design Patterns'.

Эта документация требует доработки.

ПУБЛИЧНЫЕ МЕТОДЫ

Индекс ] [ Модули ] [ Наверх ]

new(\%options)

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

  • INCLUDE_PATH

    INCLUDE_PATH используется для указания одного или нескольких каталогов, в которых расположены файлы шаблонов. Когда запрашивается шаблон, который не определен локально с помощью директивы BLOCK, каждый из каталогов, определенных в INCLUDE_PATH, просматривается в поисках файла-шаблона. Несколько каталогов можно указать с помощью ссылки на массив или в виде одной строки, в которой каталоги разделены символом ':'.

        my $provider = Template::Provider->new({
            INCLUDE_PATH => '/usr/local/templates',
        });
    
        my $provider = Template::Provider->new({
            INCLUDE_PATH => '/usr/local/templates:/tmp/my/templates',
        });
    
        my $provider = Template::Provider->new({
            INCLUDE_PATH => [ '/usr/local/templates',
                              '/tmp/my/templates' ],
        });

    В системах Win32, используется небольшой дополнительный трюк - игнорируются разделители ':', за которыми сразу следуют символы '/' или '\'. Это позволяет избежать путаницы при использовании каталогов с такими именами 'C:\Blah Blah'.

    При использовании массива для определения каталогов, INCLUDE_PATH может содержать элементы, которые динамически генерируют список каталогов для INCLUDE_PATH. Эти элементы-генераторы можно определить как ссылки на функции или объекты с методом paths().

        my $provider = Template::Provider->new({
            INCLUDE_PATH => [ '/usr/local/templates',
                              \&incpath_generator,
    			  My::IncPath::Generator->new( ... ) ],
        });

    При каждом запросе шаблона и проверке INCLUDE_PATH, будет вызываться функция или метод объекта, которые должны вернуть ссылку на массив с путями к каталогам. При возникновении ошибки функции-генераторы должны вызывать die() с сообщением о причине ошибки. Методы-генераторы в этом случае должны вернуть undef, а причина ошибки должна возвращаться через вызов метода error() объекта.

    Например:

        sub incpath_generator {
    	# ...код...
    
    	if ($all_is_well) {
    	    return \@list_of_directories;
    	}
    	else {
    	    die "cannot generate INCLUDE_PATH...\n";
    	}
        }

    или:

        package My::IncPath::Generator;
        # Template::Base (или Class::Base) предоставляет метод error()
        use Template::Base;
        use base qw( Template::Base );
        sub paths {
    	my $self = shift;
    	# ...код...
            if ($all_is_well) {
    	    return \@list_of_directories;
    	}
    	else {
    	    return $self->error("cannot generate INCLUDE_PATH...\n");
    	}
        }
        1;
  • DELIMITER

    Используется для установки альтернативной последовательности символов, используемой для разделения путей, заданных в INCLUDE_PATH. Значение по умолчанию для DELIMITER - ':'.

        # позволим использовать соглашения файловой системы глупого Билли (Silly Billy)
        my $provider = Template::Provider->new({
    	DELIMITER    => '; ',
            INCLUDE_PATH => 'C:/HERE/NOW; D:/THERE/THEN',
        });
        # решение получше: установите Linux!  :-)

    На системах Win32, разделитель по умолчанию используется немного более разумно, разбивая пути только по символам ':', за которыми нет сразу символа '/'. Это означает, что следующий пример будет работать как и запланировано, разделяя INCLUDE_PATH на 2 каталога C:/foo и C:/bar.

        # только для Win32
        my $provider = Template::Provider->new({
    	INCLUDE_PATH => 'C:/Foo:C:/Bar'
        });

    Тем не менее, при использовании Win32 рекомендуется явно переопределить символ DELIMITER на что-нибудь иное (например, ';'), а не полагаться на этот тонкий трюк.

  • ABSOLUTE

    Флаг ABSOLUTE указывает, можно ли загружать шаблоны с абсолютными путями (например, '/foo/bar'). Опция запрещена по умолчанию и любая попытка загрузить шаблон с таким именем приведет к возбуждению исключения 'file'.

        my $provider = Template::Provider->new({
    	ABSOLUTE => 1,
        });
        # именно поэтому опция запрещена по умолчанию
        [% INSERT /etc/passwd %]

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

        C:/Foo/Bar
  • RELATIVE

    Флаг RELATIVE указывает, можно ли загружать шаблоны с относительными относительно текущего каталога путями (например, './foo/bar' или '../../some/where/else'). Эта опция также запрещена по умолчанию, и в случае обнаружения таких имен файлов шаблонов, будет возбуждено исключение 'file'.

        my $provider = Template::Provider->new({
    	RELATIVE => 1,
        });
        [% INCLUDE ../logs/error.log %]
  • DEFAULT

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

        my $provider = Template::Provider->new({
    	DEFAULT => 'notfound.html',
        });

    Если запрашивается несуществующий шаблон через метод Template process() или через директивы INCLUDE, PROCESS или WRAPPER, то вместо него будет обработан шаблон DEFAULT в случае, если он определен. Имейте в виду, что шаблон DEFAULT не используется, когда шаблоны указаны с абсолютными или относительными путями, или если он определен как указатель на входной файл или текстовая строка.

  • CACHE_SIZE

    Модуль Template::Provider кеширует шаблоны, чтобы избежать повторной компиляции файлов шаблонов или блоков, при их повторном использовании. Опция CACHE_SIZE используется для ограничения числа скомпилированных шаблонов, которые модуль будет кешировать.

    По умолчанию, CACHE_SIZE имеет неопределенное значение и все скомпилированные шаблоны кешируются. Если значение опции положительное число, кеш будет ограничен на хранение не более указанного числа скомпилированных шаблонов. Когда загружается и компилируется новый шаблон, а кеш заполнен (т.е. число элементов == CACHE_SIZE), самый давно не использовавшийся шаблон удаляется, чтобы освободить место для нового.

    Установка CACHE_SIZE в 0 запрещает кеширование.

        my $provider = Template::Provider->new({
    	CACHE_SIZE => 64,   # кешировать только 64 скомпилированных шаблона
        });
        my $provider = Template::Provider->new({
    	CACHE_SIZE => 0,   # не кешировать скомпилированные шаблоны
        });
  • COMPILE_EXT

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

        my $provider = Template::Provider->new({
    	COMPILE_EXT => '.ttc',
        });

    Если COMPILE_EXT определена (а COMPILE_DIR нет, смотри ниже), то скомпилированные шаблоны с расширением COMPILE_EXT будут записываться в каталог, из которого исходный файл шаблона был загружен.

    Компиляция и последующее повторное использование шаблонов происходит автоматически всякий раз, когда установлены опции COMPILE_EXT или COMPILE_DIR. Template Toolkit автоматически загрузит и использует скомпилированные файлы, если найдет их на диске. Если соответствующий исходный файл был изменен после того как он был скомпилирован и сохранен, Template Toolkit загрузит и перекомпилирует исходник и сохранит новую версию на диск.

    Эта форма постоянного кеша дает значительную экономию времени и ресурсов, необходимых для перезагрузки шаблона. Скомпилированные шаблоны могут быть перезагружены посредством простого вызова require(), освобождая Perl от разбора и компиляции. Это Правильная Вещь.

  • COMPILE_DIR

    Опция COMPILE_DIR используется для определения альтернативного корня каталогов, в которых будут сохраняться скомпилированные шаблоны.

        my $provider = Template::Provider->new({
    	COMPILE_DIR => '/tmp/ttc',
        });

    Опция COMPILE_EXT также может быть использована для явного определения расширения, которое будет добавляться к этим файлам.

        my $provider1 = Template::Provider->new({
    	COMPILE_DIR => '/tmp/ttc',
    	COMPILE_EXT => '.ttc1',
        });
        my $provider2 = Template::Provider->new({
    	COMPILE_DIR => '/tmp/ttc',
    	COMPILE_EXT => '.ttc2',
        });

    Когда COMPILE_EXT не определена, файлы скомпилированных шаблонов сохраняются с исходными именами файлов, но в другом дереве каталогов.

    Путь каждого каталога из INCLUDE_PATH полностью воспроизводится внутри каталога COMPILE_DIR. Этот пример:

        my $provider = Template::Provider->new({
    	COMPILE_DIR  => '/tmp/ttc',
    	INCLUDE_PATH => '/home/abw/templates:/usr/share/templates',
        });

    приведет к созданию следующей структуры каталогов:

        /tmp/ttc/home/abw/templates/
        /tmp/ttc/usr/share/templates/

    Скомпилированные шаблоны файлов, загруженные из различных каталогов INCLUDE_PATH, будут сохранены в соответствующих каталогах в COMPILE_DIR.

    На платформах Win32 имя файла может начинаться с имени устройства и двоеточия. Например,

        C:/My Templates/header

    Двоеточие будет молча вырезано из имени файла при добавлении к значению COMPILE_DIR, чтобы предотвратить использование неправильных имен файлов. Двоеточия в элементах COMPILE_DIR останутся без изменений. Например:

        # только в Win32
        my $provider = Template::Provider->new({
    	DELIMITER    => ';',
    	COMPILE_DIR  => 'C:/TT2/Cache',
    	INCLUDE_PATH => 'C:/TT2/Templates;D:/My Templates',
        });

    Это приведет к созданию следующих каталогов кеша:

        C:/TT2/Cache/C/TT2/Templates
        C:/TT2/Cache/D/My Templates
  • TOLERANT

    Флаг TOLERANT используется различными модулями-поставщиками Template Toolkit (Template::Provider, Template::Plugins, Template::Filters) для управления их поведением при возникновении ошибок. По умолчанию, о любых ошибках как таковых генерируется отчет, с одновременным запретом доступа к их источнику (шаблон, плагин, фильтр) и возбуждением исключения. Когда флаг TOLERANT установлен в любое истинное значение, ошибки будут без уведомления игнорироваться, а поставщик вместо этого вернет отказ от обслуживания (STATUS_DECLINED). Это позволяет вместо неудачного завершения после запроса поставщику, передать ответственность за предоставление источника следующему поставщику. Если все поставщики отклонят запрос на обслуживание либо по причине возникновения ошибки, либо из-за невозможности его выполнить, возбуждается исключение ' not found'.

  • PARSER

    Модуль Template::Parser реализует объект парсера для компиляции шаблонов в perl-код, который затем может быть выполнен. Объект этого класса по умолчанию создается автоматически и затем используется объектом Template::Provider, как только шаблон загружен и требует компиляции. Опция PARSER используется для указания ссылки на объект альтернативного парсера.

        my $provider = Template::Provider->new({
    	PARSER => MyOrg::Template::Parser->new({ ... }),
        });
  • DEBUG

    Опцию DEBUG можно использовать, чтобы включить отладочные сообщения модуля Template::Provider, установкой (дополнением) этого флага значением DEBUG_PROVIDER.

        use Template::Constants qw( :debug );
        my $template = Template->new({
    	DEBUG => DEBUG_PROVIDER,
        });

fetch($name)

Возвращает скомпилированный шаблон для указанного имени. Если шаблон не найден возвращается (undef, STATUS_DECLINED). Если при чтении или разборе шаблона происходит ошибка возвращается ($error, STATUS_ERROR), где $error содержит сгенерированное сообщение об ошибке. Если установлен флаг TOLERANT метод вместо ошибки возвращает (undef, STATUS_DECLINED).

store($name, $template)

Сохраняет скомпилированный шаблон $template в кеше под именем $name. При последующих вызовах fetch($name) будет возвратит этот шаблон вместо файла с диска.

include_path(\@newpath))

Метод доступа к опции INCLUDE_PATH. Если метод вызывается с параметром, то существующее значение INCLUDE_PATH будет заменено на новое.

paths()

Этот метод генерирует копию списка INCLUDE_PATH. Любые элементы списка, являющиеся динамическими генераторомами (например, ссылками на функции или объекты с методом paths()) будут вызваны, и возвращенный ими список каталогов будет включен в результирующий список.

Существует возможность передать генератор, который возвращает самого себя, что приводит к зацикливанию внутри метода. Чтобы обнаружить и предотвратить это, введена переменная пакета '$MAX_DIRS', установленная по умолчанию в 64, которая ограничивает максимально возможное количество путей, которые можно добавить или сгенерировать в результирующий список. Если это число будет превышено, метод немедленно возвращает ошибку с соответствующим сообщением.

АВТОР

Индекс ] [ Модули ] [ Наверх ]

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

http://www.andywardley.com/

ВЕРСИЯ

Индекс ] [ Модули ] [ Наверх ]

2.81, поставляется в составе 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.

СМОТРИ ТАКЖЕ

Индекс ] [ Модули ] [ Наверх ]