JavaScript

For any integration, there are two pieces of JavaScript that you need: our JavaScript library and some configuration code. See the tutorial for more details on how to add this code to the page containing your address form.

JavaScript Library

Link to the JavaScript library:

<script src="https://cc-cdn.com/generic/scripts/v1/cc_c2a.min.js"></script>

There are two options for adding the JavaScript library:

Firstly, we host the final, compacted code on a CDN. This means that to add the JavaScript library to your page, you simply need to include this link. We recommend that you use this option, as you will automatically receive updates and bug fixes.

Alternatively, you can download the JavaScript and host it on your own server. You can download the package here from Github.

Basic Configuration Options

These are the basic configuration options that should be included as part of any integration.

accessToken

  • Type: string
  • Values: Your 20 digit code

Using the API requires a 20 character access token, which you should insert here. You will receive an access token when you sign up for an account.

dom

  • Type: object
  • Values: Contains elements to which search is applied

This is an object with DOM element references. By default, it finds elements by name, but this can be changed using domMode.

domMode

  • String: string
  • Values: Property to use to select element: 'name’ , 'id’ , 'class’ or 'object’
  • Default: 'name’

(Optional) Specifies how the elements are passed in to the ‘dom’ object. For example, if this is set to 'id’, you would set the values in the 'dom’ object to the IDs of the form elements.

Example of basic configuration options:

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx', // Replace this with your access token
    dom: {
        search:     'search_field', // 'search_field' is the name of the search box element
        line_1:     'addr_line1',
        line_2:     'addr_line2',
        company:    'company',
        town:       'addr_town',
        postcode:   'addr_postcode',
        county:     'addr_county',
        country:    'addr_country'
    },
    domMode: 'name' // Use names to find form elements
});

Form Elements

Below is a list of the elements that can be included in the 'dom’ object.

The value that each option is set to will be the name, id or class of the element, or the object itself, depending on how the domMode is set. If domMode is not set, element names will be used.

Only 'search’ is required; the others are optional.

  • Type: string
  • Values: name, id or class of element, or object

The input box you want to use for the address search. A user can type a search query into this field and suggestions will be shown below this box as the user types.

line_1

  • Type: string

Address line 1 element

line_2

  • Type: string

Address line 1 element

company

  • Type: string

Company element

town

  • Type: string

Town/city element

postcode

  • Type: string

Postcode/ZIP element

county

  • Type: string

County/state element

country

  • Type: string

Country element

Advanced Configuration Options

These are additional configuration options. None of these are required; if these options are not set then the default value will be used.

Search Box Interface

These options are used to customise the search box interface. You can customise the appearance of the interface, change the country options and even disable the auto-search feature.

gfxMode

  • Type: integer
  • Values:
    • 1: The search interface is displayed below the address search box.
    • 2: The search interface surrounds the search box.
  • Default: 1

Sets the way the search interface is displayed.

style

This object contains options for primary and secondary colors for the search interface.

cssPath

  • Type: string
  • Values: A file path
  • Default: The default CSS file on our CDN

This is the path to the main CSS file that is used for the search box interface.

TIP

If not using our CDN, be careful to set the cssPath. We recommend using an absolute URL, for example:

https://yoursite.com/your_asset_folder/clicktoaddress/cc_c2a.min.css

placeholders

  • Type: bool
  • Values: true, false

Use HTML placeholders on input boxes. (set by 'texts’ object).

texts

List of texts to use for placeholders and labels in the search interface.

  • Type: bool
  • Values: true, false
  • Default: true

Option for showing the clickToAddress logo on the search interface.

historyTools

  • Type: bool
  • Values: true, false
  • Default: true

Show history navigation arrows. These allow a user to go 'back’ and 'forward’ through their search history, meaning the user can view previous search results from an earlier query.

defaultCountry

  • Type: string
  • Values: Any ISO_3 country code.
  • Default: 'gbr'

This option allows you to manually change the default country for the address search. This is the country that will be selected for the user at initialization. If this option is set, it overrides getIpLocation. If it is not set, the default value is overridden by getIpLocation.

getIpLocation

  • Type: bool
  • Values: true, false
  • Default: true

Uses the server to fetch the end-user’s country from the IP address. This country is then selected for the user at initialization. If defaultCountry is set, this option is overridden.

countrySelector

  • Type: bool
  • Values: true, false
  • Default: true

Enable/disable the list of countries in the search interface. If this is disabled, address search will only work for the default country.

enabledCountries

  • Type: array
  • Values: Array of strings
  • Default: All countries

This allows you to restrict the address search to only include certain countries. Only countries in the array are enabled. If the array is not set or empty, all countries are allowed. The format of the strings in the array is set by the countryMatchWith option.

countryMatchWith

  • Type: string
  • Values:
    • 'iso_3’: will match countries to ISO_3 codes in enabledCountries array
    • 'iso_2’: will match countries to ISO_2 codes in enabledCountries array
    • 'text’: fuzzy match to any country detail in enabledCountries array
  • Default: 'iso_3'

How the enabledCountries are set. This sets the format of the strings in the enabledCountries array.

countryLanguage

  • Type: string
  • Values: 'en’, 'de’
  • Default: 'en'

Set the language for the country list in the search interface.

disableAutoSearch

  • Type: bool
  • Values: true, false
  • Default: true

Disables searching as the user types. This can allow the search to be performed manually (for example, by clicking on a button) after the user has entered the search query.

Example using the interface configuration options:

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx', // Replace this with your access token
    dom: {
        search:     'search_field', // 'search_field' is the name of the search box element
        line_1:     'addr_line1',
        line_2:     'addr_line2',
        company:    'company',
        town:       'addr_town',
        postcode:   'addr_postcode',
        county:     'addr_county',
        country:    'addr_country'
    },
    domMode: 'name', // Use names to find form elements
    gfxMode: 1, // Display interface below search box
    style: {
        ambient: 'light', // Use white as main interface color
        accent: 'default' // Use default secondary color for interface
    },
    // Use a custom CSS file
    cssPath: 'https://yoursite.com/your_asset_folder/clicktoaddress/cc_c2a.min.css',
    placeholders: true, // Show placeholders
    texts: {
        default_placeholder: 'Start with post/zip code or street',
        country_placeholder: 'Type here to search for a country',
        country_button: 'Change Country',
        generic_error: 'An error occured. Please enter your address manually',
        no_results: 'No results found'
    },
    showLogo: true, // Show ClickToAddress logo
    historyTools: true, // Show arrows
    defaultCountry: 'gbr', // Sets the default country to the UK
    getIpLocation: true, // Sets default country based on IP
    countrySelector: true, // Country list is enabled
    enabledCountries: ['gbr', 'usa', 'can'], // Enabled countries are the UK, USA and Canada
    countryMatchWith: 'iso_3', // enabledCountries uses ISO_3 codes
    countryLanguage: 'en', // Country list displayed in English
    disableAutoSearch: false // Auto-search is enabled
});

Events

These functions are executed at certain times and can be used to override basic functionality.

onResultSelected

  • Type: function
  • Function Parameters: class object, dom object, result object

Executed after the results are filled in.

onSetCounty

  • Type: function
  • Function Parameters: class object, dom object, county object

Executed instead of filling the county input element.

onError

  • Type: function
  • Function Parameters: code, message

Executed on when an error occurs.

onSearchFocus

  • Type: function
  • Function Parameters: class object, dom object

Executed when the address search input field has focus.

Example usages

  • Use onResultSelected to directly store the result data in an object, send it immediately via Ajax, or to reveal new parts of a form when an address is selected.
  • Use onSetCounty to handle unique county options with special values, to handle cases where special jQuery events need to be triggered, or where the county may need to be filled in multiple places.
  • Use onError where you might want to react to errors in a special way. For example, reveal a form part, or even to detect initialization issues.
  • Use onSearchFocus to part of the form or reveal form fields when the search box is clicked

Example of configuration including functions executed on an event:

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx', // Replace this with your access token
    dom: {
        search:     'search_field', // 'search_field' is the name of the search box element
        line_1:     'addr_line1',
        line_2:     'addr_line2',
        company:    'company',
        town:       'addr_town',
        postcode:   'addr_postcode',
        county:     'addr_county',
        country:        'addr_country'
    },
    domMode: 'name', // Use names to find form elements
    onResultSelected: function(c2a, elements, address){
        // Perform any action here with the available data.
        // For example, you could reveal all the form fields when the fields are filled.
    },
    onSetCounty: function(c2a, elements, county){
        // Perform any action here with the available data.
        // You may want your own function to change the county, depending on your checkout.
    },
    onError: function(code, message){
        // Perform any action here with the available data.
        // For example, you may want to reveal the form fields if there is an error.
    },
    onSearchFocus: function(c2a, elements){
        // Perform any action here with the available data.
        // For example, you may want to  part of the form when the search box is selected.
    }
});

Advanced

relay

  • Type: string

This allows the user to override the URL to the server (for relay purposes).

tag

  • Type: string

This allows the JavaScript to send a unique value that can later be used to identify the request (in logs). We mainly use this to identify our integration packages.

Example of tag:

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx',
    dom: {
        search:     'search_field',
        line_1:     'addr_line1',
        line_2:     'addr_line2',
        company:    'company',
        town:       'addr_town',
        postcode:   'addr_postcode',
        county:     'addr_county',
        country:    'addr_country'
    },
    tag: 'Shopify' // Tag can be used to identify the integration
});

Colors

The 'style’ object contains two keys, which can be used to set the main and secondary colors.

ambient

  • Type: string
  • Values: 'light’, 'dark’
  • Default: 'light’

accent

  • Type: string
  • Values: See the list of possible colors below.
  • Default: 'default’

The following secondary colors are available:

Color Code Color Code Color Code
default red pink
purple deepPurple indigo
blue lightBlue cyan
teal green lightGreen
lime yellow amber
orange deepOrange brown
grey blueGrey

TIP

Colors & the generic design are coming directly from Google’s Material UI. You can always apply custom colors or a unique design to the interface by forking and modifying our CSS file. This set of colors are mainly here to provide an instant theme for most websites.

Example of configuration using custom colors:

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx',
    dom: {
        search:     'search_field',
        line_1:     'addr_line1',
        line_2:     'addr_line2',
        company:    'company',
        town:       'addr_town',
        postcode:   'addr_postcode',
        county:     'addr_county',
        country:    'addr_country'
    },
    style: {
        ambient: 'dark', // Use black as main interface color
        accent: 'deepPurple' // Use deepPurple as secondary color for interface
    }
});

Texts

The 'texts’ object can be used to customize the text that is displayed as part of the search interface.

default_placeholder

  • Type: string
  • Default: 'Start with post/zip code or street’

Placeholder to be displayed in the search box.

country_placeholder

  • Type: string
  • Default: 'Type here to search for a country’

Placeholder to be displayed when searching for a country in search box.

country_button

  • Type: string
  • Default: 'Change Country’

Text to be displayed on button to change country in search interface.

generic_error

  • Type: string
  • Default: 'An error occured. Please enter your address manually’

Text to be displayed when an error occurs.

no_results

  • Type: string
  • Default: 'No results found’

Text to be displayed when no results are found.

Example of configuration with custom texts:

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx',
    dom: {
        search:     'search_field',
        line_1:     'addr_line1',
        line_2:     'addr_line2',
        company:    'company',
        town:       'addr_town',
        postcode:   'addr_postcode',
        county:     'addr_county',
        country:    'addr_country'
    },
    texts: {
        // Placeholder to be displayed in the search box
        default_placeholder: 'Start with post/zip code or street',
        // Placeholder to be displayed when searching for a country in search box
        country_placeholder: 'Type here to search for a country',
        // Text to be displayed on button to change country in search interface
        country_button: 'Change Country',
        // Text to be displayed when an error occurs
        generic_error: 'An error occured. Please enter your address manually',
        // Text to be displayed when no results are found
        no_results: 'No results found'
    }
});

Functions

In many cases, it’s worth storing the result of the class initialization as a variable. Functions can be executed on this variable, such as the attach function.

attach

This function attaches the search functionality to a new set of elements. This allows the developer to initialize the class once, and then apply the search functionality to multiple forms on the same page. The attach function runs by default, if the configuration includes the dom object.

Attach accepts two parameters. The first is the 'dom’ object for the new set of elements. This contains the following parameters:

search

Input box to use for address search

line_1

Address line 1 element

line_2

Address line 2 element

company

Company element

town

Town/city element

postcode

Postcode/ZIP element

county

County element

country

Country element

The second, optional parameter is also an object, and can be used to pass in config overrides for the new “instance” of the address search. Allowed configuration options for this method are:

  • onResultSelected
  • onSearchFocus
  • onSetCounty
  • disableAutoSearch

Basic example of attach - using first parameter only

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

Advanced example of attach - using both parameters

cc = new clickToAddress(config);
cc.attach({
    search:     'search_field',
    town:       'addr_town',
    postcode:   'addr_postcode',
    county:     'addr_county',
    line_1:     'addr_line1'
},
{
    onResultSelected: function(c2a, elements, address){
        // perform action here
    },
    onSetCounty: function(c2a, elements, address){
        // perform action here
    }
});

Error Messages

JS500

Unknown Server Error.

JS501

API server seems unreachable.

JS502

API search request resulted in a JS error.

JS503

API address retrieve request resulted in a JS error.

JS505

API countrylist retrieve request resulted in a JS error.

JS401

Invalid value for countryMatchWith. Fallback to “text”.

WARNING

A special JavaScript variable called cc_debug is also initialized when the function is called. You can set this variable to true, which will result in all errors being reported directly to the developer console. cc_debug is not part of the clickToAddress object; it is a global variable. Its default value is false.

Last Updated: 9/17/2018, 3:33:57 PM