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

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

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

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

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

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

Это так называемые аннотации. По этим аннотациям словарь фильтров формирует свое содержимое. Подробнее о словарях в разделе [[limb3:ru:packages:macro:dictionaries|"Словари элементов MACRO-шаблона"]].

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

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

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

Пример шаблона:
<code xml>
{$title|quote}
</code>

Назовем нам фильтр QuoteFilter. Этот случай - типичный для использования lmbMacroFunctionBasedFilter в качестве базы. Код фильтры будет выглядеть следующим образом:
<code php>
<?php 
/**
 * @filter quote
 */ 
class QuoteFilter extends lmbMacroFunctionBasedFilter
{
  protected $function = 'quote';
}  
?>
</code>

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

MACRO компилирует {$title|quote} в следующий код:
<code php>
quote($title);
</code>

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

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

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

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

Любой фильтр содержит ссылку на так называемую базу **$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:

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

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

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

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