You are here

README.txt in Format Number API 7

Same filename and directory in other branches
  1. 6 README.txt
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Format Number module for Drupal
;;
;; Original author: markus_petrux at drupal.org (October 2008)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

CONTENTS
========
* OVERVIEW
* INSTALLATION
* PHP API
* JAVASCRIPT API
* FORMS API NUMERIC ELEMENT


OVERVIEW
========

This module provides a method to configure number formats (site default and user
defined) with configurable decimal point and thousand separators.

The function <code>format_number($number, $decimals = 0)</code> can be used by
other contributed or custom modules to display numbers accordingly.

This module also provides the 'numericfield' Forms API element, which is a right
aligned text input element that allows the user enter numbers using the
configured thousands separator and decimal point (site default or user defined).

External references:
- http://www.php.net/number_format
- http://www.unicode.org/reports/tr35/tr35-11.html
- http://www.unicode.org/cldr/data/charts/by_type/number.symbol.html
- http://en.wikipedia.org/wiki/Decimal_separator


INSTALLATION
============

- Copy all contents of this package to your modules directory preserving
  subdirectory structure.

- Goto Administer > Site building > Modules to install this module.

- Optionally goto Administer > User management > Permissions to assign the
  "configure default number format" permission to roles of your choice.

- Goto Administer > Site configuration > Number format to configure default
  number format for the site. You may also allow users to set override these
  options from their profiles.

- When user-configurable option is enabled, a new fieldset (Number format
  settings) is available when the user profile is edited.


PHP API
=======

- Other modules may use the following functions exposed by this module:

/**
 * Format a number with (site default or user defined) thousands separator and
 * decimal point.
 *
 * @param float $number
 *   The number being formatted.
 * @param int $decimals
 *   Number of decimal digits. Use -1 for any number if decimals.
 * @return string
 *   The formatted number.
 */
function format_number($number, $decimals = 0) {}

/**
 * Formats numbers to a specified number of significant figures.
 *
 * @param number $number
 *   The number to format.
 * @param integer $significant_figures
 *   The number of significant figures to round and format the number to.
 * @return string
 *   The rounded and formatted number.
 */
function format_number_significant_figures($number, $significant_figures) {}

/**
 * Parse a formatted number.
 *
 * This function implements lenient parsing when possible, and only falls
 * back to site/user defined symbols when in doubt.
 * See http://www.unicode.org/reports/tr35/tr35-11.html#Lenient_Parsing
 *
 * @todo
 *  The algorithm probably needs optimization (using regular expressions?).
 *
 * @param string $formatted_number
 *   A number formatted with localized thousands separator and decimal point.
 * @param boolean $required
 *   If input is empty string, return FALSE when number is strictly required,
 *   otherwise an empty string is returned as 0.
 * @return number
 *   A valid PHP number. FALSE when input cannot be deciphered.
 */
function parse_formatted_number($formatted_number, $required = TRUE) {}

/**
 * Get the site/user defined thousands separator and decimal point characters.
 *
 * @param string $name
 *   The name of the option to retrieve (optional). Available options:
 *   - 'thousands_sep'  A one character string (it could be empty).
 *   - 'decimal_point'  A one character string.
 * @return mixed
 *   If name is not specified, an array with all options is returned.
 *   If name does not exist, NULL is returned.
 *   If name exists, its value is returned.
 */
function format_number_get_options($name = NULL) {}

/**
 * Expose a javascript version of the Format Number API.
 */
function format_number_add_js() {}


JAVASCRIPT API
==============

/**
 * Format a number with (site default or user defined) thousands separator
 * and decimal point.
 *
 * Formatting options are expected to be at Drupal.settings.format_number.
 *
 * @param float number
 *   The number being formatted.
 * @param int decimals
 *   Number of decimal digits. Use -1 for any number of decimals.
 * @param boolean truncate
 *   TRUE to trucate the decimal part (default). FALSE to round the result.
 * @return string
 *   The formatted number.
 */
Drupal.formatNumber = function(number, decimals, truncate) {}

/**
 * Parse a number with (site default or user defined) thousands separator
 * and decimal point.
 *
 * Formatting options are expected to be at Drupal.settings.format_number.
 *
 * @param string number
 *   A number formatted with localized thousands separator and decimal point.
 * @param boolean required
 *   FALSE to return "" when input is empty string. Otherwise, result is always
 *   returned as a valid number. Default is TRUE.
 * @return number
 *   A valid number.
 */
Drupal.parseNumber = function(number, required) {}


FORMS API NUMERIC ELEMENT
=========================

The 'numericfield' Forms API element provides a right aligned text input
element that allows the user enter numbers using the configured thousands
separator and decimal point (site default or user defined).


Example:

$form['my_number'] = array(
  '#type' => 'numericfield',
  '#title' => t('My number'),
  '#precision' => 10,
  '#decimals' => 2,
  '#minimum' => 0,
  '#maximum' => 123456.99,
  '#default_value' => $my_number,
);


Specific Forms API attributes for elements of #type 'numericfield':

- #precision:
  Integer that indicates the total number of digits available to store the
  number, including the digits to the right of the decimal point.
  Defaults to 12.

- #decimals
  Integer that indicates the number of available digits to the right of
  the decimal point.
  Defaults to 0. Maximum allowed number of decimal digits: 8.

- #minimum
- #maximum
  Minimum and maximum possible values that are allowed on input.


Other Forms API supported attributes for elements of #type 'numericfield':

- #title
- #description
- #attributes
- #field_prefix
- #field_suffix
- #prefix
- #suffix


Theme function used to render the form element:

- theme_numericfield()


CSS Class attached to numeric form elements:

- form-text (defined by Drupal core).
- form-numeric (defined in format_number.css).

File

README.txt
View source
  1. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2. ;; Format Number module for Drupal
  3. ;;
  4. ;; Original author: markus_petrux at drupal.org (October 2008)
  5. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  6. CONTENTS
  7. ========
  8. * OVERVIEW
  9. * INSTALLATION
  10. * PHP API
  11. * JAVASCRIPT API
  12. * FORMS API NUMERIC ELEMENT
  13. OVERVIEW
  14. ========
  15. This module provides a method to configure number formats (site default and user
  16. defined) with configurable decimal point and thousand separators.
  17. The function format_number($number, $decimals = 0) can be used by
  18. other contributed or custom modules to display numbers accordingly.
  19. This module also provides the 'numericfield' Forms API element, which is a right
  20. aligned text input element that allows the user enter numbers using the
  21. configured thousands separator and decimal point (site default or user defined).
  22. External references:
  23. - http://www.php.net/number_format
  24. - http://www.unicode.org/reports/tr35/tr35-11.html
  25. - http://www.unicode.org/cldr/data/charts/by_type/number.symbol.html
  26. - http://en.wikipedia.org/wiki/Decimal_separator
  27. INSTALLATION
  28. ============
  29. - Copy all contents of this package to your modules directory preserving
  30. subdirectory structure.
  31. - Goto Administer > Site building > Modules to install this module.
  32. - Optionally goto Administer > User management > Permissions to assign the
  33. "configure default number format" permission to roles of your choice.
  34. - Goto Administer > Site configuration > Number format to configure default
  35. number format for the site. You may also allow users to set override these
  36. options from their profiles.
  37. - When user-configurable option is enabled, a new fieldset (Number format
  38. settings) is available when the user profile is edited.
  39. PHP API
  40. =======
  41. - Other modules may use the following functions exposed by this module:
  42. /**
  43. * Format a number with (site default or user defined) thousands separator and
  44. * decimal point.
  45. *
  46. * @param float $number
  47. * The number being formatted.
  48. * @param int $decimals
  49. * Number of decimal digits. Use -1 for any number if decimals.
  50. * @return string
  51. * The formatted number.
  52. */
  53. function format_number($number, $decimals = 0) {}
  54. /**
  55. * Formats numbers to a specified number of significant figures.
  56. *
  57. * @param number $number
  58. * The number to format.
  59. * @param integer $significant_figures
  60. * The number of significant figures to round and format the number to.
  61. * @return string
  62. * The rounded and formatted number.
  63. */
  64. function format_number_significant_figures($number, $significant_figures) {}
  65. /**
  66. * Parse a formatted number.
  67. *
  68. * This function implements lenient parsing when possible, and only falls
  69. * back to site/user defined symbols when in doubt.
  70. * See http://www.unicode.org/reports/tr35/tr35-11.html#Lenient_Parsing
  71. *
  72. * @todo
  73. * The algorithm probably needs optimization (using regular expressions?).
  74. *
  75. * @param string $formatted_number
  76. * A number formatted with localized thousands separator and decimal point.
  77. * @param boolean $required
  78. * If input is empty string, return FALSE when number is strictly required,
  79. * otherwise an empty string is returned as 0.
  80. * @return number
  81. * A valid PHP number. FALSE when input cannot be deciphered.
  82. */
  83. function parse_formatted_number($formatted_number, $required = TRUE) {}
  84. /**
  85. * Get the site/user defined thousands separator and decimal point characters.
  86. *
  87. * @param string $name
  88. * The name of the option to retrieve (optional). Available options:
  89. * - 'thousands_sep' A one character string (it could be empty).
  90. * - 'decimal_point' A one character string.
  91. * @return mixed
  92. * If name is not specified, an array with all options is returned.
  93. * If name does not exist, NULL is returned.
  94. * If name exists, its value is returned.
  95. */
  96. function format_number_get_options($name = NULL) {}
  97. /**
  98. * Expose a javascript version of the Format Number API.
  99. */
  100. function format_number_add_js() {}
  101. JAVASCRIPT API
  102. ==============
  103. /**
  104. * Format a number with (site default or user defined) thousands separator
  105. * and decimal point.
  106. *
  107. * Formatting options are expected to be at Drupal.settings.format_number.
  108. *
  109. * @param float number
  110. * The number being formatted.
  111. * @param int decimals
  112. * Number of decimal digits. Use -1 for any number of decimals.
  113. * @param boolean truncate
  114. * TRUE to trucate the decimal part (default). FALSE to round the result.
  115. * @return string
  116. * The formatted number.
  117. */
  118. Drupal.formatNumber = function(number, decimals, truncate) {}
  119. /**
  120. * Parse a number with (site default or user defined) thousands separator
  121. * and decimal point.
  122. *
  123. * Formatting options are expected to be at Drupal.settings.format_number.
  124. *
  125. * @param string number
  126. * A number formatted with localized thousands separator and decimal point.
  127. * @param boolean required
  128. * FALSE to return "" when input is empty string. Otherwise, result is always
  129. * returned as a valid number. Default is TRUE.
  130. * @return number
  131. * A valid number.
  132. */
  133. Drupal.parseNumber = function(number, required) {}
  134. FORMS API NUMERIC ELEMENT
  135. =========================
  136. The 'numericfield' Forms API element provides a right aligned text input
  137. element that allows the user enter numbers using the configured thousands
  138. separator and decimal point (site default or user defined).
  139. Example:
  140. $form['my_number'] = array(
  141. '#type' => 'numericfield',
  142. '#title' => t('My number'),
  143. '#precision' => 10,
  144. '#decimals' => 2,
  145. '#minimum' => 0,
  146. '#maximum' => 123456.99,
  147. '#default_value' => $my_number,
  148. );
  149. Specific Forms API attributes for elements of #type 'numericfield':
  150. - #precision:
  151. Integer that indicates the total number of digits available to store the
  152. number, including the digits to the right of the decimal point.
  153. Defaults to 12.
  154. - #decimals
  155. Integer that indicates the number of available digits to the right of
  156. the decimal point.
  157. Defaults to 0. Maximum allowed number of decimal digits: 8.
  158. - #minimum
  159. - #maximum
  160. Minimum and maximum possible values that are allowed on input.
  161. Other Forms API supported attributes for elements of #type 'numericfield':
  162. - #title
  163. - #description
  164. - #attributes
  165. - #field_prefix
  166. - #field_suffix
  167. - #prefix
  168. - #suffix
  169. Theme function used to render the form element:
  170. - theme_numericfield()
  171. CSS Class attached to numeric form elements:
  172. - form-text (defined by Drupal core).
  173. - form-numeric (defined in format_number.css).