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

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

    <sect4 id="zend.view.helpers.initial.user-agent.intro">
        <title>Overview</title>

        <para>
            This view helper provides the ability to inject and later retrieve a
            <classname>Zend_Http_UserAgent</classname> instance for use in branching display logic
            based on device capabilities.
        </para>
    </sect4>

    <sect4 id="zend.view.helpers.initial.user-agent.quick-start">
        <title>Quick Start</title>

        <para>
            In most cases, you can simply retrieve the User-Agent and related device by calling the
            helper. If the <classname>UserAgent</classname> was configured in the <link
                linkend="zend.application.available-resources.useragent">
            bootstrap</link>, that instance will be injected already in the helper; otherwise, it
            will instantiate one for you.
        </para>

        <programlisting language="php"><![CDATA[
<?php if ($this->userAgent()->getDevice()->hasFlash()): ?>
    <object ...></object>
<?php endif ?>
]]></programlisting>

        <para>
            If you initialize the <classname>UserAgent</classname> object manually, you can still
            inject it into the helper, in one of two ways.
        </para>

        <programlisting language="php"><![CDATA[
// Pull the helper from the view, and inject:
$helper = $view->getHelper('userAgent');
$helper->setUserAgent($userAgent);

// Pass the UserAgent to the helper:
$view->userAgent($userAgent);
]]></programlisting>
    </sect4>

    <sect4 id="zend.view.helpers.initial.user-agent.methods">
        <title>Available Methods</title>

        <variablelist>
            <varlistentry id="zend.view.helpers.initial.user-agent.methods.user-agent">
                <term>
                    <methodsynopsis>
                        <methodname>userAgent</methodname>
                        <methodparam>
                            <funcparams>Zend_Http_UserAgent $userAgent = null</funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Use this method to set or retrieve the <classname>UserAgent</classname>
                        instance. Passing an instance will set it; passing no arguments will retrieve
                        it. If no previous instance has been registered, one will be lazy-loaded using
                        defaults.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry id="zend.view.helpers.initial.user-agent.methods.set-user-agent">
                <term>
                    <methodsynopsis>
                        <methodname>setUserAgent</methodname>
                        <methodparam>
                            <funcparams>Zend_Http_UserAgent $userAgent</funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        If you have an instance of the helper -- for instance, by calling the view
                        object's <methodname>getHelper()</methodname> method -- you may use this method
                        to set the <classname>UserAgent</classname> instance.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry id="zend.view.helpers.initial.user-agent.methods.get-user-agent">
                <term>
                    <methodsynopsis>
                        <methodname>getUserAgent</methodname>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Retrieves the <classname>UserAgent</classname> instance; if none is registered,
                        it will lazy-load one using default values.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </sect4>
</sect3>