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.
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-1.7.5.min.js" type="text/javascript"></script>
<!-- Include the Harmony RightAddress JavaScript UI client -->
<script src="/scripts/harmony-ui-1.7.5.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 an AUPAF single-line address lookup on a text input with the id 'address':
<script type="text/javascript">
Harmony.init("webUser", "password", Harmony.AUSTRALIA);
Harmony.UI.addressLookup($("#address"), Harmony.AUPAF);
</script>
The following example creates an AUPAF single-line address lookup on a text input with the id 'address' and id 'state' to filter addresses with a certain state:
<script type="text/javascript">
Harmony.init("webUser", "password", Harmony.AUSTRALIA);
Harmony.UI.addressLookup($("#address"), Harmony.AUPAF, undefined, $("#state"));
</script>
The following example creates two AUPAF single-line address lookups on a text input with the id 'address' and 'address1':
<script type="text/javascript">
Harmony.init("webUser", "password", Harmony.AUSTRALIA);
Harmony.UI.addressLookup($("#address"), Harmony.AUPAF);
Harmony.UI.addressLookup($("#address1"), Harmony.AUPAF, undefined, null, 1);
</script>
Multiple lookup components can be defined on a single web page and they are automatically linked to the other components on the same page.
For example, if a postcode lookup and locality lookup are defined, selecting a postcode from the
lookup will automatically populate the locality field as well (and vice versa).
The following example creates three lookup components for GNAF: a postcode lookup, a
locality lookup and a street lookup:
<script type="text/javascript">
Harmony.init("webUser", "password", Harmony.AUSTRALIA);
Harmony.UI.postcodeLookup($("#postcode"), Harmony.AUPAF);
Harmony.UI.localityLookup($("#locality"), Harmony.AUPAF);
Harmony.UI.streetLookup($("#street"), Harmony.AUPAF);
</script>
A user will be able to use the above example to find a street by drilling down through the postcode and locality values.
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.