Plugin events

The website plugin is event-based. Custom events are raised throughout the lifetime of the script, particularly during the address verification process.

The plugin uses these events internally, so even though these are like regular events used in Javascript, you should use the plugin's on() function to intercede so that your own handler is executed first. For example:

liveaddress.on("AddressAccepted", function(event, data, previousHandler)
{
	if (data.response.isMissingSecondary())
	{
		data.address.abort(event);
		alert("Don't forget your apartment number!");
	}
	else
		previousHandler(event, data);
});

Notice previousHandler in the above example. When you run a custom handler, you intercept the event. Calling previousHandler passes the event back to the original handler so it will run. In this example, previousHandler is placed inside of an else statement, because we want to pass the event back to the original handler only if the address is not missing a secondary number (an apartment or suite number). In most cases an else statement will not apply; you will want to call previousHandler(event, data) unconditionally.

We have created additional event handlers that you can use as a starting point.

Table of events

Event name Possible Data Description
First, these fire in basically this order:
FieldsMapped Process which maps address fields to elements on the page is complete.
MapInitialized Mapped addresses are now wired up to their input/UI elements and are ready and waiting.
AutocompleteInvoked input, addr, streetField, containerUi A request is about to be made to the auto-complete service.
AutocompleteReceived input, addr, streetField, containerUi, json A response was just received from the auto-complete service.
AddressChanged address, field, sourceEvent, suppressAutoVerification, value A field's internal value within an address object has changed, usually because the user typed or changed their input in any mapped address field, or .set() was called on an Address object.
AutocompleteUsed addr, suggestion A suggested address was used from the autocomplete service. Fires after RequestSubmitted if autoVerify is set to false due to asynchronicity.
VerificationInvoked address The verification process for an address is about to begin.
RequestSubmitted address An address was just sent to SmartyStreets API (asynchronously).
ResponseReceived address, response, invoke Response was barely received for an address; it is not yet examined.
RequestTimedOut address, invoke, status This event fires only if no response is received after a period of time.
Then any one of these, upon initial examination of the response:
AddressWasValid address, invoke, response The address matched only one valid address with no ambiguity.
AddressWasAmbiguous address, invoke, response, selectors The address matched at least two valid addresses, and ambiguity will need to be resolved.
AddressWasInvalid address, invoke, response, selectors The input could not be matched to any valid addresses; empty response.
AddressWasMissingInput address, invoke, response, selectors The input was missing input required for verificaiton (e.g., country, address1, locality, administrative area, postal code).
AddressWasMissingSecondary address, invoke, response, selectors The input was missing a secondary number (e.g., apartment number, suite number).
If the input is ambiguous, invalid, missing a secondary number, or missing input, these could happen:
OriginalInputSelected address, invoke, response The user chose to use their own input even though it's not valid (applies to: ambiguous or invalid).
UsedSuggestedAddress address, chosenCandidate, invoke, response User chose a suggested candidate address (applies to: ambiguous).
InvalidAddressRejected address, invoke, response User chose to go back to try fixing the bad address (applies to: invalid).
In the end...
AddressAccepted address, invoke, response An address was flagged as accepted; we're done with it unless it changes.
Completed address, invoke, response The process is finished, at least for now (or the user aborted).

Having trouble?

Take a look at these troubleshooting tips we put together with lots of love.


Product Features Demo Pricing Help Company Documentation Articles Contact Customers Legal Stuff