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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.view.helpers.initial.placeholder">
   4     <title>Placeholder Helper</title>
   5
   6     <para>
   7         The <classname>Placeholder</classname> view helper is used to persist content
   8         between view scripts and view instances. It also offers some useful
   9         features such as aggregating content, capturing view script content
  10         for later use, and adding pre- and post-text to content (and custom
  11         separators for aggregated content).
  12     </para>
  13
  14     <example id="zend.view.helpers.initial.placeholder.usage">
  15         <title>Basic Usage of Placeholders</title>
  16
  17         <para>
  18             Basic usage of placeholders is to persist view data. Each invocation
  19             of the <classname>Placeholder</classname> helper expects a placeholder name;
  20             the helper then returns a placeholder container object that you can
  21             either manipulate or simply echo out.
  22         </para>
  23
  24         <programlisting language="php"><![CDATA[
  25 <?php $this->placeholder('foo')->set("Some text for later") ?>
  26
  27 <?php
  28     echo $this->placeholder('foo');
  29     // outputs "Some text for later"
  30 ?>
  31 ]]></programlisting>
  32     </example>
  33
  34     <example id="zend.view.helpers.initial.placeholder.aggregation">
  35         <title>Using Placeholders to Aggregate Content</title>
  36
  37         <para>
  38             Aggregating content via placeholders can be useful at times as well.
  39             For instance, your view script may have a variable array from which
  40             you wish to retrieve messages to display later; a later view script
  41             can then determine how those will be rendered.
  42         </para>
  43
  44         <para>
  45             The <classname>Placeholder</classname> view helper uses containers that extend
  46             <classname>ArrayObject</classname>, providing a rich featureset for
  47             manipulating arrays. In addition, it offers a variety of methods for
  48             formatting the content stored in the container:
  49         </para>
  50
  51         <itemizedlist>
  52             <listitem>
  53                 <para>
  54                     <methodname>setPrefix($prefix)</methodname> sets text with which to
  55                     prefix the content. Use <methodname>getPrefix()</methodname> at any time
  56                     to determine what the current setting is.
  57                 </para>
  58             </listitem>
  59
  60             <listitem>
  61                 <para>
  62                     <methodname>setPostfix($prefix)</methodname> sets text with which to
  63                     append the content. Use <methodname>getPostfix()</methodname> at any time
  64                     to determine what the current setting is.
  65                 </para>
  66             </listitem>
  67
  68             <listitem>
  69                 <para>
  70                     <methodname>setSeparator($prefix)</methodname> sets text with which to
  71                     separate aggregated content. Use <methodname>getSeparator()</methodname>
  72                     at any time to determine what the current setting is.
  73                 </para>
  74             </listitem>
  75
  76             <listitem>
  77                 <para>
  78                     <methodname>setIndent($prefix)</methodname> can be used to set an
  79                     indentation value for content. If an integer is passed,
  80                     that number of spaces will be used; if a string is passed,
  81                     the string will be used. Use <methodname>getIndent()</methodname>
  82                     at any time to determine what the current setting is.
  83                 </para>
  84             </listitem>
  85         </itemizedlist>
  86
  87         <programlisting language="php"><![CDATA[
  88 <!-- first view script -->
  89 <?php $this->placeholder('foo')->exchangeArray($this->data) ?>
  90 ]]></programlisting>
  91
  92         <programlisting language="php"><![CDATA[
  93 <!-- later view script -->
  94 <?php
  95 $this->placeholder('foo')->setPrefix("<ul>\n    <li>")
  96                          ->setSeparator("</li><li>\n")
  97                          ->setIndent(4)
  98                          ->setPostfix("</li></ul>\n");
  99 ?>
 100
 101 <?php
 102     echo $this->placeholder('foo');
 103     // outputs as unordered list with pretty indentation
 104 ?>
 105 ]]></programlisting>
 106
 107         <para>
 108             Because the <classname>Placeholder</classname> container objects extend
 109             <classname>ArrayObject</classname>, you can also assign content to a specific
 110             key in the container easily, instead of simply pushing it into the
 111             container. Keys may be accessed either as object properties or as
 112             array keys.
 113         </para>
 114
 115         <programlisting language="php"><![CDATA[
 116 <?php $this->placeholder('foo')->bar = $this->data ?>
 117 <?php echo $this->placeholder('foo')->bar ?>
 118
 119 <?php
 120 $foo = $this->placeholder('foo');
 121 echo $foo['bar'];
 122 ?>
 123 ]]></programlisting>
 124     </example>
 125
 126     <example id="zend.view.helpers.initial.placeholder.capture">
 127         <title>Using Placeholders to Capture Content</title>
 128
 129         <para>
 130             Occasionally you may have content for a placeholder in a view script
 131             that is easiest to template; the <classname>Placeholder</classname> view
 132             helper allows you to capture arbitrary content for later rendering
 133             using the following <acronym>API</acronym>.
 134         </para>
 135
 136         <itemizedlist>
 137             <listitem>
 138                 <para>
 139                     <methodname>captureStart($type, $key)</methodname> begins capturing
 140                     content.
 141                 </para>
 142
 143                 <para>
 144                     <varname>$type</varname> should be one of the
 145                     <classname>Placeholder</classname> constants <constant>APPEND</constant> or
 146                     <constant>SET</constant>. If <constant>APPEND</constant>, captured content
 147                     is appended to the list of current content in the
 148                     placeholder; if <constant>SET</constant>, captured content is used
 149                     as the sole value of the placeholder (potentially replacing
 150                     any previous content). By default, <varname>$type</varname> is
 151                     <constant>APPEND</constant>.
 152                 </para>
 153
 154                 <para>
 155                     <varname>$key</varname> can be used to specify a specific key in
 156                     the placeholder container to which you want content
 157                     captured.
 158                 </para>
 159
 160                 <para>
 161                     <methodname>captureStart()</methodname> locks capturing until
 162                     <methodname>captureEnd()</methodname> is called; you cannot nest
 163                     capturing with the same placeholder container. Doing so will
 164                     raise an exception.
 165                 </para>
 166             </listitem>
 167
 168             <listitem>
 169                 <para>
 170                     <methodname>captureEnd()</methodname> stops capturing content, and
 171                     places it in the container object according to how
 172                     <methodname>captureStart()</methodname> was called.
 173                 </para>
 174             </listitem>
 175         </itemizedlist>
 176
 177         <programlisting language="php"><![CDATA[
 178 <!-- Default capture: append -->
 179 <?php $this->placeholder('foo')->captureStart();
 180 foreach ($this->data as $datum): ?>
 181 <div class="foo">
 182     <h2><?php echo $datum->title ?></h2>
 183     <p><?php echo $datum->content ?></p>
 184 </div>
 185 <?php endforeach; ?>
 186 <?php $this->placeholder('foo')->captureEnd() ?>
 187
 188 <?php echo $this->placeholder('foo') ?>
 189 ]]></programlisting>
 190
 191         <programlisting language="php"><![CDATA[
 192 <!-- Capture to key -->
 193 <?php $this->placeholder('foo')->captureStart('SET', 'data');
 194 foreach ($this->data as $datum): ?>
 195 <div class="foo">
 196     <h2><?php echo $datum->title ?></h2>
 197     <p><?php echo $datum->content ?></p>
 198 </div>
 199  <?php endforeach; ?>
 200 <?php $this->placeholder('foo')->captureEnd() ?>
 201
 202 <?php echo $this->placeholder('foo')->data ?>
 203 ]]></programlisting>
 204     </example>
 205
 206     <sect4 id="zend.view.helpers.initial.placeholder.implementations">
 207         <title>Concrete Placeholder Implementations</title>
 208
 209         <para>
 210             Zend Framework ships with a number of "concrete" placeholder
 211             implementations. These are for commonly used placeholders: doctype,
 212             page title, and various &lt;head&gt; elements. In all cases, calling
 213             the placeholder with no arguments returns the element itself.
 214         </para>
 215
 216         <para>
 217             Documentation for each element is covered separately, as linked
 218             below:
 219         </para>
 220
 221         <itemizedlist>
 222             <listitem>
 223                 <para>
 224                     <link linkend="zend.view.helpers.initial.doctype">Doctype</link>
 225                 </para>
 226             </listitem>
 227
 228             <listitem>
 229                 <para>
 230                     <link linkend="zend.view.helpers.initial.headlink">HeadLink</link>
 231                 </para>
 232             </listitem>
 233
 234             <listitem>
 235                 <para>
 236                     <link linkend="zend.view.helpers.initial.headmeta">HeadMeta</link>
 237                 </para>
 238             </listitem>
 239
 240             <listitem>
 241                 <para>
 242                     <link linkend="zend.view.helpers.initial.headscript">HeadScript</link>
 243                 </para>
 244             </listitem>
 245
 246             <listitem>
 247                 <para>
 248                     <link linkend="zend.view.helpers.initial.headstyle">HeadStyle</link>
 249                 </para>
 250             </listitem>
 251
 252             <listitem>
 253                 <para>
 254                     <link linkend="zend.view.helpers.initial.headtitle">HeadTitle</link>
 255                 </para>
 256             </listitem>
 257
 258             <listitem>
 259                 <para>
 260                     <link linkend="zend.view.helpers.initial.inlinescript">InlineScript</link>
 261                 </para>
 262             </listitem>
 263         </itemizedlist>
 264     </sect4>
 265 </sect3>
 266 <!--
 267 vim:se ts=4 sw=4 et:
 268 -->