[PROMOTE] Zend_View_Helper_Currency

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@20227 44c647ce-9c0f-0410-b52a-842ac1e357ba

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

@@ -0,0 +1,152 @@
+<?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 HTTP 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">
+        <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">
+        <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:
+-->

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

@@ -353,6 +353,7 @@ echo $this->formCheckbox('foo',
 
         <xi:include href="Zend_View-Helpers-Action.xml" />
         <xi:include href="Zend_View-Helpers-BaseUrl.xml" />
+        <xi:include href="Zend_View-Helpers-Currency.xml" />
         <xi:include href="Zend_View-Helpers-Cycle.xml" />
         <xi:include href="Zend_View-Helpers-Partial.xml" />
         <xi:include href="Zend_View-Helpers-Placeholder.xml" />

library/Zend/View/Helper/Currency.php

@@ -0,0 +1,119 @@
+<?php
+/**
+ * Zend Framework
+ *
+ * LICENSE
+ *
+ * This source file is subject to the new BSD license that is bundled
+ * with this package in the file LICENSE.txt.
+ * It is also available through the world-wide-web at this URL:
+ * http://framework.zend.com/license/new-bsd
+ * If you did not receive a copy of the license and are unable to
+ * obtain it through the world-wide-web, please send an email
+ * to [email protected] so we can send you a copy immediately.
+ *
+ * @category   Zend
+ * @package    Zend_View
+ * @subpackage Helper
+ * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ * @version    $Id:$
+ */
+
+/** Zend_View_Helper_Abstract.php */
+require_once 'Zend/View/Helper/Abstract.php';
+
+/**
+ * Currency view helper
+ *
+ * @category  Zend
+ * @package   Zend_View
+ * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd     New BSD License
+ */
+class Zend_View_Helper_Currency extends Zend_View_Helper_Abstract
+{
+    /**
+     * Currency object
+     *
+     * @var Zend_Currency
+     */
+    protected $_currency;
+
+    /**
+     * Constructor for manually handling
+     *
+     * @param  Zend_Currency $currency Instance of Zend_Currency
+     * @return void
+     */
+    public function __construct($currency = null)
+    {
+        if ($currency === null) {
+            require_once 'Zend/Registry.php';
+            if (Zend_Registry::isRegistered('Zend_Currency')) {
+                $currency = Zend_Registry::get('Zend_Currency');
+            }
+        }
+
+        $this->setCurrency($currency);
+    }
+
+    /**
+     * Output a formatted currency
+     *
+     * @param  integer|float                    $value    Currency value to output
+     * @param  string|Zend_Locale|Zend_Currency $currency OPTIONAL Currency to use for this call
+     * @return string Formatted currency
+     */
+    public function currency($value = null, $currency = null)
+    {
+        if ($value === null) {
+            return $this;
+        }
+
+        if (is_string($currency) || ($currency instanceof Zend_Locale)) {
+            require_once 'Zend/Locale.php';
+            if (Zend_Locale::isLocale($currency)) {
+                $currency = array('locale' => $currency);
+            }
+        }
+
+        if (is_string($currency)) {
+            $currency = array('currency' => $currency);
+        }
+
+        if (is_array($currency)) {
+            return $this->_currency->toCurrency($value, $currency);
+        }
+
+        return $this->_currency->toCurrency($value);
+    }
+
+    /**
+     * Sets a currency to use
+     *
+     * @param  Zend_Currency|String|Zend_Locale $currency Currency to use
+     * @throws Zend_View_Exception When no or a false currency was set
+     * @return Zend_View_Helper_Currency
+     */
+    public function setCurrency($currency = null)
+    {
+        if (!$currency instanceof Zend_Currency) {
+            require_once 'Zend/Currency.php';
+            $currency = new Zend_Currency($currency);
+        }
+        $this->_currency = $currency;
+
+        return $this;
+    }
+
+    /**
+     * Retrieve currency object
+     *
+     * @return Zend_Currency|null
+     */
+    public function getCurrency()
+    {
+        return $this->_currency;
+    }
+}

tests/Zend/View/Helper/AllTests.php

@@ -28,6 +28,7 @@
 
 require_once 'Zend/View/Helper/ActionTest.php';
 require_once 'Zend/View/Helper/BaseUrlTest.php';
+require_once 'Zend/View/Helper/CurrencyTest.php';
 require_once 'Zend/View/Helper/CycleTest.php';
 require_once 'Zend/View/Helper/DeclareVarsTest.php';
 require_once 'Zend/View/Helper/DoctypeTest.php';
@@ -95,6 +96,7 @@ public static function suite()
 
         $suite->addTestSuite('Zend_View_Helper_ActionTest');
         $suite->addTestSuite('Zend_View_Helper_BaseUrlTest');
+        $suite->addTestSuite('Zend_View_Helper_CurrencyTest');
         $suite->addTestSuite('Zend_View_Helper_CycleTest');
         $suite->addTestSuite('Zend_View_Helper_DeclareVarsTest');
         $suite->addTestSuite('Zend_View_Helper_DoctypeTest');