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 following methods are also supported with XHTML1_RDFA doctype
        set with the <link linkend="zend.view.helpers.initial.doctype">Doctype helper</link>:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <command>appendProperty($property, $content, $modifiers)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>offsetSetProperty($index, $property, $content, $modifiers)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>prependProperty($property, $content, $modifiers)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>setProperty($property, $content, $modifiers)</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>$keyType</varname> may also be specified as 'property' if the
        doctype has been set to XHTML1_RDFA. <varname>$placement</varname> can be '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>

    <example id="zend.view.helpers.initial.headmeta.property">
        <title>HeadMeta Usage with XHTML1_RDFA doctype</title>

        <para>
            Enabling the RDFa doctype with the <link linkend="zend.view.helpers.initial.doctype">Doctype helper</link>
            enables the use of the 'property' attribute (in addition to the standard 'name' and 'http-equiv') with HeadMeta.
            This is commonly used with the Facebook <ulink url="http://opengraphprotocol.org/">Open Graph Protocol</ulink>.
        </para>

        <para>
            For instance, you may specify an open graph page title and type as follows:
        </para>

        <programlisting language="php"><![CDATA[
$this->doctype(Zend_View_Helper_Doctype::XHTML1_RDFA);
$this->headMeta()->setProperty('og:title', 'my article title');
$this->headMeta()->setProperty('og:type', 'article');
echo $this->headMeta();

// output is:
//   <meta property="og:title" content="my article title" />
//   <meta property="og:type" content="article" />
]]></programlisting>

    </example>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->