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

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

    <para>
        Displaying localized currency values is a common task; the
        <classname>Zend_Currency</classname> view helper is intended to simply this task. See the
        <link linkend="zend.currency.introduction">Zend_Currency documentation</link> for specifics
        on this localization feature. In this section, we will focus simply on usage of the view
        helper.
    </para>

    <para>
        There are several ways to initiate the <emphasis>Currency</emphasis> view helper:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                Registered, through a previously registered instance in
                <classname>Zend_Registry</classname>.
            </para>
        </listitem>

        <listitem>
            <para>
                Afterwards, through the fluent interface.
            </para>
        </listitem>

        <listitem>
            <para>
                Directly, through instantiating the class.
            </para>
        </listitem>
    </itemizedlist>

    <para>
        A registered instance of <classname>Zend_Currency</classname> is the preferred usage for
        this helper. Doing so, you can select the currency to be used prior to adding the adapter to
        the registry.
    </para>

    <para>
        There are several ways to select the desired currency. First, you may simply provide a
        currency string; alternately, you may specify a locale. The preferred way is to use a
        locale as this information is automatically detected and selected via the
        <acronym>HTTP</acronym> client headers provided when a user accesses your application, and
        ensures the currency provided will match their locale.
    </para>

    <note>
        <para>
            We are speaking of "locales" instead of "languages" because a language may vary based on
            the geographical region in which it is used. For example, English is spoken in different
            dialects: British English, American English, etc. As a currency always correlates to a
            country you must give a fully-qualified locale, which means providing both the language
            <emphasis>and</emphasis> region. Therefore, we say "locale" instead of "language."
        </para>
    </note>

    <example id="zend.view.helpers.initial.currency.registered">
        <title>Registered instance</title>

        <para>
            To use a registered instance, simply create an instance of
            <classname>Zend_Currency</classname> and register it within
            <classname>Zend_Registry</classname> using <classname>Zend_Currency</classname> as its
            key.
        </para>

        <programlisting language="php"><![CDATA[
// our example currency
$currency = new Zend_Currency('de_AT');
Zend_Registry::set('Zend_Currency', $currency);

// within your view
echo $this->currency(1234.56);
// this returns '€ 1.234,56'
]]></programlisting>
    </example>

    <para>
        If you are more familiar with the fluent interface, then you can also create an instance
        within your view and configure the helper afterwards.
    </para>

    <example id="zend.view.helpers.initial.currency.afterwards">
        <title>Within the view</title>

        <para>
            To use the fluent interface, create an instance of <classname>Zend_Currency</classname>,
            call the helper without a parameter, and call the <methodname>setCurrency()</methodname>
            method.
        </para>

        <programlisting language="php"><![CDATA[
// within your view
$currency = new Zend_Currency('de_AT');
$this->currency()->setCurrency($currency)->currency(1234.56);
// this returns '€ 1.234,56'
]]></programlisting>
    </example>

    <para>
        If you are using the helper without <classname>Zend_View</classname> then you can
        also use it directly.
    </para>

    <example id="zend.view.helpers.initial.currency.directly.example-1">
        <title>Direct usage</title>

        <programlisting language="php"><![CDATA[
// our example currency
$currency = new Zend_Currency('de_AT');

// initiate the helper
$helper = new Zend_View_Helper_Currency($currency);
echo $helper->currency(1234.56); // this returns '€ 1.234,56'
]]></programlisting>
    </example>

    <para>
        As already seen, the <methodname>currency()</methodname> method is used to return the
        currency string. Just call it with the value you want to display as a currency. It also
        accepts some options which may be used to change the behaviour and output of the helper.
    </para>

    <example id="zend.view.helpers.initial.currency.directly.example-2">
        <title>Direct usage</title>

        <programlisting language="php"><![CDATA[
// our example currency
$currency = new Zend_Currency('de_AT');

// initiate the helper
$helper = new Zend_View_Helper_Currency($currency);
echo $helper->currency(1234.56); // this returns '€ 1.234,56'
echo $helper->currency(1234.56, array('precision' => 1));
// this returns '€ 1.234,6'
]]></programlisting>
    </example>

    <para>
        For details about the available options, search for <classname>Zend_Currency</classname>'s
        <methodname>toCurrency()</methodname> method.
    </para>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->