Customising Address Lookup

Our Address Finder JavaScript code has a range of settings that can be tweaked to adjust the functionality to match your website’s needs.

Layout Options

The code itself supports two different layouts via CSS.

The interface can be placed underneath the search field (default): under

new clickToAddress({
    /*core code
    ...
    */
    gfxMode: 1
});

Or it can surround the field:

final-surround

new clickToAddress({
    /*core code
    ...
    */
    gfxMode: 2
});

Styling Options

There are a number of built-in styling options to easily make the interface dark or light, and to change the highlighted text to one of our pre-defined styles.

Examples:

dark-orange

new clickToAddress({
    /*core code
    ...
    */
    style: {
        ambient: "dark",
        accent: "deepOrange"
    }
});

final-light-default

new clickToAddress({
    /*core code
    ...
    */
    style: {
        ambient: "light",
        accent: "default"
    }
});
  • Note: The style object will expect both the ambient and accent property to be defined.
  • For the full list of available styles, check out our API Documentation.
  • If you want to go beyond the built-in styles, you can take a look at our CSS structure on GitHub. You can either include an extra css file to override our styling, or add the cssPath parameter to pass in a URL for your own CSS, instead of using the default CDN url.

Restricting the Country List

By default, all available countries are shown. To limit usage to a smaller subset of countries, you can pass in an array of countries in the configuration.

For example, you can limit the enabled countries by ISO 3166 Alpha-2 (2 letter) or ISO 3166 Alpha-3 (3 letter) country codes:

new clickToAddress({
    /*core code
    ...
    */
    countryMatchWith: "iso\_2",
    enabledCountries: ["pl", "hu", "uk"]
});

Or by naming the countries in full:

new clickToAddress({
    /*core code
    ...
    */
    countryMatchWith: "text",
    enabledCountries: ["Poland", "Hungary", "United Kingdom"]
});
  • The countryMatchWith parameter tells the JavaScript class how to match the enabledCountries list against the full list of available countries. You can set it to “iso_2”, “iso_3” (default) or “text”. While “iso_2” and “iso_3” restricts the search to exact ISO 3166 country short codes, “text” searches in all known names in the country list.
  • Note: If you choose the text option, always type in the full name of the country to avoid partial matches.
  • List of ISO 3166 Alpha-2 and Alpha-3 country codes

Events and Triggers

If you need to further process the data you receive from the API or if you need to trigger events on certain user actions, you can attach functions to be called by the JavaScript class.

Event: onResultSelected

This event is triggered after an address has been selected.

The sample below shows you how to trigger custom code to let jQuery know the country field has changed after the user selects an address:

new clickToAddress({
    /*core code
    ..
    */
    onResultSelected: function(c2a, elements, address){
        //do something useful, like trigger the country change event
        jQuery(elements.country).trigger('change');
    }
});

The method to call the other two functions is exactly the same for the other two options.

  • Sometimes it’s necessary to trigger a browser event (for example, a change event on the country dropdown) if you have a code that would do something based on that user action. Most e-commerce solutions have dynamic form validation triggering on such events, and might prevent the user from advancing to the next stage of checkout unless these events are triggered.
  • There are always 3 parameters passed in to these functions:
    1. the first object is the address lookup javascript object itself
    2. the second object is the object that contains the passed in dom elements
    3. the third object contains all the details to the selected address
  • It is possible to configure the JavaScript class with just the search element defined. Use onResultSelected to retrieve all the address details via JavaScript.

Event: onCountyChange (States and Counties)

This event’s main purpose is to provide a way to trigger custom code instead of executing the default county / state matching algorithm. By default, the JavaScript applies a fuzzy matching algorithm, that tries to find the most similar county / state name in your dropdown (if required).

However, there might be some cases when matching this way is just not efficient or viable. For example, custom translated county lists or if the way of storing the county / state requires a JavaScript action.

If you set this event, the county won’t be set by our code. Only the supplied custom code will be executed.

How to Apply the Address Lookup to Multiple Forms on the Same Page

Using the attach function of the clickToAddress class, you can specify a new object that the interface will also attach itself to (as if you were passing it in via the dom parameter).

Using this functionality is mandatory if you need to apply the functionality to multiple forms on the same page, as you cannot initialize the class twice.

cc = new clickToAddress(config);
cc.attach({
    search:     'search_field',
    town:       'addr_town',
    postcode:   'addr_postcode',
    county:     'addr_county',
    line_1:     'addr_line1'
});
cc.attach({
    search:     'search_field-2',
    town:       'addr_town-2',
    postcode:   'addr_postcode-2',
    county:     'addr_county-2',
    line_1:     'addr_line1-2'
});

Complete Code Example

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx',
    dom: {
        search:     'search-bar',
        town:       'address-town',
        postcode:   'address-zip',
        line_1:     'address-line-1',
        line_2:     'address-line-2',
        country:    'address-country'
    },
    domMode: 'id',
    style: {
        ambient: 'dark',
        accent: 'default'
    },
    gfxMode: 2,
    countryMatchWith: 'iso\_3',
    enabledCountries: ['GBR','SWE','AUS'],
    onResultSelected: function(c2a, elements, address){
        console.log("Congratulations, You just picked an address!");
    },
    onCountyChange: function(c2a, elements, address){
        console.log("County Changed");
    }
});
Last Updated: 9/6/2018, 11:26:17 AM