# new AddressFmt(options)
Parameters:
| Name | Type | Description |
|---|---|---|
options |
Object
|
options that configure how this formatter should work Returns a formatter instance that can format multiple addresses. |
Methods
# format(address) → {string}
This function formats a physical address (Address instance) for display. Whitespace is trimmed from the beginning and end of final resulting string, and multiple consecutive whitespace characters in the middle of the string are compressed down to 1 space character.
If the Address instance is for a locale that is different than the locale for this formatter, then a hybrid address is produced. The country name is located in the correct spot for the current formatter's locale, but the rest of the fields are formatted according to the default style of the locale of the actual address.
Example: a mailing address in China, but formatted for the US might produce the words "People's Republic of China" in English at the last line of the address, and the Chinese-style address will appear in the first line of the address. In the US, the country is on the last line, but in China the country is usually on the first line.
Parameters:
| Name | Type | Description |
|---|---|---|
address |
Address
|
Address to format |
Returns a string containing the formatted address
string
# getFormatInfo(locale, syncopt, callbackopt) → {Array.<Object>}
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.
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"
}]
}]
]
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
locale |
Locale
|
string
|
the locale to translate the labels to. If not given, the locale of the formatter will be used. |
|
sync |
boolean
|
<optional> |
true if this method should load the data synchronously, false if async |
callback |
function
|
<optional> |
a callback to call when the data is ready |
An array of rows of address components
Array.<Object>
Example
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) {
// 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.
fmt.getAddressFormatInfo("en-US", true, ilib.bind(this, function(rows) {
// iterate through the rows array and dynamically create the input
// elements with the given labels
}));
})
});