documentation/manual/en/module_specs/Zend_Currency-Description.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.currency.description">
   4     <title>What makes a currency?</title>
   5
   6     <para>
   7         The currency consists of several informations. A name, a abbreviation and a sign. Each
   8         of these could be relevant to be displayed, but only one at the same time. It would not
   9         be a good practice to display something like "USD 1.000 $".
  10     </para>
  11
  12     <para>
  13         Therefor <classname>Zend_Currency</classname> supports the definition of the currency
  14         information which has to be rendered. The following constants can be used:
  15     </para>
  16
  17     <table id="zend.currency.description.table-1">
  18         <title>Rendered informations for a currency</title>
  19
  20         <tgroup cols="2" align="left">
  21             <thead>
  22                 <row>
  23                     <entry>Constant</entry>
  24                     <entry>Description</entry>
  25                 </row>
  26             </thead>
  27
  28             <tbody>
  29                 <row>
  30                     <entry><constant>NO_SYMBOL</constant></entry>
  31                     <entry>No currency representation will be rendered at all</entry>
  32                 </row>
  33
  34                 <row>
  35                     <entry><constant>USE_SYMBOL</constant></entry>
  36
  37                     <entry>
  38                         The currency symbol will be rendered. For US Dollar this would be '$'
  39                     </entry>
  40                 </row>
  41
  42                 <row>
  43                     <entry><constant>USE_SHORTNAME</constant></entry>
  44
  45                     <entry>
  46                         The abbreviation for this currency will be rendered. For US Dollar this
  47                         would be 'USD'. Most abbreviations consist of 3 characters
  48                     </entry>
  49                 </row>
  50
  51                 <row>
  52                     <entry><constant>USE_NAME</constant></entry>
  53
  54                     <entry>
  55                         The full name for this currency will be rendered. For US Dollar the full
  56                         name would be "US Dollar"
  57                     </entry>
  58                 </row>
  59             </tbody>
  60         </tgroup>
  61     </table>
  62
  63     <example id="zend.currency.description.example-1">
  64         <title>Selecting the currency description</title>
  65
  66         <para>
  67             Let's assume that your client has again set "en_US" as locale. Using no option the
  68             returned value could look like this:
  69         </para>
  70
  71         <programlisting language="php"><![CDATA[
  72 $currency = new Zend_Currency(
  73     array(
  74         'value' => 100,
  75     )
  76 );
  77
  78 print $currency; // Could return '$ 100'
  79 ]]></programlisting>
  80
  81         <para>
  82             By giving the proper option you can define what information which has to be
  83             rendered.
  84         </para>
  85
  86         <programlisting language="php"><![CDATA[
  87 $currency = new Zend_Currency(
  88     array(
  89         'value'   => 100,
  90         'display' => Zend_Currency::USE_SHORTNAME,
  91     )
  92 );
  93
  94 print $currency; // Could return 'USD 100'
  95 ]]></programlisting>
  96
  97         <para>
  98              Without providing the <property>display</property> the currency sign will be used
  99             when rendering the object. When the currency has no sign, the abbreviation will be
 100             used as replacement.
 101         </para>
 102     </example>
 103
 104     <note>
 105         <title>Not all currencies have signs</title>
 106
 107         <para>
 108             You should note that not all currencies have default currency signs. This means,
 109             that when there is no default sign, and you set the sign to be rendered, you will
 110             not have a rendered currency at all because the sign is an empty string.
 111         </para>
 112     </note>
 113
 114     <para>
 115         Sometimes it is necessary to change the default informations. You can set each of the
 116         three currency informations independently by giving the proper option. See the following
 117         example.
 118     </para>
 119
 120     <example id="zend.currency.description.example-2">
 121         <title>Changing the currency description</title>
 122
 123         <para>
 124             Let's assume that your client has again set "en_US" as locale. But now we don't want
 125             to use the default settings but set our own description. This can simply be done
 126             providing the proper option:
 127         </para>
 128
 129         <programlisting language="php"><![CDATA[
 130 $currency = new Zend_Currency(
 131     array(
 132         'value' => 100,
 133         'name'  => 'Dollar',
 134     )
 135 );
 136
 137 print $currency; // Could return 'Dollar 100'
 138 ]]></programlisting>
 139
 140         <para>
 141             You could also set a sign or an abbreviations yourself.
 142         </para>
 143
 144         <programlisting language="php"><![CDATA[
 145 $currency = new Zend_Currency(
 146     array(
 147         'value'    => 100,
 148         'symbol' => '$$$',
 149     )
 150 );
 151
 152 print $currency; // Could return '$$$ 100'
 153 ]]></programlisting>
 154     </example>
 155
 156     <note>
 157         <title>Automatic display settings</title>
 158
 159         <para>
 160             When you set a name, abbreviation or sign yourself, than this new information will
 161             automatically be set to be rendered. This simplification prevents you from setting
 162             the proper <property>display</property> option when you set a information.
 163         </para>
 164
 165         <para>
 166             So using the <property>sign</property> option you can omit
 167             <property>display</property> and don't neet to setting it to
 168             '<constant>USE_SYMBOL</constant>'.
 169         </para>
 170     </note>
 171 </sect1>