Units API converts between various weights and measurements.
The central API call, unitsapi_convert($value, $from, $to, $details = FALSE), uses the International System of Units (SI) conversion factors to convert measurement units.
This module is only an API and does not have an user interface.
A submodule, unitsapi_formatters, provides display formatters for CCK Number Fields and Measured Value Fields. The formatters will convert the field's value upon output.
SUPPORTED UNITS
A list of supported units, and the keys you need to pass to the unitsapi_convert() function, are available on the module's help page.
DISPLAY FORMATTERS
A submodule, unitsapi_formatters, provides display formatters for CCK Number Fields and Measured Value Fields. The formatters will convert the field's value upon output. If you are using a Measured Value Field, the conversion will respect your number format and label settings.
EXAMPLES
<?php
// Convert kilometer to feet
$result = unitsapi_convert(1.5, 'kilometer', 'foot');
// $result == 4921.259843
// Convert Fahrenheit to Kelvin
$result = unitsapi_convert(55, 'fahrenheit', 'kelvin');
// $result == 285.927778
// Convert US liquid ounces to Imperial pints with a detailed array of the conversion
$result = unitsapi_convert(50, 'us fluid ounce', 'imperial pint', TRUE);
// $result == Array ([result] => 2.602107, [from][view] => US fluid ounces, [to][view] => Imperial pints)
?>HOOK_UNITSAPI_LOAD_ALTER() and HOOK_UNITSAPI_RESULT_ALTER()
<?php
/**
* Implementation of hook_unitsapi_load_alter().
*/
function mymodule_unitsapi_load_alter(&$units) {
/* Modify the meter name */
$units['meter']['singular'] = 'metre';
/* Add a kilopascal unit to the pressure category */
$units['kilopascal'] = Array('singular' => 'kilopascal', 'plural' => 'kilopascals', 'symbol' => 'kPa', 'factor' => '1000', 'kind' => 'pressure', 'source' => 'http://physics.nist.gov/Pubs/SP811/contents.html');
}
/**
* Implementation of hook_unitsapi_result_alter().
*/
function mymodule_unitsapi_result_alter(&$result) {
if ($result['from']['key'] == 'meter') {
$result['result'] = mymodule_any_function($result['value']);
}
}
?>HOW TO ADD NEW UNITS
- Option #1: Implement hook_unitsapi_load_alter() from your own module to add units.
- Option #2: Implement hook_unitsapi_result_alter() from your own module to add units or run your own conversion function.
- Option #3: Create an issue with your requested units. The issue requires at least the unit name, plural name, symbol, conversion factor, and an URL to a credible source to verify the conversion factor. For the conversion factor, check the units.xml file for the common factor. For example, all Area conversions use square meters as their conversion factor.
INTEGRATED MODULES
FUTURE PLANS
- Add additional measurement units.
- Add additional automated tests.
SPONSORED BY
This module is sponsored by Raspberry Man LLC.
Project Information
- Maintenance status: Actively maintained
- Development status: Under active development
- Module categories: Utility
- Reported installs: 172 sites currently report using this module. View usage statistics.
- Last modified: April 3, 2011
