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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.view.helpers.initial.headmeta">
   4     <title>HeadMeta Helper</title>
   5
   6     <para>
   7         The <acronym>HTML</acronym> <emphasis>&lt;meta&gt;</emphasis> element is used to provide
   8         meta information about your <acronym>HTML</acronym> document -- typically keywords, document
   9         character set, caching pragmas, etc. Meta tags may be either of the
  10         'http-equiv' or 'name' types, must contain a 'content' attribute, and
  11         can also have either of the 'lang' or 'scheme' modifier attributes.
  12     </para>
  13
  14     <para>
  15         The <classname>HeadMeta</classname> helper supports the following methods for
  16         setting and adding meta tags:
  17     </para>
  18
  19     <itemizedlist>
  20         <listitem>
  21             <para>
  22                 <command>appendName($keyValue, $content, $conditionalName)</command>
  23             </para>
  24         </listitem>
  25
  26         <listitem>
  27             <para>
  28                 <command>offsetSetName($index, $keyValue, $content, $conditionalName)</command>
  29             </para>
  30         </listitem>
  31
  32         <listitem>
  33             <para>
  34                 <command>prependName($keyValue, $content, $conditionalName)</command>
  35             </para>
  36         </listitem>
  37
  38         <listitem>
  39             <para>
  40                 <command>setName($keyValue, $content, $modifiers)</command>
  41             </para>
  42         </listitem>
  43
  44         <listitem>
  45             <para>
  46                 <command>appendHttpEquiv($keyValue, $content, $conditionalHttpEquiv)</command>
  47             </para>
  48         </listitem>
  49
  50         <listitem>
  51             <para>
  52                 <command>offsetSetHttpEquiv($index, $keyValue, $content,
  53                     $conditionalHttpEquiv)</command>
  54             </para>
  55         </listitem>
  56
  57         <listitem>
  58             <para>
  59                 <command>prependHttpEquiv($keyValue, $content, $conditionalHttpEquiv)</command>
  60             </para>
  61         </listitem>
  62
  63         <listitem>
  64             <para>
  65                 <command>setHttpEquiv($keyValue, $content, $modifiers)</command>
  66             </para>
  67         </listitem>
  68
  69         <listitem>
  70             <para>
  71                 <command>setCharset($charset)</command>
  72             </para>
  73         </listitem>
  74     </itemizedlist>
  75
  76     <para>
  77         The <varname>$keyValue</varname> item is used to define a value for the 'name'
  78         or 'http-equiv' key; <varname>$content</varname> is the value for the
  79         'content' key, and <varname>$modifiers</varname> is an optional associative
  80         array that can contain keys for 'lang' and/or 'scheme'.
  81     </para>
  82
  83     <para>
  84         You may also set meta tags using the <methodname>headMeta()</methodname> helper
  85         method, which has the following signature: <command>headMeta($content,
  86             $keyValue, $keyType = 'name', $modifiers = array(), $placement =
  87             'APPEND')</command>. <varname>$keyValue</varname> is the content for the key
  88         specified in <varname>$keyType</varname>, which should be either 'name' or
  89         'http-equiv'. <varname>$placement</varname> can be either 'SET' (overwrites
  90         all previously stored values), 'APPEND' (added to end of stack), or
  91         'PREPEND' (added to top of stack).
  92     </para>
  93
  94     <para>
  95         <classname>HeadMeta</classname> overrides each of <methodname>append()</methodname>,
  96         <methodname>offsetSet()</methodname>, <methodname>prepend()</methodname>, and
  97         <methodname>set()</methodname> to enforce usage of the special methods as listed above.
  98         Internally, it stores each item as a <property>stdClass</property> token, which it later
  99         serializes using the <methodname>itemToString()</methodname> method. This allows you
 100         to perform checks on the items in the stack, and optionally modify these
 101         items by simply modifying the object returned.
 102     </para>
 103
 104     <para>
 105         The <classname>HeadMeta</classname> helper is a concrete implementation of the
 106         <link linkend="zend.view.helpers.initial.placeholder">Placeholder helper</link>.
 107     </para>
 108
 109     <example id="zend.view.helpers.initial.headmeta.basicusage">
 110         <title>HeadMeta Helper Basic Usage</title>
 111
 112         <para>
 113             You may specify a new meta tag at any time. Typically, you
 114             will specify client-side caching rules or SEO keywords.
 115         </para>
 116
 117         <para>
 118             For instance, if you wish to specify SEO keywords, you'd be creating
 119             a meta name tag with the name 'keywords' and the content the
 120             keywords you wish to associate with your page:
 121         </para>
 122
 123         <programlisting language="php"><![CDATA[
 124 // setting meta keywords
 125 $this->headMeta()->appendName('keywords', 'framework, PHP, productivity');
 126 ]]></programlisting>
 127
 128         <para>
 129             If you wished to set some client-side caching rules, you'd set
 130             http-equiv tags with the rules you wish to enforce:
 131         </para>
 132
 133         <programlisting language="php"><![CDATA[
 134 // disabling client-side cache
 135 $this->headMeta()->appendHttpEquiv('expires',
 136                                    'Wed, 26 Feb 1997 08:21:57 GMT')
 137                  ->appendHttpEquiv('pragma', 'no-cache')
 138                  ->appendHttpEquiv('Cache-Control', 'no-cache');
 139 ]]></programlisting>
 140
 141         <para>
 142             Another popular use for meta tags is setting the content type,
 143             character set, and language:
 144         </para>
 145
 146         <programlisting language="php"><![CDATA[
 147 // setting content type and character set
 148 $this->headMeta()->appendHttpEquiv('Content-Type',
 149                                    'text/html; charset=UTF-8')
 150                  ->appendHttpEquiv('Content-Language', 'en-US');
 151 ]]></programlisting>
 152
 153         <para>
 154             If you are serving an <acronym>HTML</acronym>5 document, you should provide the
 155             character set like this:
 156         </para>
 157
 158         <programlisting language="php"><![CDATA[
 159 // setting character set in HTML5
 160 $this->headMeta()->setCharset('UTF-8'); // Will look like <meta charset="UTF-8">
 161 ]]></programlisting>
 162
 163         <para>
 164             As a final example, an easy way to display a transitional message
 165             before a redirect is using a "meta refresh":
 166         </para>
 167
 168         <programlisting language="php"><![CDATA[
 169 // setting a meta refresh for 3 seconds to a new url:
 170 $this->headMeta()->appendHttpEquiv('Refresh',
 171                                    '3;URL=http://www.some.org/some.html');
 172 ]]></programlisting>
 173
 174         <para>
 175             When you're ready to place your meta tags in the layout, simply echo the helper:
 176         </para>
 177
 178         <programlisting language="php"><![CDATA[
 179 <?php echo $this->headMeta() ?>
 180 ]]></programlisting>
 181     </example>
 182 </sect3>
 183 <!--
 184 vim:se ts=4 sw=4 et:
 185 -->