documentation/manual/en/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>Action Helpers</title>
   5
   6     <sect2 id="zend.controller.actionhelper.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             Action Helpers allow developers to inject runtime and/or on-demand
  11             functionality into any Action Controllers that extend
  12             <classname>Zend_Controller_Action</classname>. Action Helpers aim to minimize the
  13             necessity to extend the abstract Action Controller in order to
  14             inject common Action Controller functionality.
  15         </para>
  16
  17         <para>
  18             There are a number of ways to use Action Helpers. Action Helpers
  19             employ the use of a brokerage system, similar to the types of
  20             brokerage you see in <link
  21                 linkend="zend.view.helpers">Zend_View_Helper</link>, and that
  22             of <link
  23                 linkend="zend.controller.plugins">Zend_Controller_Plugin</link>.
  24             Action Helpers (like <classname>Zend_View_Helper</classname>) may be
  25             loaded and called on demand, or they may be instantiated at
  26             request time (bootstrap) or action controller creation time
  27             (<methodname>init()</methodname>). To understand this more fully, please see the usage
  28             section below.
  29         </para>
  30     </sect2>
  31
  32     <sect2 id="zend.controller.actionhelper.initialization">
  33         <title>Helper Initialization</title>
  34
  35         <para>
  36             A helper can be initialized in several different ways, based on
  37             your needs as well as the functionality of that helper.
  38         </para>
  39
  40         <para>
  41             The helper broker is stored as the <varname>$_helper</varname> member of
  42             <classname>Zend_Controller_Action</classname>; use the broker to retrieve or
  43             call on helpers. Some methods for doing so include:
  44         </para>
  45
  46         <itemizedlist>
  47             <listitem>
  48                 <para>
  49                     Explicitly using <methodname>getHelper()</methodname>. Simply pass it a
  50                     name, and a helper object is returned:
  51                 </para>
  52
  53                 <programlisting language="php"><![CDATA[
  54 $flashMessenger = $this->_helper->getHelper('FlashMessenger');
  55 $flashMessenger->addMessage('We did something in the last request');
  56 ]]></programlisting>
  57             </listitem>
  58
  59             <listitem>
  60                 <para>
  61                     Use the helper broker's <methodname>__get()</methodname> functionality
  62                     and retrieve the helper as if it were a member property of
  63                     the broker:
  64                 </para>
  65
  66                 <programlisting language="php"><![CDATA[
  67 $flashMessenger = $this->_helper->FlashMessenger;
  68 $flashMessenger->addMessage('We did something in the last request');
  69 ]]></programlisting>
  70             </listitem>
  71
  72             <listitem>
  73                 <para>
  74                     Finally, most action helpers implement the method
  75                     <methodname>direct()</methodname> which will call a specific, default
  76                     method in the helper. In the example of the
  77                     <emphasis>FlashMessenger</emphasis>, it calls
  78                     <methodname>addMessage()</methodname>:
  79                 </para>
  80
  81                 <programlisting language="php"><![CDATA[
  82 $this->_helper->FlashMessenger('We did something in the last request');
  83 ]]></programlisting>
  84             </listitem>
  85         </itemizedlist>
  86
  87         <note>
  88             <para>All of the above examples are functionally equivalent.</para>
  89         </note>
  90
  91         <para>
  92             You may also instantiate helpers explicitly. You may wish to do this
  93             if using the helper outside of an action controller, or if you wish
  94             to pass a helper to the helper broker for use by any action.
  95             Instantiation is as per any other <acronym>PHP</acronym> class.
  96         </para>
  97     </sect2>
  98
  99     <sect2 id="zend.controller.actionhelper.broker">
 100         <title>The Helper Broker</title>
 101
 102         <para>
 103             <classname>Zend_Controller_Action_HelperBroker</classname> handles the details
 104             of registering helper objects and helper paths, as well as
 105             retrieving helpers on-demand.
 106         </para>
 107
 108         <para>
 109             To register a helper with the broker, use <methodname>addHelper()</methodname>:
 110         </para>
 111
 112         <programlisting language="php"><![CDATA[
 113 Zend_Controller_Action_HelperBroker::addHelper($helper);
 114 ]]></programlisting>
 115
 116         <para>
 117             Of course, instantiating and passing helpers to the broker is a bit
 118             time and resource intensive, so two methods exists to automate
 119             things slightly: <methodname>addPrefix()</methodname> and
 120             <methodname>addPath()</methodname>.
 121         </para>
 122
 123         <itemizedlist>
 124             <listitem>
 125                 <para>
 126                     <methodname>addPrefix()</methodname> takes a class prefix and uses it
 127                     to determine a path where helper classes have been defined.
 128                     It assumes the prefix follows Zend Framework class naming
 129                     conventions.
 130                 </para>
 131
 132                 <programlisting language="php"><![CDATA[
 133 // Add helpers prefixed with My_Action_Helpers in My/Action/Helpers/
 134 Zend_Controller_Action_HelperBroker::addPrefix('My_Action_Helpers');
 135 ]]></programlisting>
 136             </listitem>
 137
 138             <listitem>
 139                 <para>
 140                     <methodname>addPath()</methodname> takes a directory as its first
 141                     argument and a class prefix as the second argument
 142                     (defaulting to '<classname>Zend_Controller_Action_Helper</classname>').
 143                     This allows you to map your own class prefixes to specific directories.
 144                 </para>
 145
 146                 <programlisting language="php"><![CDATA[
 147 // Add helpers prefixed with Helper in Plugins/Helpers/
 148 Zend_Controller_Action_HelperBroker::addPath('./Plugins/Helpers',
 149                                              'Helper');
 150 ]]></programlisting>
 151             </listitem>
 152         </itemizedlist>
 153
 154         <para>
 155             Since these methods are static, they may be called at any point in
 156             the controller chain in order to dynamically add helpers as needed.
 157         </para>
 158
 159         <para>
 160             Internally, the helper broker uses <link
 161                 linkend="zend.loader.pluginloader">a PluginLoader
 162                 instance</link> to maintain paths. You can retrieve the
 163             PluginLoader using the static method <methodname>getPluginLoader()</methodname>,
 164             or, alternately, inject a custom PluginLoader instance using
 165             <methodname>setPluginLoader()</methodname>.
 166         </para>
 167
 168         <para>
 169             To determine if a helper exists in the helper broker, use
 170             <methodname>hasHelper($name)</methodname>, where <varname>$name</varname> is the short
 171             name of the helper (minus the prefix):
 172         </para>
 173
 174         <programlisting language="php"><![CDATA[
 175 // Check if 'redirector' helper is registered with the broker:
 176 if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
 177     echo 'Redirector helper registered';
 178 }
 179 ]]></programlisting>
 180
 181         <para>
 182             There are also two static methods for retrieving helpers from the helper
 183             broker: <methodname>getExistingHelper()</methodname> and
 184             <methodname>getStaticHelper()</methodname>.
 185             <methodname>getExistingHelper()</methodname>
 186             will retrieve a helper only if it has previously been invoked by or
 187             explicitly registered with the helper broker; it will throw an
 188             exception if not. <methodname>getStaticHelper()</methodname> does the same as
 189             <methodname>getExistingHelper()</methodname>, but will attempt to instantiate
 190             the helper if has not yet been registered with the helper stack.
 191             <methodname>getStaticHelper()</methodname> is a good choice for retrieving
 192             helpers which you wish to configure.
 193         </para>
 194
 195         <para>
 196             Both methods take a single argument, <varname>$name</varname>, which is
 197             the short name of the helper (minus the prefix).
 198         </para>
 199
 200         <programlisting language="php"><![CDATA[
 201 // Check if 'redirector' helper is registered with the broker, and fetch:
 202 if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
 203     $redirector =
 204         Zend_Controller_Action_HelperBroker::getExistingHelper('redirector');
 205 }
 206
 207 // Or, simply retrieve it, not worrying about whether or not it was
 208 // previously registered:
 209 $redirector =
 210     Zend_Controller_Action_HelperBroker::getStaticHelper('redirector');
 211 }
 212 ]]></programlisting>
 213
 214         <para>
 215             Finally, to delete a registered helper from the broker, use
 216             <methodname>removeHelper($name)</methodname>, where <varname>$name</varname> is the
 217             short name of the helper (minus the prefix):
 218         </para>
 219
 220         <programlisting language="php"><![CDATA[
 221 // Conditionally remove the 'redirector' helper from the broker:
 222 if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
 223     Zend_Controller_Action_HelperBroker::removeHelper('redirector')
 224 }
 225 ]]></programlisting>
 226     </sect2>
 227
 228     <sect2 id="zend.controller.actionhelper.stockhelpers">
 229         <title>Built-in Action Helpers</title>
 230
 231         <para>
 232             Zend Framework includes several action helpers by default:
 233             <emphasis>AutoComplete</emphasis> for automating responses for <acronym>AJAX</acronym>
 234             autocompletion; <emphasis>ContextSwitch</emphasis> and
 235             <emphasis>AjaxContext</emphasis> for serving alternate response formats for
 236             your actions; a <emphasis>FlashMessenger</emphasis> for handling session flash
 237             messages; <emphasis>Json</emphasis> for encoding and sending <acronym>JSON</acronym>
 238             responses; a <emphasis>Redirector</emphasis>, to provide different
 239             implementations for redirecting to internal and external pages from
 240             your application; and a <emphasis>ViewRenderer</emphasis> to automate the
 241             process of setting up the view object in your controllers and
 242             rendering views.
 243         </para>
 244
 245         <xi:include href="Zend_Controller-ActionHelpers-ActionStack.xml" />
 246         <xi:include href="Zend_Controller-ActionHelpers-AutoComplete.xml" />
 247         <xi:include href="Zend_Controller-ActionHelpers-ContextSwitch.xml" />
 248         <xi:include href="Zend_Controller-ActionHelpers-FlashMessenger.xml" />
 249         <xi:include href="Zend_Controller-ActionHelpers-Json.xml" />
 250         <xi:include href="Zend_Controller-ActionHelpers-Redirector.xml" />
 251         <xi:include href="Zend_Controller-ActionHelpers-ViewRenderer.xml" />
 252     </sect2>
 253
 254     <sect2 id="zend.controller.actionhelper.writingyourown">
 255         <title>Writing Your Own Helpers</title>
 256
 257         <para>
 258             Action helpers extend
 259             <classname>Zend_Controller_Action_Helper_Abstract</classname>, an abstract
 260             class that provides the basic interface and functionality required
 261             by the helper broker. These include the following methods:
 262         </para>
 263
 264         <itemizedlist>
 265             <listitem>
 266                 <para>
 267                     <methodname>setActionController()</methodname> is used to set the current
 268                     action controller.
 269                 </para>
 270             </listitem>
 271
 272             <listitem>
 273                 <para>
 274                     <methodname>init()</methodname>, triggered by the helper broker at
 275                     instantiation, can be used to trigger initialization in the
 276                     helper; this can be useful for resetting state when multiple
 277                     controllers use the same helper in chained actions.
 278                 </para>
 279             </listitem>
 280
 281             <listitem>
 282                 <para>
 283                     <methodname>preDispatch()</methodname>, is triggered prior to a
 284                     dispatched action.
 285                 </para>
 286             </listitem>
 287
 288             <listitem>
 289                 <para>
 290                     <methodname>postDispatch()</methodname> is triggered when a dispatched
 291                     action is done -- even if a <methodname>preDispatch()</methodname>
 292                     plugin has skipped the action. Mainly useful for cleanup.
 293                 </para>
 294             </listitem>
 295
 296             <listitem>
 297                 <para>
 298                     <methodname>getRequest()</methodname> retrieves the current request
 299                     object.
 300                 </para>
 301             </listitem>
 302
 303             <listitem>
 304                 <para>
 305                     <methodname>getResponse()</methodname> retrieves the current response
 306                     object.
 307                 </para>
 308             </listitem>
 309
 310             <listitem>
 311                 <para>
 312                     <methodname>getName()</methodname> retrieves the helper name. It
 313                     retrieves the portion of the class name following the last
 314                     underscore character, or the full class name otherwise. As
 315                     an example, if the class is named
 316                     <classname>Zend_Controller_Action_Helper_Redirector</classname>, it
 317                     will return <emphasis>Redirector</emphasis>; a class named
 318                     <emphasis>FooMessage</emphasis> will simply return itself.
 319                 </para>
 320             </listitem>
 321         </itemizedlist>
 322
 323         <para>
 324             You may optionally include a <methodname>direct()</methodname> method in your
 325             helper class. If defined, it allows you to treat the helper as a
 326             method of the helper broker, in order to allow easy, one-off usage
 327             of the helper. As an example, the <link
 328                 linkend="zend.controller.actionhelpers.redirector">redirector</link>
 329             defines <methodname>direct()</methodname> as an alias of
 330             <methodname>goto()</methodname>, allowing use of the helper like this:
 331         </para>
 332
 333         <programlisting language="php"><![CDATA[
 334 // Redirect to /blog/view/item/id/42
 335 $this->_helper->redirector('item', 'view', 'blog', array('id' => 42));
 336 ]]></programlisting>
 337
 338         <para>
 339             Internally, the helper broker's <methodname>__call()</methodname> method looks
 340             for a helper named <emphasis>redirector</emphasis>, then checks to see if
 341             that helper has a defined <methodname>direct()</methodname> method, and calls it
 342             with the arguments provided.
 343         </para>
 344
 345         <para>
 346             Once you have created your own helper class, you may provide access
 347             to it as described in the sections above.
 348         </para>
 349     </sect2>
 350 </sect1>
 351 <!--
 352 vim:se ts=4 sw=4 et:
 353 -->