documentation/manual/en/module_specs/Zend_View-Helpers.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.view.helpers" xmlns:xi="http://www.w3.org/2001/XInclude">
   4     <title>View Helpers</title>
   5
   6     <para>
   7         In your view scripts, often it is necessary to perform certain
   8         complex functions over and over: e.g., formatting a date,
   9         generating form elements, or displaying action links. You can
  10         use helper classes to perform these behaviors for you.
  11     </para>
  12
  13     <para>
  14         A helper is simply a class. Let's say we want a helper named 'fooBar'.
  15         By default, the class is prefixed with 'Zend_View_Helper_'
  16         (you can specify a custom prefix when setting a helper path), and the
  17         last segment of the class name is the helper name; this segment should
  18         be TitleCapped; the full class name is then:
  19         <classname>Zend_View_Helper_FooBar</classname>. This class should contain at the
  20         minimum a single method, named after the helper, and camelCased:
  21         <methodname>fooBar()</methodname>.
  22     </para>
  23
  24     <note>
  25         <title>Watch the Case</title>
  26         <para>
  27             Helper names are always camelCased, i.e., they never begin with an
  28             uppercase character. The class name itself is MixedCased, but the
  29             method that is actually executed is camelCased.
  30         </para>
  31     </note>
  32
  33     <note>
  34         <title>Default Helper Path</title>
  35
  36         <para>
  37             The default helper path always points to the Zend Framework view
  38             helpers, i.e., 'Zend/View/Helper/'. Even if you call
  39             <methodname>setHelperPath()</methodname> to overwrite the existing paths, this
  40             path will be set to ensure the default helpers work.
  41         </para>
  42     </note>
  43
  44     <para>
  45         To use a helper in your view script, call it using
  46         <command>$this->helperName()</command>. Behind the scenes,
  47         <classname>Zend_View</classname> will load the
  48         <classname>Zend_View_Helper_HelperName</classname> class, create an object
  49         instance of it, and call its <methodname>helperName()</methodname> method. The
  50         object instance is persistent within the <classname>Zend_View</classname>
  51         instance, and is reused for all future calls to
  52         <command>$this->helperName()</command>.
  53     </para>
  54
  55     <sect2 id="zend.view.helpers.initial">
  56         <title>Initial Helpers</title>
  57
  58         <para>
  59             <classname>Zend_View</classname> comes with an initial set of helper classes,
  60             most of which relate to form element generation and perform
  61             the appropriate output escaping automatically. In addition, there
  62             are helpers for creating route-based <acronym>URL</acronym>s and HTML lists, as well as
  63             declaring variables. The currently shipped helpers include:
  64         </para>
  65
  66         <itemizedlist>
  67
  68             <listitem><para>
  69                 <methodname>declareVars()</methodname>: Primarily for use when using
  70                 <methodname>strictVars()</methodname>, this helper can be used to declare
  71                 template variables that may or may not already be set in the
  72                 view object, as well as to set default values. Arrays passed as
  73                 arguments to the method will be used to set default values;
  74                 otherwise, if the variable does not exist, it is set to an empty
  75                 string.
  76             </para></listitem>
  77
  78             <listitem><para>
  79                 <methodname>fieldset($name, $content, $attribs)</methodname>: Creates an
  80                 <acronym>XHTML</acronym> fieldset. If <varname>$attribs</varname> contains a
  81                 'legend' key, that value will be used for the fieldset legend. The
  82                 fieldset will surround the <varname>$content</varname> as provided to
  83                 the helper.
  84             </para></listitem>
  85
  86             <listitem><para>
  87                 <methodname>form($name, $attribs, $content)</methodname>: Generates an
  88                 <acronym>XHTML</acronym> form. All <varname>$attribs</varname> are escaped and
  89                 rendered as <acronym>XHTML</acronym> attributes of the form tag. If
  90                 <varname>$content</varname> is present and not a boolean <constant>FALSE</constant>,
  91                 then that content is rendered within the start and close form tags; if
  92                 <varname>$content</varname> is a boolean <constant>FALSE</constant> (the default),
  93                 only the opening form tag is generated.
  94             </para></listitem>
  95
  96             <listitem><para>
  97                 <methodname>formButton($name, $value, $attribs)</methodname>: Creates an
  98                 &lt;button /&gt; element.
  99             </para></listitem>
 100
 101             <listitem>
 102                 <para>
 103                     <methodname>formCheckbox($name, $value, $attribs,
 104                         $options)</methodname>: Creates an &lt;input type="checkbox"
 105                     /&gt; element.
 106                 </para>
 107
 108                 <para>
 109                     By default, when no $value is provided and no $options are
 110                     present, '0' is assumed to be the unchecked value, and '1'
 111                     the checked value. If a $value is passed, but no $options
 112                     are present, the checked value is assumed to be the value
 113                     passed.
 114                 </para>
 115
 116                 <para>
 117                     $options should be an array. If the array is indexed, the
 118                     first value is the checked value, and the second the
 119                     unchecked value; all other values are ignored. You may also
 120                     pass an associative array with the keys 'checked' and
 121                     'unChecked'.
 122                 </para>
 123
 124                 <para>
 125                     If $options has been passed, if $value matches the checked
 126                     value, then the element will be marked as checked. You may
 127                     also mark the element as checked or unchecked by passing a
 128                     boolean value for the attribute 'checked'.
 129                 </para>
 130
 131                 <para>
 132                     The above is probably best summed up with some examples:
 133                 </para>
 134
 135                 <programlisting language="php"><![CDATA[
 136 // '1' and '0' as checked/unchecked options; not checked
 137 echo $this->formCheckbox('foo');
 138
 139 // '1' and '0' as checked/unchecked options; checked
 140 echo $this->formCheckbox('foo', null, array('checked' => true));
 141
 142 // 'bar' and '0' as checked/unchecked options; not checked
 143 echo $this->formCheckbox('foo', 'bar');
 144
 145 // 'bar' and '0' as checked/unchecked options; checked
 146 echo $this->formCheckbox('foo', 'bar', array('checked' => true));
 147
 148 // 'bar' and 'baz' as checked/unchecked options; unchecked
 149 echo $this->formCheckbox('foo', null, null, array('bar', 'baz'));
 150
 151 // 'bar' and 'baz' as checked/unchecked options; unchecked
 152 echo $this->formCheckbox('foo', null, null, array(
 153     'checked' => 'bar',
 154     'unChecked' => 'baz'
 155 ));
 156
 157 // 'bar' and 'baz' as checked/unchecked options; checked
 158 echo $this->formCheckbox('foo', 'bar', null, array('bar', 'baz'));
 159 echo $this->formCheckbox('foo',
 160                          null,
 161                          array('checked' => true),
 162                          array('bar', 'baz'));
 163
 164 // 'bar' and 'baz' as checked/unchecked options; unchecked
 165 echo $this->formCheckbox('foo', 'baz', null, array('bar', 'baz'));
 166 echo $this->formCheckbox('foo',
 167                          null,
 168                          array('checked' => false),
 169                          array('bar', 'baz'));
 170 ]]></programlisting>
 171
 172                 <para>
 173                     In all cases, the markup prepends a hidden element with the
 174                     unchecked value; this way, if the value is unchecked, you
 175                     will still get a valid value returned to your form.
 176                 </para>
 177             </listitem>
 178
 179             <listitem>
 180                 <para>
 181                     <methodname>formErrors($errors, $options)</methodname>: Generates an
 182                     <acronym>XHTML</acronym> unordered list to show errors.
 183                     <varname>$errors</varname> should be a string or an array of strings;
 184                     <varname>$options</varname> should be any attributes you want
 185                     placed in the opening list tag.
 186                 </para>
 187
 188                 <para>
 189                     You can specify alternate opening, closing, and separator
 190                     content when rendering the errors by calling several methods
 191                     on the helper:
 192                 </para>
 193
 194                 <itemizedlist>
 195                     <listitem><para>
 196                             <methodname>setElementStart($string)</methodname>; default is
 197                             '&lt;ul class="errors"%s"&gt;&lt;li&gt;', where %s
 198                             is replaced with the attributes as specified in
 199                             <varname>$options</varname>.
 200                     </para></listitem>
 201
 202                     <listitem><para>
 203                             <methodname>setElementSeparator($string)</methodname>; default
 204                             is '&lt;/li&gt;&lt;li&gt;'.
 205                     </para></listitem>
 206
 207                     <listitem><para>
 208                             <methodname>setElementEnd($string)</methodname>; default is
 209                             '&lt;/li&gt;&lt;/ul&gt;'.
 210                     </para></listitem>
 211                 </itemizedlist>
 212             </listitem>
 213
 214             <listitem><para>
 215                 <methodname>formFile($name, $attribs)</methodname>: Creates an
 216                 &lt;input type="file" /&gt; element.
 217             </para></listitem>
 218
 219             <listitem><para>
 220                 <methodname>formHidden($name, $value, $attribs)</methodname>: Creates an
 221                 &lt;input type="hidden" /&gt; element.
 222             </para></listitem>
 223
 224             <listitem><para>
 225                 <methodname>formLabel($name, $value, $attribs)</methodname>: Creates a
 226                 &lt;label&gt; element, setting the <property>for</property> attribute to
 227                 <varname>$name</varname>, and the actual label text to
 228                 <varname>$value</varname>. If <emphasis>disable</emphasis> is passed in
 229                 <property>attribs</property>, nothing will be returned.
 230             </para></listitem>
 231
 232             <listitem><para>
 233                 <methodname>formMultiCheckbox($name, $value, $attribs, $options,
 234                     $listsep)</methodname>: Creates a list of checkboxes.
 235                 <varname>$options</varname> should be an associative array, and may be
 236                 arbitrarily deep. <varname>$value</varname> may be a single value or
 237                 an array of selected values that match the keys in the
 238                 <varname>$options</varname> array. <varname>$listsep</varname> is an HTML
 239                 break ("&lt;br /&gt;") by default. By default, this element is
 240                 treated as an array; all checkboxes share the same name, and are
 241                 submitted as an array.
 242             </para></listitem>
 243
 244             <listitem><para>
 245                 <methodname>formPassword($name, $value, $attribs)</methodname>: Creates an
 246                 &lt;input type="password" /&gt; element.
 247             </para></listitem>
 248
 249             <listitem><para>
 250                 <methodname>formRadio($name, $value, $attribs, $options)</methodname>:
 251                 Creates a series of &lt;input type="radio" /&gt; elements, one
 252                 for each of the $options elements. In the $options array, the
 253                 element key is the radio value, and the element value is the
 254                 radio label. The $value radio will be preselected for you.
 255             </para></listitem>
 256
 257             <listitem><para>
 258                 <methodname>formReset($name, $value, $attribs)</methodname>: Creates an
 259                 &lt;input type="reset" /&gt; element.
 260             </para></listitem>
 261
 262             <listitem><para>
 263                 <methodname>formSelect($name, $value, $attribs, $options)</methodname>:
 264                 Creates a &lt;select&gt;...&lt;/select&gt; block, with one
 265                 &lt;option&gt;one for each of the $options elements. In the
 266                 $options array, the element key is the option value, and the
 267                 element value is the option label. The $value option(s) will be
 268                 preselected for you.
 269             </para></listitem>
 270
 271             <listitem><para>
 272                 <methodname>formSubmit($name, $value, $attribs)</methodname>: Creates an
 273                 &lt;input type="submit" /&gt; element.
 274             </para></listitem>
 275
 276             <listitem><para>
 277                 <methodname>formText($name, $value, $attribs)</methodname>: Creates an
 278                 &lt;input type="text" /&gt; element.
 279             </para></listitem>
 280
 281             <listitem><para>
 282                 <methodname>formTextarea($name, $value, $attribs)</methodname>: Creates a
 283                 &lt;textarea&gt;...&lt;/textarea&gt; block.
 284             </para></listitem>
 285
 286             <listitem><para>
 287                 <methodname>url($urlOptions, $name, $reset)</methodname>: Creates a
 288                 <acronym>URL</acronym> string based on a named route.
 289                 <varname>$urlOptions</varname> should be an associative array of key/value pairs
 290                 used by the particular route.
 291             </para></listitem>
 292
 293             <listitem><para>
 294                 <methodname>htmlList($items, $ordered, $attribs, $escape)</methodname>: generates
 295                 unordered and ordered lists based on the <varname>$items</varname>
 296                 passed to it. If <varname>$items</varname> is a multidimensional
 297                 array, a nested list will be built. If the <varname>$escape</varname>
 298                 flag is <constant>TRUE</constant> (default), individual items will be escaped using
 299                 the view objects registered escaping mechanisms; pass a <constant>FALSE</constant>
 300                 value if you want to allow markup in your lists.
 301             </para></listitem>
 302
 303         </itemizedlist>
 304
 305         <para>
 306             Using these in your view scripts is very easy, here is an example.
 307             Note that you all you need to do is call them; they will load
 308             and instantiate themselves as they are needed.
 309         </para>
 310
 311         <programlisting language="php"><![CDATA[
 312 // inside your view script, $this refers to the Zend_View instance.
 313 //
 314 // say that you have already assigned a series of select options under
 315 // the name $countries as array('us' => 'United States', 'il' =>
 316 // 'Israel', 'de' => 'Germany').
 317 ?>
 318 <form action="action.php" method="post">
 319     <p><label>Your Email:
 320 <?php echo $this->formText('email', 'you@example.com', array('size' => 32)) ?>
 321     </label></p>
 322     <p><label>Your Country:
 323 <?php echo $this->formSelect('country', 'us', null, $this->countries) ?>
 324     </label></p>
 325     <p><label>Would you like to opt in?
 326 <?php echo $this->formCheckbox('opt_in', 'yes', null, array('yes', 'no')) ?>
 327     </label></p>
 328 </form>
 329 ]]></programlisting>
 330
 331         <para>
 332             The resulting output from the view script will look something like this:
 333         </para>
 334
 335         <programlisting language="php"><![CDATA[
 336 <form action="action.php" method="post">
 337     <p><label>Your Email:
 338         <input type="text" name="email" value="you@example.com" size="32" />
 339     </label></p>
 340     <p><label>Your Country:
 341         <select name="country">
 342             <option value="us" selected="selected">United States</option>
 343             <option value="il">Israel</option>
 344             <option value="de">Germany</option>
 345         </select>
 346     </label></p>
 347     <p><label>Would you like to opt in?
 348         <input type="hidden" name="opt_in" value="no" />
 349         <input type="checkbox" name="opt_in" value="yes" checked="checked" />
 350     </label></p>
 351 </form>
 352 ]]></programlisting>
 353
 354         <xi:include href="Zend_View-Helpers-Action.xml" />
 355         <xi:include href="Zend_View-Helpers-BaseUrl.xml" />
 356         <xi:include href="Zend_View-Helpers-Currency.xml" />
 357         <xi:include href="Zend_View-Helpers-Cycle.xml" />
 358         <xi:include href="Zend_View-Helpers-Partial.xml" />
 359         <xi:include href="Zend_View-Helpers-Placeholder.xml" />
 360         <xi:include href="Zend_View-Helpers-Doctype.xml" />
 361         <xi:include href="Zend_View-Helpers-HeadLink.xml" />
 362         <xi:include href="Zend_View-Helpers-HeadMeta.xml" />
 363         <xi:include href="Zend_View-Helpers-HeadScript.xml" />
 364         <xi:include href="Zend_View-Helpers-HeadStyle.xml" />
 365         <xi:include href="Zend_View-Helpers-HeadTitle.xml" />
 366         <xi:include href="Zend_View-Helpers-HtmlObject.xml" />
 367         <xi:include href="Zend_View-Helpers-InlineScript.xml" />
 368         <xi:include href="Zend_View-Helpers-Json.xml" />
 369         <xi:include href="Zend_View-Helpers-Navigation.xml" />
 370         <xi:include href="Zend_View-Helpers-Translate.xml" />
 371     </sect2>
 372
 373     <sect2 id="zend.view.helpers.paths">
 374         <title>Helper Paths</title>
 375
 376         <para>
 377             As with view scripts, your controller can specify a stack of paths
 378             for <classname>Zend_View</classname> to search for helper classes. By default,
 379             <classname>Zend_View</classname> looks in "Zend/View/Helper/*" for helper
 380             classes. You can tell <classname>Zend_View</classname> to look in other
 381             locations using the <methodname>setHelperPath()</methodname> and
 382             <methodname>addHelperPath()</methodname> methods. Additionally, you can
 383             indicate a class prefix to use for helpers in the path provided, to
 384             allow namespacing your helper classes. By default, if no class
 385             prefix is provided, 'Zend_View_Helper_' is assumed.
 386         </para>
 387
 388         <programlisting language="php"><![CDATA[
 389 $view = new Zend_View();
 390
 391 // Set path to /path/to/more/helpers, with prefix 'My_View_Helper'
 392 $view->setHelperPath('/path/to/more/helpers', 'My_View_Helper');
 393 ]]></programlisting>
 394
 395         <para>
 396             In fact, you can "stack" paths using the
 397             <methodname>addHelperPath()</methodname> method. As you add paths to the stack,
 398             <classname>Zend_View</classname> will look at the most-recently-added path for
 399             the requested helper class. This allows you to add to (or even
 400             override) the initial distribution of helpers with your own custom
 401             helpers.
 402         </para>
 403
 404         <programlisting language="php"><![CDATA[
 405 $view = new Zend_View();
 406 // Add /path/to/some/helpers with class prefix 'My_View_Helper'
 407 $view->addHelperPath('/path/to/some/helpers', 'My_View_Helper');
 408 // Add /other/path/to/helpers with class prefix 'Your_View_Helper'
 409 $view->addHelperPath('/other/path/to/helpers', 'Your_View_Helper');
 410
 411 // now when you call $this->helperName(), Zend_View will look first for
 412 // "/path/to/some/helpers/HelperName" using class name
 413 // "Your_View_Helper_HelperName", then for
 414 // "/other/path/to/helpers/HelperName.php" using class name
 415 // "My_View_Helper_HelperName", and finally for
 416 // "Zend/View/Helper/HelperName.php" using class name
 417 // "Zend_View_Helper_HelperName".
 418 ]]></programlisting>
 419
 420     </sect2>
 421
 422     <sect2 id="zend.view.helpers.custom">
 423         <title>Writing Custom Helpers</title>
 424
 425         <para>
 426             Writing custom helpers is easy; just follow these rules:
 427         </para>
 428
 429         <itemizedlist>
 430
 431             <listitem><para>
 432                 While not strictly necessary, we recommend either implementing
 433                 <classname>Zend_View_Helper_Interface</classname> or extending
 434                 <classname>Zend_View_Helper_Abstract</classname> when creating your
 435                 helpers. Introduced in 1.6.0, these simply define a
 436                 <methodname>setView()</methodname> method; however, in upcoming releases, we
 437                 plan to implement a strategy pattern that will simplify much of
 438                 the naming schema detailed below. Building off these now will
 439                 help you future-proof your code.
 440             </para></listitem>
 441
 442             <listitem><para>
 443                 The class name must, at the very minimum, end with the helper
 444                 name itself, using MixedCaps. E.g., if you were writing a
 445                 helper called "specialPurpose", the class name would minimally
 446                 need to be "SpecialPurpose". You may, and should, give the class
 447                 name a prefix, and it is recommended that you use 'View_Helper'
 448                 as part of that prefix: "My_View_Helper_SpecialPurpose". (You
 449                 will need to pass in the prefix, with or without the trailing
 450                 underscore, to <methodname>addHelperPath()</methodname> or
 451                 <methodname>setHelperPath()</methodname>).
 452             </para></listitem>
 453
 454             <listitem><para>
 455                 The class must have a public method that matches the
 456                 helper name; this is the method that will be called when
 457                 your template calls "$this->specialPurpose()". In our
 458                 "specialPurpose" helper example, the required method
 459                 declaration would be "public function specialPurpose()".
 460             </para></listitem>
 461
 462             <listitem><para>
 463                 In general, the class should not echo or print or otherwise
 464                 generate output. Instead, it should return values to be
 465                 printed or echoed. The returned values should be escaped
 466                 appropriately.
 467             </para></listitem>
 468
 469             <listitem><para>
 470                 The class must be in a file named after the helper class. Again
 471                 using our "specialPurpose" helper example, the file has to be
 472                 named "SpecialPurpose.php".
 473             </para></listitem>
 474         </itemizedlist>
 475
 476         <para>
 477             Place the helper class file somewhere in your helper path stack, and
 478             <classname>Zend_View</classname> will automatically load, instantiate,
 479             persist, and execute it for you.
 480         </para>
 481
 482         <para>
 483             Here is an example of our <classname>SpecialPurpose</classname> helper code:
 484         </para>
 485
 486         <programlisting language="php"><![CDATA[
 487 class My_View_Helper_SpecialPurpose extends Zend_View_Helper_Abstract
 488 {
 489     protected $_count = 0;
 490     public function specialPurpose()
 491     {
 492         $this->_count++;
 493         $output = "I have seen 'The Jerk' {$this->_count} time(s).";
 494         return htmlspecialchars($output);
 495     }
 496 }
 497 ]]></programlisting>
 498
 499         <para>
 500             Then in a view script, you can call the <classname>SpecialPurpose</classname>
 501             helper as many times as you like; it will be instantiated once, and
 502             then it persists for the life of that <classname>Zend_View</classname>
 503             instance.
 504         </para>
 505
 506         <programlisting language="php"><![CDATA[
 507 // remember, in a view script, $this refers to the Zend_View instance.
 508 echo $this->specialPurpose();
 509 echo $this->specialPurpose();
 510 echo $this->specialPurpose();
 511 ]]></programlisting>
 512
 513         <para>
 514             The output would look something like this:
 515         </para>
 516         <programlisting language="php"><![CDATA[
 517 I have seen 'The Jerk' 1 time(s).
 518 I have seen 'The Jerk' 2 time(s).
 519 I have seen 'The Jerk' 3 time(s).
 520 ]]></programlisting>
 521
 522         <para>
 523             Sometimes you will need access to the calling <classname>Zend_View</classname>
 524             object -- for instance, if you need to use the registered encoding,
 525             or want to render another view script as part of your helper. To get
 526             access to the view object, your helper class should have a
 527             <methodname>setView($view)</methodname> method, like the following:
 528         </para>
 529
 530         <programlisting language="php"><![CDATA[
 531 class My_View_Helper_ScriptPath
 532 {
 533     public $view;
 534
 535     public function setView(Zend_View_Interface $view)
 536     {
 537         $this->view = $view;
 538     }
 539
 540     public function scriptPath($script)
 541     {
 542         return $this->view->getScriptPath($script);
 543     }
 544 }
 545 ]]></programlisting>
 546
 547         <para>
 548             If your helper class has a <methodname>setView()</methodname> method, it will be
 549             called when the helper class is first instantiated, and passed the
 550             current view object. It is up to you to persist the object in your
 551             class, as well as determine how it should be accessed.
 552         </para>
 553
 554         <para>
 555             If you are extending <classname>Zend_View_Helper_Abstract</classname>, you do
 556             not need to define this method, as it is defined for you.
 557         </para>
 558     </sect2>
 559
 560     <sect2 id="zend.view.helpers.registering-concrete">
 561         <title>Registering Concrete Helpers</title>
 562
 563         <para>
 564             Sometimes it is convenient to instantiate a view helper, and then register it with the
 565             view. As of version 1.10.0, this is now possible using the
 566             <methodname>registerHelper()</methodname> method, which expects two arguments: the
 567             helper object, and the name by which it will be registered.
 568         </para>
 569
 570         <programlisting language="php"><![CDATA[
 571 $helper = new My_Helper_Foo();
 572 // ...do some configuration or dependency injection...
 573
 574 $view->registerHelper($helper, 'foo');
 575 ]]></programlisting>
 576
 577         <para>
 578             If the helper has a <methodname>setView()</methodname> method, the view object will call
 579             this and inject itself into the helper on registration.
 580         </para>
 581
 582         <note>
 583             <title>Helper name should match a method</title>
 584
 585             <para>
 586                 The second argument to <methodname>registerHelper()</methodname> is the name of the
 587                 helper. A corresponding method name should exist in the helper; otherwise,
 588                 <classname>Zend_View</classname> will call a non-existent method when invoking the
 589                 helper, raising a fatal PHP error.
 590             </para>
 591         </note>
 592     </sect2>
 593 </sect1>
 594 <!--
 595 vim:se ts=4 sw=4 et:
 596 -->