Инструменты пользователя

Инструменты сайта


limb3:ru:packages:macro:how_to_create_new_filter

Создание собственных {{macro}} фильтров

Файл вашего нового класса должен быть расположен в одной из директорий вида src/macro и иметь имя some_filter_name.filter.php. Обратите внимание на окончание .filter.php.

В качестве безовых классов можно использовать 2 класса:

  • lmbMacroFunctionBasedFilter - используется для реализации страндартных php-функций или любых других функции в виде MACRO-фильтров. Примеры: html, nl2br и другие фильтры. В простейшем случае необходимо только отнаследоваться от класса и указать php-функцию.
  • lmbMacroFilter - более базовый класс, используется в сложных случаях.

Аннотации фильтров

В заголовке любого фильтра находятся его аннотации, например:

<?php 
/**
 * @filter number_format
 * @aliases number
 */ 
class lmbMacroNumberFormatFilter extends lmbMacrounctionBasedFilter
{
  [..]
}  

Это так называемые аннотации. По этим аннотациям словарь фильтров формирует свое содержимое. Подробнее о словарях в разделе "Словари элементов MACRO-шаблона".

Полный список аннотация для фильтров:

  • filter - название фильтра, которое используется в шаблоне.
  • aliases - другие названия фильтра, которые также могут используется в шаблоне. Разделяются запятой

Создание фильтра для php-функции или другой функции

Рассмотрим пример простого фильтра, выполняющего операцию заключения строки в кавычки. В шаблоне мы предполагаем использовать синтаксис {$var|quote}.

Пример шаблона:

{$title|quote}

Назовем нам фильтр QuoteFilter. Этот случай - типичный для использования lmbMacroFunctionBasedFilter в качестве базы. Код фильтры будет выглядеть следующим образом:

<?php 
/**
 * @filter quote
 */ 
class QuoteFilter extends lmbMacroFunctionBasedFilter
{
  protected $function = 'quote';
}  
?>

(Здесь и далее мы подразумеваем, что функция quote($string) уже определена)

MACRO компилирует {$title|quote} в следующий код:

quote($title);

Если фильтр содержит параметры, то lmbMacroFunctionBasedFilter автоматически их будет добавлять в том же порядке в генерируемый код, например, MACRO компилирует {$my_number|number_format:2,$del} в следующий код:

number_format($title, 2, $del);

Используемая функция, ествественно, должна быть определена. Если это не стандартная php-функция, тогда подключение нужного файла можно сделать при помощи атрибута $include_file:

<?php 
/**
 * @filter quote
 */ 
class QuoteFilter extends lmbMacroFunctionBasedFilter
{
  protected $function = 'quote';
  protected $include_file = '/path/to/quote_function_declaration.php';
}  
?>

Создание более сложного фильтра

Любой фильтр содержит ссылку на так называемую базу $base. $base - это обычно объект класса lmbMacroExpressionNode или другой фильтр, в случае, если к выражению применены несколько фильтров.

База, впрочем как и фильтры поддерживают следующий набор методов:

  • getValue() - возвращает косок кода, который именно должен быть вставлен в откомпилированный php-шаблон. В MACRO, в отличие от WACT-а нет различия между динамическими и статическими данными. Поэтому используется только getValue().
  • preGenerate($code_writer) - генерит код, необходимый для так называемой прегенерации базы. Например это нужно чтобы при применении фильтра к выражению {$author.title|html} фильтр html применился именно к полю title. Прегенерацией будет в данном случае получение какой-то временной переменной, которая будет хранить значение поля title.

Рассмотрим код фильтра date, который можно найти в файлe limb/macro/src/filters/core/date.filter.php. Несмотря на то, что это обычная php-функция, но первым параметром это функции указывается форма данных, а не сама дата, поэтому мы не могли применить lmbMacroFunctionBasedFilter в данном случае. Поэтому мы создали наследника от lmbMacroFilter:

/**
 * class lmbMacroDateFilter.
 *
 * @filter date
 * @package macro
 * @version $Id$
 */ 
class lmbMacroDateFilter extends lmbMacroFilter
{
  function getValue()
  {
    return 'date(' . $this->params[0].', ' . $this->base->getValue() . ')';
  }  
} 

Параметры фильтра

Фильтры могут принимать дополнительный параметры, которые в шаблоне следуют за названием фильтра и знака двоеточия, например, {$var|trim:«&»}. Параметры доступны в классе фильтра в виде атрибута $params. Параметры не имеют имен, поэтому приходится их получать по индексу.

Параметры хранятся как есть, то есть для случая {$var|trim:«&»}, $this→params[0] будет хранить именно, «&», то есть строку с кавычками. Поэтому при генерации параметров в шаблон не нужно их дополнительно как-то экранировать.

Обсуждение

Ваш комментарий. Вики-синтаксис разрешён:
   __  ___   _  __  _      __ __  __   ___ 
  /  |/  /  / |/ / | | /| / / \ \/ /  / _ \
 / /|_/ /  /    /  | |/ |/ /   \  /  / , _/
/_/  /_/  /_/|_/   |__/|__/    /_/  /_/|_|
 
limb3/ru/packages/macro/how_to_create_new_filter.txt · Последние изменения: 2010/11/10 10:02 (внешнее изменение)