This is an archived page. The information on this archived page is no longer current.
Plugin functions
This plugin is deprecated and will receive no continued development.
After initializing the plugin, a variety of functions are available to you in the returned object.
On this page
Functions
.activate(addressID)
"Turns on" an address identified by addressID
(given during mapping) so that it will be verified
when the form is submitted or the address changes. Usually called sometime after deactivate
is called.
.autoVerify([newSetting])
Pass in true
or false
to turn autoVerify on or off, respectively. Pass in nothing to
simply return the current setting. See more about autoVerify here.
.deactivate([addressID])
"Turns off" an address identified by addressID
(given during mapping) so it won't be verified when
it changes or when the form is submitted. This "soft" deactivation can be reversed by calling activate with the appropriate addressID
. If nothing is passed in, this
deactivates the plugin entirely. (Mapped addresses, address IDs, etc. are destroyed.) This is a "hard"
deactivation. Reactivating the entire plugin requires either remapping using the mapFields function or reinstantiating the plugin. This function is useful for web
pages that have dynamic forms that are sometimes visible and sometimes not. See an example here.
.getMappedAddressByID(addressID)
Returns an Address object with specified addressID
(given during mapping)
that is mapped to a form. This function is mostly used internally by the plugin itself, but it can be used if
the user needs to manipulate the address in some custom way.
.getMappedAddresses()
Returns an array of Address objects that are mapped to forms. Similar purpose as getMappedAddressByID. Mostly for internal purposes.
.makeAddress(addressData)
Returns a new Address object. addressData
should be a string containing the
entire address or an object mapping fields to values. For instance: liveaddress.makeAddress({ street: "123
Main St", city: "Schenectady", state: "New York", zipcode: "12345" });
. Addresses constructed in this
manner are independent of any mapped fields. You won't usually need this.
.mapFields([map])
Maps form fields to the type of data they contain. Specify your own field mapping with CSS selectors. Pass in nothing to use the mapping from initialization or your own field mapping to use that. Overwrites any existing mapping. Can be useful for dynamic forms.
.on(eventName, callback)
Similar to jQuery's on
function, this is specifically for binding your own handlers to our plugin's
custom events. The benefit of using this on
function instead of jQuery's is that your handler will
be fired first instead of last. See the events documentation
for more information and examples. Make sure to call previousHandler(event, data);
in order for the
normal plugin functionality to still occur after you intercept the event.
.setCityFilter(cities)
Changes the city filter for autocomplete suggestions.
cities
should be a list of city names, separated by commas.
.setCityStatePreference(preferred)
Changes the preference for autocomplete suggestions.
preferred
should be a list of city and state pairs where the city and state are separated by a
comma and each pair is separated by a semicolon.
.setKey(key)
Changes the website key used to authenticate requests. Seldom used outside of certain debugging scenarios or maybe in private-labeling situations.
.setStateFilter(states)
Changes the state filter for autocomplete
suggestions. states
should be a list of state names, separated by commas.
.verify(address | addressID[, callback(response)])
Performs a request to the API given an input address and invokes the callback, giving it a Response
object. address
can be a string (containing a single-line address) or an object where keys are
fields and values are the address data. (Do not use an actual Address object.) Instead of
an address, you can provide an addressID
. You can use this function to programmatically click the
"Verify" button. This function is asynchronous and does not return a value. If you are considering using this
function to simply verify an address, we recommend making calls to our US
Street Address API or
International Street Address API instead.
Mapping fields
Set up the plugin by specifying field mapping. A contrived example that maps two addresses, one using all available fields and another using just one field, is shown below:
$.LiveAddress({
key: 'YOUR_WEBSITE_KEY_HERE',
addresses: [{
id: 'billing', // IDs are not part of the address
address1: '#street1',
address2: '#street2', // Not all these fields are required
locality: '#city',
administrative_area: '#state',
postal_code: '#zip',
country: '#country'
},
{
id: 'shipping', // IDs are optional, but can be helpful
freeform: '#entireAddress',
country: '#country2'
}]
});
This example shows a field mapping during initialization, but you can pass the same kind of array into the mapFields function.
Notice that we specify fields using CSS selectors. It's usually easiest to give your fields an ID and then use
the CSS ID selector (the #
symbol) to express the specific DOM elements to bind to. All
mapped fields must be inside a <form> tag; no exceptions.
Mandatory fields (US target)
address1
+ locality
+ administrative_area
address1
+ postal_code
freeform
Mandatory fields (International target)
address1
+ locality
+ administrative_area
+ country
address1
+ postal_code
+ country
freeform
+ country
Table of Fields
Name | Description |
---|---|
id
|
The ID that you set to identify the address. |
address1
|
The first line of the address. |
address2
|
The second line of the address. |
address3
|
The third line of the address. |
address4
|
The fourth line of the address. |
locality
|
The locality or city. |
administrative_area
|
The administrative area or state. |
postal_code
|
The postal code or ZIP Code. |
country
|
The country. |
freeform
|
The freeform field. This is used when the entire address is on one line. Used in place of a address1
+ locality + adminstrative_area combination. Must be used with the country
mapping field when dealing with international addresses.
|
match
|
The match field. See more here. |
Address object
Address objects represent input (un-verified) addresses. They are obtained by calling makeAddress or are received by argument in an event handler.
Properties
-
active
If
true
, the address is activated. Iffalse
, the address is deactivated. See the activate and deactivate functions for more information. -
form
The form object that the address is mapped to. Multiple addresses can be associated with a single form, but usually it is just one.
-
lastField
The last input field that is associated with the address. Usually is the ZIP Code, but can be the city/state/zip (last line), street (freeform), or country fields depending on your form.
-
lastStreetInput
The value of what is typed in the input field mapped as the street value. Used for autocomplete to detect changes.
-
verifyCount
The number of times that the address has been verified.
Table of functions
Function | Description |
---|---|
.abort(event [,keepAccept])
|
Resets an address, so to speak, so that it can be run through the verification process again from the
beginning. This is often used in your own event handlers when you want to abort the verification
process. Pass in the event to make sure it stops firing other handlers. This function will automatically
"un-accept" the address. If you want the address to stay "accepted" for some reason, set the second
argument to true . See events.
|
.accept([data, showVerified])
|
Marks the address as "accepted" (whether it was verified or not). Forms won't submit until every address
is accepted. If intervening with an event handler, pass through the data to the next event.
By default, calling this will turn the status indicator green. Set the second argument to false to
prevent that.
|
.countryISO()
|
Returns the 3-digit ISO code that corresponds to the country associated with the address. |
.enoughInput()
|
Returns true if the address has enough data to be submitted for verification, false otherwise. This check is done implicitly during verification anyway. If verification is invoked and this is true, the user will be notified of which input is missing. |
.get(field)
|
Gets the value stored within the address by field name, such as "address1," "postal_code," etc. See US output fields and international output fields. |
.getDomFields()
|
Returns an associative array (an object) which contains references to the DOM elements for the fields in the address, if there are any. |
.hasDomFields()
|
Returns true if the address has DOM elements associated with any of its fields. |
.id()
|
Returns the unique ID associated with this Address object. |
.isDomestic()
|
Returns true if the address is detected to be in the United States; false otherwise. |
.isFreeform()
|
Returns true if the address is considered to be a freeform (or "single-line") address, where all the data is contained in the "freeform" field and country in the "country" field. Returns false otherwise. |
.replaceWith(
|
Replaces the values in the address with those found in replacement , which is an object
returned from the API. (The API's raw response is an array of JSON objects; pass in just one of those
objects. If an array of objects is passed in, the first object is used.) Set
updateDomElement to true to update any DOM element values associated with the address, and
event can be the event which initiated the request.
|
.set(field, value[, updateDomElement, keepState, sourceEvent]
|
Sets the value of field in the address to value . If
updateDomElement is true, the value of the field on the DOM (if there is one) will be
updated. If keepState is true, the state of the address ("changed" or "accepted") will not
be changed. sourceEvent may be an event object which caused this change to happen.
|
.status()
|
Gets the state of the address, whether it is "changed" or "accepted." |
.undo(
|
For each field in the address, switches the current value with the previous value. If the argument is true or undefined, the value of the DOM element associated with each field (if any) will be updated to reflect the change. |
.verify([callback])
|
Invokes verification on this address. Supply an optional callback function to which the Response will be passed if the request succeeds. If you supply a callback, events will stop firing for this verification process once a response is received; it will be up to your callback to handle the response after that point. (The address is not automatically updated to reflect the verification results.) |
.toRequestInternational()
|
Returns an object mapping fields to values, ready to submit to the international API. Use this to "convert" the address object to a format accepted by the international API. |
.toRequestUS()
|
Returns an object mapping fields to values, ready to submit to the US API. Use this to "convert" the address object to a format accepted by the US API. |
.toString()
|
Returns a string representation of the values for each field of the address (separated by spaces). |
.unaccept()
|
Marks the address as "changed" (thus, not accepted) and raises the associated event. |
Response object
Response objects are obtained by calling verify or are received by argument to an event handler. They contain the raw output of the API and some helpful wrapper functions to make the output easier to interpret and use.
Properties
-
length
The number of raw elements.
-
raw
The raw output from the API. This will always be an array of matching candidates. Use this property to access data about particular candidates returned from the API. For example:
response.raw[0].metadata.latitude
Table of functions
All the following functions return true/false and may optionally be passed an index from 0 to n-1, where n is the number of candidates returned. If no index is passed in, then 0 is assumed.
Function | Description |
---|---|
.isInvalid() |
The address is considered invalid (only one candidate returned). |
.isValid() |
The address is considered valid (only one candidate returned). |
.isAmbiguous() |
The address is considered ambiguous (more than one candidate returned). |
.isMissingSecondary() |
The address is valid, but is missing a secondary (unit/apartment/suite) number. |
Having trouble?
Take a look at these troubleshooting tips we put together with lots of love.