====== "Шаблонные команды" ======

===== Краткое описание =====

Термин "шаблонные команды" пока взят в кавычки, так как это рабочее название, окончальный термин еще не определен. 

Суть использования шаблонных команд следующая:
  * инициализировать объект, который является потомком класса WactTemplateCommand, прямо в шаблоне
  * вызвать у этого объекта какой-либо метод (по-умолчанию этот метод называется doPerform, что обеспечивает аналогию с шаблоном Command).

Объект, наследник от **WactTemplateCommand**, и который был вызван, имеет доступ к корневому активному компоненту шаблона, к активному компоненту, из которого был сделан вызов, а также все, что можно получить при помощи глобальных источников, например, lmbToolkit. Это открывает весьма широкий простор для изменения содержимого шаблона. Например, можно изменить количество элементов в каком-либо pager-е, можно поместить в корневой контейнер данных шаблона какие-либо данные(см. пример ниже) и т.д.

Для реализации такого вызова используется тег [[limb3:ru:packages:wact:tags:perform_tags:perform_tag|<perform>]], а также дополнительный тег [[limb3:ru:packages:wact:tags:perform_tags:perform_params_tag|<perform:params>]], который позволяет передать в вызываемый метод дополнительные параметры.

Класс WactTemplateCommand находится в папке limb/wact/src/components/perform.

===== Использование тега <perform> =====

Разберем небольшой пример, в котором мы будем ставить в контейнеры данных шаблона данные. Пример несколько абстрактный, но должен продемонстрировать основные моменты использования шаблонных команд.


==== Класс шаблонной команды ====

Итак, нам нужна "шаблонная команда". Это должен быть класс, дочерний от класса WactTemplateCommand, который находится в limb/wact/src/components/WactTemplateCommand.class.php

Внутри WactTemplateCommand доступны атрибуты:
  * **$template** - ссылка на корневой активный компонент.
  * **$context_component** - ссылка на активный компонент, из которого делается вызов шаблонной команды.

Как мы уже говорили, по-умолчанию вызывается метод doPerform(), поэтому для начала мы реализуем именно его. Этот метод будет устанавливать в корневой контейнер данных и в текущий контейнер данных значения некоторых переменных.

<code php>
lmb_require('limb/wact/src/components/perform/WactTemplateCommand.class.php');

class MyTemplateCommand extends WactTemplateCommand
{
  function doPerform()
  {
    $this->template->set('my_var', 'This was set from template command object');
    $this->context_component->getDatasourceComponent()->set('my_other_var', 'This was also set from template command object');
  }
}
</code>

Обратите внимание, template - это корневой активной компоонент, который является корневым контейнером данных. Поэтому у него безопасно вызывать метод set(). context_component - может быть любым активным компонентом, и не являться контейнером данных, поэтому мы использовали метод getDatasourceComponent(), который возвращает ближайший контейнер данных вверх по иерархии.

Допустим, мы сохраним наш класс в пути, где он будет доступен через include_path(), например, так src/template/command/MyTemplateCommand.class.php.

Теперь можно попробовать вызвать метод MyTemplateCommand :: doPerform() из шаблона при помощи тега <perform>:

<code php>
<core:datasource>
<perform command='src/template/command/MyTemplateCommand'/>
{$#my_var}<br/>
{$my_other_var}
</core:datasource>
</code>

В результате получим:
<code>
This was set from template command object<br/>
This was also set from template command object
</code>

==== Вызов произвольного метода ====

При помощи атрибута **method** тега <perform> можно указать другой метод вызываемой шаблонной команды. Значение атрибута **method** приводится к виду doMethodValue(), например: <perform method='my_method'> приведет к вызову метода doMyMethod() в шаблонной команде.

==== Передача параметров в вызываемый метод. Тег <perform:params> ====

Методы шаблонных команд могут принимать произвольное количество параметров. 

При помощи тега <perform:params> можно передать им эти параметры прямо из шаблона. 

Например, путь у нас будет метод MyTemplateCommand :: doOtherPerform() который будет принимать 2 дополнительных параметра, значения которых он и будет ставить в шаблон:

<code php>
lmb_require('limb/wact/src/components/perform/WactTemplateCommandclass.php');

class MyTemplateCommand extends WactTemplateCommandclass
{
  [...]
  function doOtherPerform($param1, $param2)
  {
    $this->template->set('my_var', $param1);
    $this->context_component->getDatasourceComponent->set('my_other_var', $param2);
  }
}
</code>

В вызываемый метод передаются значения атрибутов тега <perform:params> в том порядке, в котором они указаны в шаблоне. Названия атрибутов не имеют значения:

<code xml>
<core:datasource>
<perform command='src/template/command/MyTemplateCommand' method='other_perform'>
  <perform:params p1='For root datasource' p2='For current datasource'/>
</perform>
{$#my_var}<br/>
{$my_other_var}
</core:datasource>
</code>

В результате получим:
<code>
For root datasource<br/>
For current datasource
</code>