Clients

Harmony RightAddress JavaScript client

The Harmony RightAddress JavaScript client is a JavaScript library that can be included on a web page, allowing website users to connect directly to the Harmony RightAddress services without any server-side processing requirements.

For the best experience, we recommend you to use the latest versions of your favourite browsers.

As of version 1.3.0, the Harmony RightAddress JavaScript client can be configured to use either Cross Origin Resource Sharing (CORS) or JSON with Padding (JSONP). CORS is preferable for modern browsers.
Please note that IE 11 will no longer be supported by Microsoft after August 17th, 2021.

Code snippet

Copy and paste the following code snippet into your web page.


<link rel="stylesheet" href="https://ajax.googleapis.com/ajax/libs/jqueryui/1.12.1/themes/smoothness/jquery-ui.css">
<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="https://common.mastersoftgroup.com/scripts/harmony-1.7.5.min.js" type="text/javascript"></script>

<script>
	$(function() {
		// Use the Production environment
		Harmony.useEnv(Harmony.ENV_PRODUCTION);

		Harmony.init(USERNAME, PASSWORD, Harmony.AUSTRALIA);

		// Use the JSONP protocol
		Harmony.useProtocol(Harmony.JSONP);

		ADDRESS_ID.autocomplete({
			// minimum number of entered characters before trying to search
			minLength:3,
			// miliseconds to wait before trying to search
			delay:500,

			source: function(request, response) {

				Harmony.address({ fullAddress : request.term }, Harmony.AUPAF,
					function(data) {

					var array = [];
					if(data.status == Harmony.SUCCESS) {
						array = $.map(data.payload, function(p) {
							return {
								label: p.fullAddress,
							};
						});
						response(array);
					}
				});
			},
			focus: function(event, ui) {
				// prevent autocomplete from updating the textbox
				event.preventDefault();
				// manually update the textbox
				$(this).val(ui.item.label);
			},
			select: function(event, ui) {
				// prevent autocomplete from updating the textbox
				event.preventDefault();
				// manually update the textbox
				$(this).val(ui.item.label);
			}
		});
	});
</script>

Pre-requisites

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

An active Harmony RightAddress account
A Harmony RightAddress username and password for your domain
A proficiency in JavaScript

Getting the client

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

harmony-1.7.5.min.js
For any earlier versions of client please contact us.

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>

Setting the environment and protocol

During initialisation, the client environment is set to Production and the protocol is set to CORS. To use the Production environment or the JSONP protocol, the useEnv and useProtocol methods can be used.


    <script type="text/javascript">

        // Use the Production environment
        Harmony.useEnv(Harmony.ENV_PRODUCTION);

        // Use the JSONP protocol
        Harmony.useProtocol(Harmony.JSONP);

    </script>

Invoking service requests

Once the Harmony RightAddress client has been initialised, any methods available to the supplied user can be invoked. These methods are invoked using the global Harmony object.

The following example invokes the address method with the single-line address '1 abc street' and the 'AUPAF' Source of Truth. The callback method then output the addresses in a textarea with the id 'output':


    <script type="text/javascript">

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

        Harmony.address({ fullAddress:"1 abc street" }, Harmony.AUPAF,
                function(response) {
                    var outputText = "";

                    // Check if the request was successful.
                    if (response == Harmony.SUCCESS) {

                        // Fill the output text with the single-line address results.
                        for (var i = 0; i < response.payload.length; i++) {
                            outputText += response.payload[i].fullAddress + "\n";
                        }

                    } else {

                        // Fill the output text with the error message(s).
                        for (var i = 0; i < response.messages.length; i++) {
                            outputText += response.messages[i] + "\n";
                        }

                    }

                    // Put the output text in the textarea (with id 'output')
                    document.getElementById("output").value = outputText;
                }
        );

    </script>

See the Harmony RightAddress JavaScript client API documentation for details on invoking the other Harmony RightAddress service methods.