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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.view.helpers.initial.currency">
   4     <title>Currency Helper</title>
   5
   6     <para>
   7         Displaying localized currency values is a common task; the
   8         <classname>Zend_Currency</classname> view helper is intended to simply this task. See the
   9         <link linkend="zend.currency.introduction">Zend_Currency documentation</link> for specifics
  10         on this localization feature. In this section, we will focus simply on usage of the view
  11         helper.
  12     </para>
  13
  14     <para>
  15         There are several ways to initiate the <emphasis>Currency</emphasis> view helper:
  16     </para>
  17
  18     <itemizedlist>
  19         <listitem>
  20             <para>
  21                 Registered, through a previously registered instance in
  22                 <classname>Zend_Registry</classname>.
  23             </para>
  24         </listitem>
  25
  26         <listitem>
  27             <para>
  28                 Afterwards, through the fluent interface.
  29             </para>
  30         </listitem>
  31
  32         <listitem>
  33             <para>
  34                 Directly, through instantiating the class.
  35             </para>
  36         </listitem>
  37     </itemizedlist>
  38
  39     <para>
  40         A registered instance of <classname>Zend_Currency</classname> is the preferred usage for
  41         this helper. Doing so, you can select the currency to be used prior to adding the adapter to
  42         the registry.
  43     </para>
  44
  45     <para>
  46         There are several ways to select the desired currency. First, you may simply provide a
  47         currency string; alternately, you may specify a locale. The preferred way is to use a
  48         locale as this information is automatically detected and selected via the HTTP client
  49         headers provided when a user accesses your application, and ensures the currency provided
  50         will match their locale.
  51     </para>
  52
  53     <note>
  54         <para>
  55             We are speaking of "locales" instead of "languages" because a language may vary based on
  56             the geographical region in which it is used. For example, English is spoken in different
  57             dialects: British English, American English, etc. As a currency always correlates to a
  58             country you must give a fully-qualified locale, which means providing both the language
  59             <emphasis>and</emphasis> region. Therefore, we say "locale" instead of "language."
  60         </para>
  61     </note>
  62
  63     <example id="zend.view.helpers.initial.currency.registered">
  64         <title>Registered instance</title>
  65
  66         <para>
  67             To use a registered instance, simply create an instance of
  68             <classname>Zend_Currency</classname> and register it within
  69             <classname>Zend_Registry</classname> using <classname>Zend_Currency</classname> as its
  70             key.
  71         </para>
  72
  73         <programlisting language="php"><![CDATA[
  74 // our example currency
  75 $currency = new Zend_Currency('de_AT');
  76 Zend_Registry::set('Zend_Currency', $currency);
  77
  78 // within your view
  79 echo $this->currency(1234.56);
  80 // this returns '€ 1.234,56'
  81 ]]></programlisting>
  82     </example>
  83
  84     <para>
  85         If you are more familiar with the fluent interface, then you can also create an instance
  86         within your view and configure the helper afterwards.
  87     </para>
  88
  89     <example id="zend.view.helpers.initial.currency.afterwards">
  90         <title>Within the view</title>
  91
  92         <para>
  93             To use the fluent interface, create an instance of <classname>Zend_Currency</classname>,
  94             call the helper without a parameter, and call the <methodname>setCurrency()</methodname>
  95             method.
  96         </para>
  97
  98         <programlisting language="php"><![CDATA[
  99 // within your view
 100 $currency = new Zend_Currency('de_AT');
 101 $this->currency()->setCurrency($currency)->currency(1234.56);
 102 // this returns '€ 1.234,56'
 103 ]]></programlisting>
 104     </example>
 105
 106     <para>
 107         If you are using the helper without <classname>Zend_View</classname> then you can
 108         also use it directly.
 109     </para>
 110
 111     <example id="zend.view.helpers.initial.currency.directly.example-1">
 112         <title>Direct usage</title>
 113
 114         <programlisting language="php"><![CDATA[
 115 // our example currency
 116 $currency = new Zend_Currency('de_AT');
 117
 118 // initiate the helper
 119 $helper = new Zend_View_Helper_Currency($currency);
 120 echo $helper->currency(1234.56); // this returns '€ 1.234,56'
 121 ]]></programlisting>
 122     </example>
 123
 124     <para>
 125         As already seen, the <methodname>currency()</methodname> method is used to return the
 126         currency string. Just call it with the value you want to display as a currency. It also
 127         accepts some options which may be used to change the behaviour and output of the helper.
 128     </para>
 129
 130     <example id="zend.view.helpers.initial.currency.directly.example-2">
 131         <title>Direct usage</title>
 132
 133         <programlisting language="php"><![CDATA[
 134 // our example currency
 135 $currency = new Zend_Currency('de_AT');
 136
 137 // initiate the helper
 138 $helper = new Zend_View_Helper_Currency($currency);
 139 echo $helper->currency(1234.56); // this returns '€ 1.234,56'
 140 echo $helper->currency(1234.56, array('precision' => 1));
 141 // this returns '€ 1.234,6'
 142 ]]></programlisting>
 143     </example>
 144
 145     <para>
 146         For details about the available options, search for <classname>Zend_Currency</classname>'s
 147         <methodname>toCurrency()</methodname> method.
 148     </para>
 149 </sect3>
 150 <!--
 151 vim:se ts=4 sw=4 et:
 152 -->