Class AddressFmt
Create a new formatter object to format physical addresses in a particular way. The options object may contain the following properties, both of which are optional:
- locale - the locale to use to format this address. If not specified, it uses the default locale
- style - the style of this address. The default style for each country usually includes all valid fields for that country.
- onLoad - a callback function to call when the address info for the locale is fully loaded and the address has been parsed. When the onLoad option is given, the address formatter object will attempt to load any missing locale data using the ilib loader callback. When the constructor is done (even if the data is already preassembled), the onLoad function is called with the current instance as a parameter, so this callback can be used with preassembled or dynamic loading or a mix of the two.
- sync - tell whether to load any missing locale data synchronously or asynchronously. If this option is given as "false", then the "onLoad" callback must be given, as the instance returned from this constructor will not be usable for a while.
- loadParams - an object containing parameters to pass to the loader callback function when locale data is missing. The parameters are not interpretted or modified in any way. They are simply passed along. The object may contain any property/value pairs as long as the calling code is in agreement with the loader callback function as to what those parameters mean.
Defined in: AddressFmt.js.
| Constructor Attributes | Constructor Name and Description |
|---|---|
|
AddressFmt(options)
|
| Method Attributes | Method Name and Description |
|---|---|
|
format(address)
This function formats a physical address (Address instance) for display.
|
|
|
getFormatInfo(locale, sync, callback)
Return information about the address format that can be used
by UI builders to display a locale-sensitive set of input fields
based on the current formatter's settings.
|
- Parameters:
- {Object} options
- options that configure how this formatter should work Returns a formatter instance that can format multiple addresses.
- Parameters:
- {Address} address
- Address to format
- Returns:
- {string} Returns a string containing the formatted address
The object returned by this method is an array of address rows. Each row is itself an array which may have one to four address components in that row. Each address component is an object that contains a component property and a label to display with it. The label is written in the given locale, or the locale of this formatter if it was not given.
Optionally, if the address component is constrained to a particular pattern or to a fixed list of possible values, then the constraint rules are given in the "constraint" property.
If an address component must conform to a particular pattern, the regular expression that matches that pattern is returned in "constraint". Mostly, it is only the postal code component that can be validated in this way.
If an address component should be limited to a fixed list of values, then the constraint property will be set to an array that lists those values. The constraint contains an array of objects in the correct sorted order for the locale where each object contains an code property containing the ISO code, and a name field to show in UI. The ISO codes should not be shown to the user and are intended to represent the values in code. The names are translated to the given locale or to the locale of this formatter if it was not given. For the most part, it is the region and country components that are constrained in this way.
Here is what the result would look like for a US address:
[
[{
"component": "streetAddress",
"label": "Street Address"
}],
[{
"component": "locality",
"label": "City"
},{
"component": "region",
"label": "State",
"constraint": [{
"code": "AL",
"name": "Alabama"
},{
"code": "AK",
"name": "Alaska"
},{
...
},{
"code": "WY",
"name": "Wyoming"
}
},{
"component": "postalCode",
"label": "Zip Code",
"constraint": "[0-9]{5}(-[0-9]{4})?"
}],
[{
"component": "country",
"label": "Country",
"constraint": [{
"code": "AF",
"name": "Afghanistan"
},{
"code": "AL",
"name": "Albania"
},{
...
},{
"code": "ZW",
"name": "Zimbabwe"
}]
}]
]
Example of calling the getFormatInfo method // the AddressFmt should be created with the locale of the address you // would like the user to enter. For example, if you have a "country" // selector, you would create a new AddressFmt instance each time the // selector is changed. new AddressFmt({ locale: 'nl-NL', // for addresses in the Netherlands onLoad: ilib.bind(this, function(fmt) { fmt.getAddressFormatInfo({ // The following is the locale of the UI you would like to see the labels // like "City" and "Postal Code" translated to. In this example, we // are showing an input form for Dutch addresses, but the labels are // written in US English. locale: "en-US", onLoad: ilib.bind(this, function(rows) { // iterate through the rows array and dynamically create the input // elements with the given labels }) }); }) });
- Parameters:
- {Locale|string=} locale
- the locale to translate the labels to. If not given, the locale of the formatter will be used.
- {boolean=} sync
- true if this method should load the data synchronously, false if async
- {Function=} callback
- a callback to call when the data is ready
- Returns:
- {Array. An array of rows of address components