Comment on page
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.
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
The versions of the JavaScript UI client can be downloaded using the following links:
- For any earlier versions of client please contact us.
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>
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 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>
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.
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.
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. |
Name | Description |
---|---|
Adds a new field specifying the field name (e.g. Harmony.POSTCODE , Harmony.LOCALITY , etc) and the input element. | |
Single-line address lookup version 2 for international address lookup on the supplied input element. | |
Parses the value retrieved from the Harmony.ADDRESS field and populates any other specified fields with the results. | |
Sets the element to use to display the Harmony UI output. |
Adds a new field specifying the field name (e.g.
Harmony.POSTCODE
, Harmony.LOCALITY
, etc) and the input element.Type: StringThe name of the field to be added (e.g.
Harmony.POSTCODE
).Type: ObjectThe
input
element to be assigned to the field (e.g. document.getElementById("postcodeField"))
.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);
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.Type: ObjectThe
input
address element to create the lookup for (e.g. document.getElementById("address")
).Type: ObjectThe
input
country element to create the lookup for (e.g. document.getElementById("country")
).Type: StringThe Source of Truth to override the default Australia and New Zealand SOTs. It is optional.(e.g.
Harmony.AUPAF
for Australia).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).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);
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();
});
Sets the element to use to display the Harmony UI output.
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"));
Last modified 1yr ago