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 versions earlier than 1.8.0 please refer to the previous version of Harmony RightAddress JavaScript Client for code snippet.

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-2.0.1.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) {
            // call find method to get a list of candidate.
            Harmony.v2.find({ fullAddress : request.term, country: "au" }, 
                Harmony.AUPAF,
                function(data) {

                var array = [];
                if(data.status == Harmony.SUCCESS) {
                    array = $.map(data.payload, function(p) {
                        return {
                            label: p.fullAddress,
                            id: p.id
                        };
                    });
                    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();
            // call retrieve method to get additional information of the address
            Harmony.v2.retrieve({id: ui.item.id}, function(responseData) {
                $(this).val(ui.item.label);
                console.log(JSON.stringify(responseData));
            });
        }
    });
});
</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-2.0.1.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 find method with the single-line address '1 abc street' in Canada. 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.v2.find({ fullAddress:"1 abc street" , country: "ca"}, null,
                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.