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.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>

        <refentry id="zend.view.helpers.initial.user-agent.methods.user-agent">
            <refnamediv>
                <refname>userAgent</refname>
                <refpurpose>Set and/or retrieve the UserAgent instance</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>userAgent</methodname>
                    <methodparam>
                        <funcparams>Zend_Http_UserAgent $userAgent = null</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>userAgent()</title>

                <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>
            </refsect1>
        </refentry>

        <refentry id="zend.view.helpers.initial.user-agent.methods.set-user-agent">
            <refnamediv>
                <refname>setUserAgent</refname>
                <refpurpose>Set the UserAgent instance</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>setUserAgent</methodname>
                    <methodparam>
                        <funcparams>Zend_Http_UserAgent $userAgent</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>setUserAgent()</title>

                <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>
            </refsect1>
        </refentry>

        <refentry id="zend.view.helpers.initial.user-agent.methods.get-user-agent">
            <refnamediv>
                <refname>getUserAgent</refname>
                <refpurpose>Retrieve the UserAgent instance</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>getUserAgent</methodname>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>getUserAgent()</title>

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