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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect3 id="zend.view.helpers.initial.headmeta">
    <title>HeadMeta Helper</title>

    <para>
        The <acronym>HTML</acronym> <emphasis>&lt;meta&gt;</emphasis> element is used to provide
        meta information about your <acronym>HTML</acronym> document -- typically keywords, document
        character set, caching pragmas, etc. Meta tags may be either of the
        'http-equiv' or 'name' types, must contain a 'content' attribute, and
        can also have either of the 'lang' or 'scheme' modifier attributes.
    </para>

    <para>
        The <classname>HeadMeta</classname> helper supports the following methods for
        setting and adding meta tags:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <command>appendName($keyValue, $content, $conditionalName)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>offsetSetName($index, $keyValue, $content, $conditionalName)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>prependName($keyValue, $content, $conditionalName)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>setName($keyValue, $content, $modifiers)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>appendHttpEquiv($keyValue, $content, $conditionalHttpEquiv)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>offsetSetHttpEquiv($index, $keyValue, $content,
                    $conditionalHttpEquiv)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>prependHttpEquiv($keyValue, $content, $conditionalHttpEquiv)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>setHttpEquiv($keyValue, $content, $modifiers)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>setCharset($charset)</command>
            </para>
        </listitem>
    </itemizedlist>

    <para>
        The <varname>$keyValue</varname> item is used to define a value for the 'name'
        or 'http-equiv' key; <varname>$content</varname> is the value for the
        'content' key, and <varname>$modifiers</varname> is an optional associative
        array that can contain keys for 'lang' and/or 'scheme'.
    </para>

    <para>
        You may also set meta tags using the <methodname>headMeta()</methodname> helper
        method, which has the following signature: <command>headMeta($content,
            $keyValue, $keyType = 'name', $modifiers = array(), $placement =
            'APPEND')</command>. <varname>$keyValue</varname> is the content for the key
        specified in <varname>$keyType</varname>, which should be either 'name' or
        'http-equiv'. <varname>$placement</varname> can be either 'SET' (overwrites
        all previously stored values), 'APPEND' (added to end of stack), or
        'PREPEND' (added to top of stack).
    </para>

    <para>
        <classname>HeadMeta</classname> overrides each of <methodname>append()</methodname>,
        <methodname>offsetSet()</methodname>, <methodname>prepend()</methodname>, and
        <methodname>set()</methodname> to enforce usage of the special methods as listed above.
        Internally, it stores each item as a <property>stdClass</property> token, which it later
        serializes using the <methodname>itemToString()</methodname> method. This allows you
        to perform checks on the items in the stack, and optionally modify these
        items by simply modifying the object returned.
    </para>

    <para>
        The <classname>HeadMeta</classname> helper is a concrete implementation of the
        <link linkend="zend.view.helpers.initial.placeholder">Placeholder helper</link>.
    </para>

    <example id="zend.view.helpers.initial.headmeta.basicusage">
        <title>HeadMeta Helper Basic Usage</title>

        <para>
            You may specify a new meta tag at any time. Typically, you
            will specify client-side caching rules or SEO keywords.
        </para>

        <para>
            For instance, if you wish to specify SEO keywords, you'd be creating
            a meta name tag with the name 'keywords' and the content the
            keywords you wish to associate with your page:
        </para>

        <programlisting language="php"><![CDATA[
// setting meta keywords
$this->headMeta()->appendName('keywords', 'framework, PHP, productivity');
]]></programlisting>

        <para>
            If you wished to set some client-side caching rules, you'd set
            http-equiv tags with the rules you wish to enforce:
        </para>

        <programlisting language="php"><![CDATA[
// disabling client-side cache
$this->headMeta()->appendHttpEquiv('expires',
                                   'Wed, 26 Feb 1997 08:21:57 GMT')
                 ->appendHttpEquiv('pragma', 'no-cache')
                 ->appendHttpEquiv('Cache-Control', 'no-cache');
]]></programlisting>

        <para>
            Another popular use for meta tags is setting the content type,
            character set, and language:
        </para>

        <programlisting language="php"><![CDATA[
// setting content type and character set
$this->headMeta()->appendHttpEquiv('Content-Type',
                                   'text/html; charset=UTF-8')
                 ->appendHttpEquiv('Content-Language', 'en-US');
]]></programlisting>

        <para>
            If you are serving an <acronym>HTML</acronym>5 document, you should provide the
            character set like this:
        </para>

        <programlisting language="php"><![CDATA[
// setting character set in HTML5
$this->headMeta()->setCharset('UTF-8'); // Will look like <meta charset="UTF-8">
]]></programlisting>

        <para>
            As a final example, an easy way to display a transitional message
            before a redirect is using a "meta refresh":
        </para>

        <programlisting language="php"><![CDATA[
// setting a meta refresh for 3 seconds to a new url:
$this->headMeta()->appendHttpEquiv('Refresh',
                                   '3;URL=http://www.some.org/some.html');
]]></programlisting>

        <para>
            When you're ready to place your meta tags in the layout, simply echo the helper:
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->headMeta() ?>
]]></programlisting>
    </example>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->