Advanced API Setup
For more advanced setup options, use the API-based setup, rather than the setup wizard. This can be useful when implementing specific AddressComplete behaviour on the selection of an address.
Based on the form layout shown below:
<div class="input-line">
<label for="street-address">Address</label>
<input id="street-address" type="text" placeholder="Street address" autofocus />
</div>
<div class="input-line">
<label for="street-address2"></label>
<input id="street-address2" type="text" placeholder="" />
</div>
<div class="input-line">
<label for="city"></label>
<input id="city" type="text" placeholder="City" />
</div>
<div class="input-line">
<label for="state"></label>
<input id="state" type="text" placeholder="State/Province" />
</div>
<div class="input-line">
<label for="postcode"></label>
<input id="postcode" type="text" placeholder="Zip/Postcode" />
</div>
<div class="input-line">
<label for="country"></label>
<input id="country" type="text" placeholder="Country" />
</div>
<div class="input-line">
<label for="multi-unit"></label>
<input id="multi-unit" type="text" placeholder="Multi-Unit-Indicator" />
</div>
<div class="input-line">
<label for="residential-business"></label>
<input id="residential-business" type="text" placeholder="Residential/Business" />
</div>
A typical API setup might look like below.
Note: If you want to use the extra flags we offer, you can map these as shown below. Make
sure you include the curly braces when setting the field value.
<script type="text/javascript">
var fields = [
{ element: "search", field: "", mode: pca.fieldMode.SEARCH },
{ element: "street-address", field: "Line1", mode: pca.fieldMode.POPULATE },
{ element: "street-address2", field: "Line2", mode: pca.fieldMode.POPULATE },
{ element: "city", field: "City", mode: pca.fieldMode.POPULATE },
{ element: "state", field: "ProvinceName", mode: pca.fieldMode.POPULATE },
{ element: "postcode", field: "PostalCode" },
{ element: "country", field: "CountryName", mode: pca.fieldMode.COUNTRY }
{ element: "multi-unit", field: "{AcMua}", mode: pca.fieldMode.POPULATE },
{ element: "residential-business", field: "{AcRbdi}", mode: pca.fieldMode.POPULATE }
],
options = {
key: "AA11-AA11-AA11-AA11"
},
control = new pca.Address(fields, options);
</script>
The parts of this setup are as follows:
- fields
This array is where the fields that AddressComplete uses are defined: element is the id of the element you want to use, field is the AddressComplete field to associate with that element, and mode allows you to select the mode the field will operate in. (See Field Modes below) - options
This is where the options for the AddressComplete control are defined - control
This is where the AddressComplete instance is initiated using pca.Address(fields, options)
Options
- key (required)
The key used to authenticate the request. This can be copied from the code sample of an AddressComplete installation. - name
A reference for the control used as an id to provide ARIA support. - populate
Defaults to true. Used to enable or disable population of all fields. - onlyInputs
Defaults to false. Only input fields will be populated. - autoSearch
Defaults to false. Search will be triggered on field focus. - prompt
Defaults to false. Shows a message to prompt the user for more detail. - promptDelay
Defaults to 0. The time in milliseconds before the control will prompt the user for more detail. - setCursor
Defaults to false. Updates the input field with the current search text. - minSearch
Defaults to 1. Search will be triggered on field focus. - maxItems
Defaults to 0. The maximum number of items to show (0 = disabled). - manualEntry
Defaults to false. If no results are found, the message can be clicked to disable the control. - disableTime
Defaults to 60000. The time in milliseconds to disable the control for manual entry. - suppressAutocomplete
Defaults to true. Suppress the default browser field autocomplete on search fields. - setCountryByIP
Defaults to false. Automatically set the country based upon the user IP address. - culture
Force set the culture for labels, e.g. "en-us", "fr-ca". - languagePreference
The preferred language for the selected address, e.g. "eng", "fra".
Field Modes
- pca.fieldMode.DEFAULT
This is the default mode and combines the actions of SEARCH and POPULATE. - pca.fieldMode.POPULATE
This mode will populate the element with the AddressComplete field when a user selects an address. Typing in this field will not trigger an AddressComplete search. - pca.fieldMode.COUNTRY
This mode indicates a country selector. This can be used to select the country for AddressComplete to search in. - pca.fieldMode.SEARCH
This sets the field to an AddressComplete search field. Typing in this field will trigger searching via the AddressComplete control. - pca.fieldMode.NONE
This field will be ignored. - pca.fieldMode.PRESERVE
This prevents the field from being overwritten by AddressComplete.
Advanced AddressComplete Options
Triggering events when an address is returned
When an AddressComplete lookup returns an address, you may wish to trigger an event on your page, such as a success message. To do so, insert the following code into the header of your page, and include the event in the relevant section of the code.
<script type="text/javascript">
addressComplete.listen('load', function(control) {
control.listen("populate", function (address) {
//add custom code here
});
});
</script>
Accessing the contents of the response from an address retrieve request
The contents of the response from an AddressComplete request can be accessed and then manipulated if you need to use the various elements of the address. Insert the code below into your page and then modify to access the relevant part of the address object (for example, in the example below: “Postcode”).
<script type="text/javascript">
addressComplete.listen('load', function(control) {
control.listen("populate", function (address) {
document.getElementById("line1").value = address.Line1;
});
});
</script>
Address Complete altering/stretching your form
Depending on the layout and styling of your page, Address Complete might stretch the elements of your form, especially if they are very short. To avoid this, put the AddressComplete control into a div fixed to the same width as your fields. This can be done by using code like this:
<script type="text/javascript">
addressComplete.listen('ready', function() {
addressComplete.setWidth(300);
addressComplete.setHeight(300);
});
</script>
Changing drop-down font colour/size
To change the colour and font of the text that appears in the Address Complete search drop-down box, insert this code into the header of the page:
<style type="text/css">
.pca .pcatext {
font: 15px Verdana;
color: #4682b4;
}
</style>
Enabling/disabling the control dynamically
On some pages you may want to control when the AddressComplete lookup control is loaded, rather than it always being operational. Use the code below to enable/disable the control.
<script type="text/javascript">
addressComplete.listen('ready', function() {
addressComplete.enable();
addressComplete.disable();
});
</script>
Setting the country dynamically
You may wish to set the country for the AddressComplete control dynamically, either because of selections users have made, or the page they’re on. This will over-ride the default functionality that selects the country based upon the user’s IP address. Use the code below.
<script type="text/javascript">
addressComplete.listen('ready', function() {
addressComplete.setCountry("France");
});
</script>
Locations you don’t want to deliver to
If you have some areas that you can’t deliver to then you may want to indicate this to your customers when they do their address lookup. The code below illustrates how this can be achieved by looking at a province in the response from the address lookup and displaying an appropriate error message when addresses in a specific province are returned. This could be adapted for other address elements such as cities or Postal Codes.
<script type="text/javascript">
addressComplete.listen('load', function(control) {
control.listen("populate", function (address) {
if ( address.ProvinceCode == "ON" || address.ProvinceCode == "QC") {
//EXAMPLE – do not deliver to ON or QC
alert("Sorry we do not deliver to this address");
}
});
});
</script>
Setting additional control options
You can override additional control options in order to change its style further.
<script type="text/javascript">
addressComplete.listen('options', function(options) {
options.bar = options.bar || {};
options.bar.showCountry = false;
options.bar.showLogo = true;
options.bar.logoLink = false;
});
</script>
Setting the language of the control
You can set the language of the control UI at any time to suit your current page language culture.
<script type="text/javascript">
addressComplete.listen('ready', function() {
addressComplete.setCulture("fr-CA");
});
</script>
Changing the text of messages in the control
You can set the content of the messages displayed to users.
<script type="text/javascript">
pca.messages.en.DIDYOUMEAN = "Did you mean:";
pca.messages.en.NORESULTS = "No results found";
pca.messages.en.KEEPTYPING = "Keep typing your address to display more results";
pca.messages.en.RETRIEVEERROR = "Record could not be retrieved";
pca.messages.en.SERVICEERROR = "Service Error:";
pca.messages.en.COUNTRYSELECT = "Select Country";
pca.messages.en.NOLOCATION = "Sorry, we could not get your location";
pca.messages.en.NOCOUNTRY = "Sorry, we could not find this country";
</script>
Current version: 2.3
