Harmony RightAddress JavaScript UI client API

The UI client library acts as a further abstraction wrapper for the Harmony RightAddress JavaScript client. As with the Harmony RightAddress 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: String The name of the field to be added (e.g. Harmony.POSTCODE).

element

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

index

Type: Integer The 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 addressLookup.

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.

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: Object The input address element to create the lookup for (e.g. document.getElementById("address")).

countryElement

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

sourceOfTruth

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

opts

Type: Object Optional 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: String Optional 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: Object The 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"));