The UI client is an even easier way of configuring a web page to use Harmony RightAddress.
The UI client uses jQuery and jQuery UI to create 'auto-complete' fields that invoke the Harmony RightAddress service methods.
Please note: Since Harmony RightAddress JavaScript client version 2.0.0 (harmony-2.0.0.min.js), a lightweight vanilla address auto-complete implementation is already included without the dependency on jquery and jQuery UI. Please refer to Harmony RightAddress Autocomplete JavaScript client API for more details.
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.
Before you can use the Harmony RightAddress client, you must make sure you have:
The versions of the JavaScript UI client can be downloaded using the following links:
The UI client is dependent on the following JavaScript libraries:
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>
For the jQuery UI styles to work correctly, the stylesheets should also be included on the web page.
<!-- Include the jQuery UI stylesheets -->
<link rel="stylesheet" href="https://ajax.googleapis.com/ajax/libs/jqueryui/1.12.1/themes/smoothness/jquery-ui.css">
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>
Once the Harmony RightAddress 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>
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.
See the Harmony RightAddress JavaScript UI client API documentation for details on configuring the other lookup components.