Deprecated JQuery Library v1.8.1

The UI client uses jQuery and jQuery UI to create 'auto-complete' fields that invoke the Harmony API service methods.

We recommend Harmony API JavaScript client version 2.0.0+, a lightweight vanilla address auto-complete implementation is already included without the dependency on jQuery and jQuery UI.

Pre-requisites

Before you can use the Harmony API client, you must make sure you have:

• An active Harmony API account

• A Harmony API username and password for your domain

Getting the client

The versions of the JavaScript UI client can be downloaded using the following links:

• harmony-ui-1.8.1.min.js

• For any earlier versions of client please contact us.

Configuring the client dependencies

The UI client is dependent on the following JavaScript libraries:

• jQuery 3.5.1+

• jQuery UI 1.12.1+

• Harmony RightAddress JavaScript Client 1.8.1+

These dependencies should be included on the web page before the UI client. In the following example, the three JavaScript files have been downloaded to the 'scripts' folder in the root of the website.

 <!-- Include the JavaScript dependencies -->
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js" type="text/javascript"></script>
    <script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.12.1/jquery-ui.min.js" type="text/javascript"></script>    
    <script src="/scripts/harmony-2.0.1.min.js" type="text/javascript"></script>

    <!-- Include the Harmony RightAddress JavaScript UI client -->
    <script src="/scripts/harmony-ui-1.8.1.min.js" type="text/javascript"></script>

Initialising the client

Before making service requests, the client must be initialised. This is done by invoking the init method on the global Harmony object.

Harmony.init({String} username, {String} password, {String} locale);

This method must be called before any other methods are invoked on the Harmony object.

    <script type="text/javascript">

        Harmony.init("webUser", "password", Harmony.AUSTRALIA);

    </script>

Creating a single-line international address lookup with v2 APIs

Once the Harmony API client has been initialised, lookup fields can be created using the global Harmony.UI object.

The following example creates a international single-line address lookup on a text input with the id 'address' and 'country'.

<script type="text/javascript">

    Harmony.init("webUser", "password", Harmony.AUSTRALIA);
    //pass in custom feature options if applicable. 
    Harmony.useFeatureOptions({"exposeAttributes":0, "groupAddresses":1});
    //pass in Optional parameter for jquery autocomplete.
    var opt = {
        // min 3 chars to trigger the lookup
        minLength:3, 
        // enable Harmony.International.getGeocode for non-AU/NZ countries when address selected.
        getIntlGeocode:true,
        //Override onSelect function if applicable. It is Optional
        onSelect: function(event, ui) {
           console.log('address selected: ' + JSON.stringify(ui.item));
        },
        //Override onIntlGeocode function if applicable. It is Optional
        //e.g. get ui.onIntlGeocodeItem object for address payload after onIntlGeocode call.
        onIntlGeocode: function(event, ui) {
           console.log('geocode address selected: ' + JSON.stringify(ui.onIntlGeocodeItem));
        },
        //Override onRetrieve function if applicable. It is Optional
        //e.g. get ui.onRetrieveItem object for address payload after onRetrieve call.
        onRetrieve: function(event, ui) {
           console.log('onRetrieve address selected: ' + JSON.stringify(ui.onRetrieveItem));
        }
      };

      //specify the sot for AU/NZ address search if applicable, otherwise just pass in null.
      var sot = "GNAF";

      Harmony.UI.addressLookupV2($("#address"), $("#country"), sot, opt);

    </script>

Specifying output fields

As well as performing address lookups, the UI client can output additional fields from the lookups performed. This is done by adding fields using the global Harmony.UI object.

The following example configures a single-line address lookup which then outputs the component parts of the resulting address to separate fields on the page.

    <script type="text/javascript">

        Harmony.init("webUser", "password", Harmony.AUSTRALIA);

        // Configure the address lookup.
        Harmony.UI.addressLookup($("#address"), Harmony.AUPAF);

        // Configure the output fields.
        Harmony.UI.addField(Harmony.POSTCODE, $("#postcode"));
        Harmony.UI.addField(Harmony.LOCALITY, $("#locality"));
        Harmony.UI.addField(Harmony.STREET, $("#street"));
        //add attributes field e.g. latitude and longitude
        Harmony.UI.addField("attributes.Latitude", $("#Latitude"));
    	Harmony.UI.addField("attributes.Longitude", $("#Longitude"));

    </script>

The following example configures two single-line address lookups which then outputs the component parts of the resulting address to separate fields on the page.

    <script type="text/javascript">

        Harmony.init("webUser", "password", Harmony.AUSTRALIA);

        // Configure the address lookup.
        Harmony.UI.addressLookup($("#address"), Harmony.AUPAF);
        Harmony.UI.addressLookup($("#address1"), Harmony.AUPAF, undefined, null, 1);

        // Configure the output fields.
        Harmony.UI.addField(Harmony.POSTCODE, $("#postcode"));
        Harmony.UI.addField(Harmony.LOCALITY, $("#locality"));
        Harmony.UI.addField(Harmony.STREET, $("#street"));

        Harmony.UI.addField(Harmony.POSTCODE, $("#postcode1"), 1);
        Harmony.UI.addField(Harmony.LOCALITY, $("#locality1"), 1);
        Harmony.UI.addField(Harmony.STREET, $("#street1"), 1);

    </script>

When an address is selected from the lookup, the postcode, locality and street fields will automatically be populated with the corresponding values from the selected address.

Additional information

See the Harmony RightAddress JavaScript UI client API documentation for details on configuring the other lookup components.

Extending Library for JQuery

The UI client library acts as a further abstraction wrapper for the Harmony RightAddress JavaScript client. As with the Harmony API JavaScript client, the objects used by the library are JavaScript representations of those found in the Harmony RightAddress service API.

It is recommended to use the current Javascript UI Client Address lookup methods. However the previous version of JavaScript UI Client Address lookup methods are still available.

Constants

Name	Type	Description
Harmony.UI.LOADING	CSS class	The CSS class added to the input element during the service method invocation.
Harmony.UI.OUTPUT	Field	The field used to output any errors that occur during the service method invocation.

Methods

Name	Description
Harmony.UI.addField	Adds a new field specifying the field name (e.g. Harmony.POSTCODE, Harmony.LOCALITY, etc) and the input element.
Harmony.UI.addressLookupV2	Single-line address lookup version 2 for international address lookup on the supplied input element.
Harmony.UI.parseAddress	Parses the value retrieved from the Harmony.ADDRESS field and populates any other specified fields with the results.
Harmony.UI.setOutputElement	Sets the element to use to display the Harmony UI output.

Harmony.UI.addField(field, element, index)

Adds a new field specifying the field name (e.g. Harmony.POSTCODE, Harmony.LOCALITY, etc) and the input element.

field

Type: StringThe name of the field to be added (e.g. Harmony.POSTCODE).

element

Type: ObjectThe input element to be assigned to the field (e.g. document.getElementById("postcodeField")).

index

Type: IntegerThe optional index if there are multiple sets of lookups on the same page (e.g. one for residential addresses and the other one for postal addresses). Currently only available for addressLookupV2.

The following example assigns the Harmony.LOCALITY field to the input element with the ID localityField:

    // Perform the assignment using standard JavaScript.
    Harmony.UI.addField(Harmony.LOCALITY, document.getElementById("localityField"));
  
    // Perform the assignment using a jQuery selector.
    Harmony.UI.addField(Harmony.LOCALITY, $("#localityField"));
    
    /* Perform the assignment using a jQuery selector with index 
       for the second set address lookup. */
    Harmony.UI.addField(Harmony.LOCALITY, $("#localityField"), 1); 

Harmony.UI.addressLookupV2(element, countryElement, sourceOfTruth, opts, index)

Creates international single-line address lookup with v2 APIs on the supplied input and country elements. It returns the response from find service and the callback is available via onSelect option.

For retrieve service, the response is available via ui.onRetrieveItem and the callback is available via onRetrieve option. For internationalGeocode service, if getIntlGeocode options is enabled, the response is available via ui.onIntlGeocodeItem and the callback is available via onIntlGeocode option.

element

Type: ObjectThe input address element to create the lookup for (e.g. document.getElementById("address")).

countryElement

Type: ObjectThe input country element to create the lookup for (e.g. document.getElementById("country")).

sourceOfTruth

Type: StringThe Source of Truth to override the default Australia and New Zealand SOTs. It is optional.(e.g. Harmony.AUPAF for Australia).

opts

Type: ObjectOptional parameter to be passed into the jQuery UI Autocomplete component (e.g. getIntlGeocode true/false to enable international geocode call for the selected address, default is false. And callback functions e.g. onRetrieve and onIntlGeocode in below sample).

index

Type: StringOptional index to indicate which set of fields to populate if there are multiple lookups.

The following example creates a single-line address lookup (use AUPAF for Australian addresses) on the input element with ID singleLineAddress and country and customized opts:

    var opt = {
        // min 3 chars to trigger the lookup
        minLength:3, 
        // enable Harmony.International.getGeocode for non-AU/NZ countries when address selected.
        getIntlGeocode:true,
        //Override onSelect function if applicable. It is Optional
        onSelect: function(event, ui) {
            console.log('address selected: ' + JSON.stringify(ui.item));
        },
        //Override onIntlGeocode function if applicable. It is Optional
        //e.g. get ui.onIntlGeocodeItem object for address payload after onIntlGeocode call.
        onIntlGeocode: function(event, ui) {
            console.log('geocode address selected: ' + JSON.stringify(ui.onIntlGeocodeItem));
        },
        //Override onRetrieve function if applicable. It is Optional
        //e.g. get ui.onRetrieveItem object for address payload after onRetrieve call.
        onRetrieve: function(event, ui) {
            console.log('onRetrieve address selected: ' + JSON.stringify(ui.onRetrieveItem));
        }
    };
    
    // Perform the assignment using a jQuery selector.
    Harmony.UI.addressLookupV2($("#singleLineAddress"), $("#country"), Harmony.AUPAF, opt);

Harmony.UI.parseAddress()

Parses the value entered in the Harmony.ADDRESS field and populates any other specified fields with the parse results.

The following example uses jQuery to assign a click event to a button with the ID parseButton, which then parses the value in the address input and outputs the generated address components into the postcode, locality and street inputs:

    // Add the address field using jQuery selectors.
    Harmony.addField($("#address"), Harmony.ADDRESS);
    
    // Add the output fields using jQuery selectors.
    Harmony.addField($("#postcode"), Harmony.POSTCODE);
    Harmony.addField($("#locality"), Harmony.LOCALITY);
    Harmony.addField($("#street"), Harmony.STREET);
    
    // Use jQuery to generate the click event for the button.
    $("#parseButton").click(function(event) {
        // Perform the parse.
        Harmony.UI.parseAddress();
    });
     

Harmony.UI.setOutputElement(element)

Sets the element to use to display the Harmony UI output.

element

Type: ObjectThe element (can be any type) in which to post the Harmony UI output (e.g. document.getElementById("output")).

The following example sets the output element to the element with the ID outputDiv:

    // Perform the assignment using standard JavaScript.
    Harmony.UI.setOutputElement(document.getElementById("outputDiv"));
  
    // Perform the assignment using a jQuery selector.
    Harmony.UI.setOutputElement($("#outputDiv"));