documentation/manual/ru/module_specs/Zend_Controller-ActionHelpers.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.controller.actionhelpers" xmlns:xi="http://www.w3.org/2001/XInclude">
   4     <title>Помощники действий</title>
   5
   6     <sect2 id="zend.controller.actionhelper.introduction">
   7         <title>Введение</title>
   8         <para>
   9             Помощники действий (action helpers) дают разработчикам возможность
  10             добавлять функционал во время выполнения или по требованию в любые
  11             контроллеры действий, которые наследуют от
  12             <classname>Zend_Controller_Action</classname>.
  13             Помощники действий помогают снизить необходимость в наследовании от
  14             абстрактного контроллера действий при добавлении общего
  15             функционала в контроллер действий.
  16         </para>
  17
  18         <para>
  19             Есть несколько вариантов использования помощников действий.
  20             Помощники действий используют брокерскую систему (brokerage system),
  21             подобную той, которая используется в
  22             <link linkend="zend.view.helpers">Zend_View_Helper</link> и
  23             <link linkend="zend.controller.plugins">Zend_Controller_Plugin</link>.
  24             Помощники действий (как и <classname>Zend_View_Helper</classname>) могут быть
  25             загружены и вызваны по требованию, либо инстанцироваться во время
  26             запроса (начальной загрузки) или создания контроллера действий
  27             (init()). Для того, чтобы лучше разобраться с этим, см. ниже раздел
  28             по использованию.
  29         </para>
  30     </sect2>
  31
  32     <sect2 id="zend.controller.actionhelper.initialization">
  33         <title>Инициализация помощника</title>
  34
  35         <para>
  36             Помощник может быть инициализирован несколькими различными
  37             способами, выбор способа зависит от ваших нужд и от
  38             функционала, предоставляемого этим помощником.
  39         </para>
  40
  41         <para>
  42             Брокер помощников хранится как член <varname>$_helper</varname> класса
  43             <classname>Zend_Controller_Action</classname>; используйте брокер для
  44             получения или вызова помощников. Методы для этого включают в себя:
  45         </para>
  46
  47         <itemizedlist>
  48             <listitem>
  49                 <para>
  50                     Явное использование метода <code>getHelper()</code>. Просто
  51                     передайте ему имя, и будет возвращен объект помощника:
  52                 </para>
  53
  54                 <programlisting language="php"><![CDATA[
  55 $flashMessenger = $this->_helper->getHelper('FlashMessenger');
  56 $flashMessenger->addMessage('We did something in the last request');
  57 ]]></programlisting>
  58             </listitem>
  59
  60             <listitem>
  61                 <para>
  62                     Используйте функционал "волшебного" метода
  63                     <code>__get()</code> брокера помощников - извлекайте
  64                     помощника так же, как если бы он был свойством этого брокера:
  65                 </para>
  66
  67                 <programlisting language="php"><![CDATA[
  68 $flashMessenger = $this->_helper->FlashMessenger;
  69 $flashMessenger->addMessage('We did something in the last request');
  70 ]]></programlisting>
  71             </listitem>
  72
  73             <listitem>
  74                 <para>
  75                     И наконец, большинство помощников действий реализует метод
  76                     <code>direct()</code>, который будет вызывать особый,
  77                     используемый по умолчанию метод в помощнике. Например, в
  78                     случае <code>FlashMessenger</code> будет вызван метод
  79                     <code>addMessage()</code>:
  80                 </para>
  81
  82                 <programlisting language="php"><![CDATA[
  83 $this->_helper->FlashMessenger('We did something in the last request');
  84 ]]></programlisting>
  85             </listitem>
  86         </itemizedlist>
  87
  88         <note>
  89             <para>
  90                 Все примеры выше функционально эквивалентны.
  91             </para>
  92         </note>
  93
  94         <para>
  95             Вы можете также явно инстанцировать помощников. Вы можете захотеть
  96             сделать это, если используете помощника вне контроллера действий,
  97             или если хотите передавать помощника брокеру для использования в
  98             любых действиях. Инстанцирование производится так же, как и для
  99             любого другого класса PHP.
 100         </para>
 101     </sect2>
 102
 103     <sect2 id="zend.controller.actionhelper.broker">
 104         <title>Брокер помощников</title>
 105
 106         <para>
 107             <classname>Zend_Controller_Action_HelperBroker</classname> управляет
 108             регистрацией объектов помощников и путей к помощникам, а также
 109             извлечением помощников по требованию.
 110         </para>
 111
 112         <para>
 113             Для того, чтобы зарегистрировать помощника через брокер, используйте
 114             <code>addHelper</code>:
 115         </para>
 116
 117         <programlisting language="php"><![CDATA[
 118 Zend_Controller_Action_HelperBroker::addHelper($helper);
 119 ]]></programlisting>
 120
 121         <para>
 122             Само собой, инстанцирование и передача помощников брокеру отнимают
 123             некоторое время и ресурсы, поэтому существуют два метода для
 124             некоторой автоматизации: <code>addPrefix()</code> и
 125             <code>addPath()</code>.
 126         </para>
 127
 128         <itemizedlist>
 129             <listitem>
 130                 <para>
 131                     <code>addPrefix()</code> принимает префикс класса и
 132                     использует его для определения пути, по которому определен
 133                     класс помощника. Подразумевается, что префикс следует
 134                     соглашениям по именованию классов Zend Framework-а.
 135                 </para>
 136
 137                 <programlisting language="php"><![CDATA[
 138 // Добавление помощников, начинающихся
 139 // с My_Action_Helpers в My/Action/Helpers/
 140 Zend_Controller_Action_HelperBroker::addPrefix('My_Action_Helpers');
 141 ]]></programlisting>
 142             </listitem>
 143
 144             <listitem>
 145                 <para>
 146                     <code>addPath()</code> принимает директорию в качестве
 147                     первого аргумента и префикс класса в качестве второго (по
 148                     умолчанию это 'Zend_Controller_Action_Helper'). Это
 149                     позволяет поставить в соответствие определенным
 150                     директориям собственные префиксы классов.
 151                 </para>
 152
 153                 <programlisting language="php"><![CDATA[
 154 // Добавление помощников, начинающихся с Helper в Plugins/Helpers/
 155 Zend_Controller_Action_HelperBroker::addPath('./Plugins/Helpers',
 156                                              'Helper');
 157 ]]></programlisting>
 158             </listitem>
 159         </itemizedlist>
 160
 161         <para>
 162             Поскольку эти методы статические, то они могут вызываться из любого
 163             места в цепочке контроллеров для динамического добавления
 164             помощников при необходимости.
 165         </para>
 166
 167         <para>
 168             Внутри себя брокер помощников использует <link
 169                 linkend="zend.loader.pluginloader">экземпляр PluginLoader</link>
 170             для поддержки путей. Вы можете извлечь PluginLoader, используя
 171             статический метод <code>getPluginLoader()</code>, или
 172             добавить свой экземпляр PluginLoader, используя
 173             <code>setPluginLoader()</code>.
 174         </para>
 175
 176         <para>
 177             Для определения того, есть ли помощник в брокере, используйте
 178             <code>hasHelper($name)</code>, где <varname>$name</varname> - короткое
 179             имя помощника без префикса:
 180         </para>
 181
 182         <programlisting language="php"><![CDATA[
 183 // Проверка, зарегистрирован ли помощник 'redirector' в брокере:
 184 if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
 185     echo 'Redirector helper registered';
 186 }
 187 ]]></programlisting>
 188
 189         <para>
 190             Есть также два статических метода для извлечения помощников из
 191             брокера помощников: <code>getExistingHelper()</code> и
 192             <code>getStaticHelper()</code>. <code>getExistingHelper()</code>
 193             будет извлекать помощника только если он был ранее вызван или явно
 194             зарегистрирован через брокер помощников, иначе бросается исключение.
 195             <code>getStaticHelper()</code> делает то же самое, что и
 196             <code>getExistingHelper()</code>, за тем исключением, что будет
 197             пытаться инстанцировать помощника, если он еще не был
 198             зарегистрирован в стеке помощников. <code>getStaticHelper()</code>
 199             является хорошим выбором, если нужно извлечь помощника для конфигурирования.
 200         </para>
 201
 202         <para>
 203             Оба метода принимают единственный аргумент, <varname>$name</varname>,
 204             который является коротким именем помощника (без префикса).
 205         </para>
 206
 207         <programlisting language="php"><![CDATA[
 208 // Проверка, зарегистрирован ли помощник 'redirector' в брокере,
 209 // и его извлечение:
 210 if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
 211     $redirector =
 212         Zend_Controller_Action_HelperBroker::getExistingHelper('redirector');
 213 }
 214
 215 // Или просто извлеките его, не заботясь о том,
 216 // был ли он ранее зарегистрирован:
 217 $redirector =
 218     Zend_Controller_Action_HelperBroker::getStaticHelper('redirector');
 219 }
 220 ]]></programlisting>
 221
 222         <para>
 223             Наконец, для удаления зарегистрированного помощника из брокера
 224             используйте <code>removeHelper($name)</code>, где <varname>$name</varname>
 225             - короткое имя помощника без префикса:
 226         </para>
 227
 228         <programlisting language="php"><![CDATA[
 229 // Удаление помощника 'redirector' из брокера, помещенное
 230 // в условную конструкцию
 231 if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
 232     Zend_Controller_Action_HelperBroker::removeHelper('redirector')
 233 }
 234 ]]></programlisting>
 235     </sect2>
 236
 237     <sect2 id="zend.controller.actionhelper.stockhelpers">
 238         <title>Встроенные помощники действий</title>
 239
 240         <para>
 241             Zend Framework уже содержит в себе набор помощников действий:
 242             <code>AutoComplete</code> автоматизирует ответы для автозавершения
 243             ввода с использованием AJAX; <code>ContextSwitch</code> и
 244             <code>AjaxContext</code> для обслуживания альтернативных форматов
 245             ответов для ваших действий; <code>FlashMessenger</code> для
 246             управления сессионными сообщениями; <code>Json</code> для
 247             кодирования и отправки ответов JSON; <code>Redirector</code>,
 248             предоставляющий различные реализации перенаправления из вашего
 249             приложения на внутренние и внешние страницы; и
 250             <code>ViewRenderer</code>, автоматизирующий процесс настройки
 251             объекта вида в контроллерах и рендеринга видов.
 252         </para>
 253
 254         <xi:include href="Zend_Controller-ActionHelpers-ActionStack.xml">
 255             <xi:fallback><xi:include href="../../en/module_specs/Zend_Controller-ActionHelpers-ActionStack.xml" /></xi:fallback>
 256         </xi:include>
 257         <xi:include href="Zend_Controller-ActionHelpers-AutoComplete.xml">
 258             <xi:fallback><xi:include href="../../en/module_specs/Zend_Controller-ActionHelpers-AutoComplete.xml" /></xi:fallback>
 259         </xi:include>
 260         <xi:include href="Zend_Controller-ActionHelpers-ContextSwitch.xml">
 261             <xi:fallback><xi:include href="../../en/module_specs/Zend_Controller-ActionHelpers-ContextSwitch.xml" /></xi:fallback>
 262         </xi:include>
 263         <xi:include href="Zend_Controller-ActionHelpers-FlashMessenger.xml">
 264             <xi:fallback><xi:include href="../../en/module_specs/Zend_Controller-ActionHelpers-FlashMessenger.xml" /></xi:fallback>
 265         </xi:include>
 266         <xi:include href="Zend_Controller-ActionHelpers-Json.xml">
 267             <xi:fallback><xi:include href="../../en/module_specs/Zend_Controller-ActionHelpers-Json.xml" /></xi:fallback>
 268         </xi:include>
 269         <xi:include href="Zend_Controller-ActionHelpers-Redirector.xml">
 270             <xi:fallback><xi:include href="../../en/module_specs/Zend_Controller-ActionHelpers-Redirector.xml" /></xi:fallback>
 271         </xi:include>
 272         <xi:include href="Zend_Controller-ActionHelpers-ViewRenderer.xml">
 273             <xi:fallback><xi:include href="../../en/module_specs/Zend_Controller-ActionHelpers-ViewRenderer.xml" /></xi:fallback>
 274         </xi:include>
 275     </sect2>
 276
 277     <sect2 id="zend.controller.actionhelper.writingyourown">
 278         <title>Написание собственных помощников</title>
 279
 280         <para>
 281             Помощники действий наследуют от абстрактного класса
 282             <classname>Zend_Controller_Action_Helper_Abstract</classname>,
 283             который предоставляет базовый интерфейс и функционал, необходимые
 284             для использования с брокером помощников. Он включает в себя
 285             следующие методы:
 286         </para>
 287
 288         <itemizedlist>
 289             <listitem>
 290                 <para>
 291                     <code>setActionController()</code> используется для
 292                     установки текущего контроллера действий.
 293                 </para>
 294             </listitem>
 295
 296             <listitem>
 297                 <para>
 298                     <code>init()</code>, запускаемый брокером при
 299                     инстанцировании, может использоваться для запуска
 300                     инициализации в помощнике. Это может быть полезным для
 301                     переустановки состояния, когда несколько контроллеров
 302                     используют один и тот же помощник в цепочке действий.
 303                 </para>
 304             </listitem>
 305
 306             <listitem>
 307                 <para>
 308                     <code>preDispatch()</code> запускается до того, как будет
 309                     запущено действие.
 310                 </para>
 311             </listitem>
 312
 313             <listitem>
 314                 <para>
 315                     <code>postDispatch()</code> запускается, когда
 316                     выполнение действия завершилось  - даже если
 317                     плагин <code>preDispatch()</code> пропустил это действие.
 318                     Полезно в основном для очистки.
 319                 </para>
 320             </listitem>
 321
 322             <listitem>
 323                 <para>
 324                     <code>getRequest()</code> возвращает текущий объект запроса.
 325                 </para>
 326             </listitem>
 327
 328             <listitem>
 329                 <para>
 330                     <code>getResponse()</code> возвращает текущий объект ответа.
 331                 </para>
 332             </listitem>
 333
 334             <listitem>
 335                 <para>
 336                     <code>getName()</code> возвращает имя помощника. Он
 337                     извлекает ту часть имени класса, которая следует после
 338                     последнего символа подчеркивания, иначе возвращается полное
 339                     имя класса. Например, если класс называется
 340                     <classname>Zend_Controller_Action_Helper_Redirector</classname>,
 341                     то он вернет <code>Redirector</code>, а если класс называется
 342                     <code>FooMessage</code> то он просто вернет свое полное имя.
 343                 </para>
 344             </listitem>
 345         </itemizedlist>
 346
 347         <para>
 348             Вы можете опционально добавить метод <code>direct()</code> в свой
 349             класс помощника. Если он определен, то это позволит вам обращаться к
 350             помощнику как к методу брокера помощников, этим обеспечивается
 351             легкое единовременное использование помощника. Например,
 352             <link linkend="zend.controller.actionhelpers.redirector">redirector</link>
 353             определяет <code>direct()</code> как псевдоним метода
 354             <code>goto()</code>, что позволяет использовать помощника следующим
 355             образом:
 356         </para>
 357
 358         <programlisting language="php"><![CDATA[
 359 // Перенаправление на /blog/view/item/id/42
 360 $this->_helper->redirector('item', 'view', 'blog', array('id' => 42));
 361 ]]></programlisting>
 362
 363         <para>
 364             Метод брокера помощников <code>__call()</code> ищет помощника с
 365             именем <code>redirector</code>, затем смотрит, имеет ли помощник
 366             определенный метод <code>direct</code>, и, если есть, вызывает его с
 367             переданными аргументами.
 368         </para>
 369
 370         <para>
 371             Создав собственный класс помощника, вы можете предоставить доступ к
 372             нему, как описано в разделах выше.
 373         </para>
 374     </sect2>
 375 </sect1>
 376 <!--
 377 vim:se ts=4 sw=4 et:
 378 -->