About TerraPages AddressHelper

AddressHelper is a feature packed web based application component that can be used to obtain addresses which are validated against the G-NAF dataset.

Besides validating addresses against the G-NAF dataset, AddressHelper can:

Retrieve Suburb and Street Name Aliases (Alias information is where a Suburb or Street Name may be known as another name.)
Retrieve Geospatial Coordinates for a particular address
Return an address and its coordinates in an OpenLS XML format
Automatically TAB to the next field once a selection has been made
Retrieve as many or as little results as the user wishes
Configure the window size that AddressHelper creates
Enable/Disable address detail elements
Alter the layout
Configure the delay before retrieving suggestions
Display a clear button to clear data entered by the user
Display in a free form picklist, matching addresses based on the users input
Insert custom style sheets
Display the data entered by the user in free form
Copy data entered in the window to the parent form

All the points listed above are completely configurable by the user and they can turn these on and off at their desire.
To use AddressHelper in your web application, all you need to do is add the folowing into a new HTML page.

		
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<script type="text/javascript" src="InitAddressHelper.js"></script>
<script type="text/javascript" src="AddressHelper.js"></script>
<title>TerraPages Address Helper</title>
</head>
<body>
<div id="AddressHelper"></div>
<script>
	var addressHelper = new AddressHelper();
	addressHelper.setDisplay('INLINE');
	addressHelper.setState(true, 'visible', '');
	addressHelper.setSuburb(true, 'visible', '');
	addressHelper.setStreetName(true, 'visible', '');
	addressHelper.setStreetType(true, 'visible', '');
	addressHelper.setStreetNumber(true, 'visible', '');
	addressHelper.setFlatNumber(true, 'visible', '');
	addressHelper.setAutoTab(true);
	addressHelper.setLayout('VERTICAL');
	addressHelper.setDelay(1.5);
	addressHelper.setAlias(true);
	addressHelper.setCoordinates(true);
	addressHelper.setXMLResponse(true, '_blank');
	addressHelper.setNumberAddressesReturned(10, 100);
	addressHelper.setDimensions(400, 500);
	addressHelper.setClearButton(true);
	addressHelper.setStyle('http://www.mywebsite.com/css/addresshelper-main.css');
	addressHelper.setFreeForm(true, 10, '<flatnumber>/<streetnumber> <streetname> 
		<streettype>, <suburb>, <state>');
	addressHelper.setShowAllAddresses(true);
	addressHelper.create();
</script>
</body>
</html>

The InitAddressHelper and AddressHelper scripts location will be made available to end users once they have purchased the product. These two scripts initialise the product and dynamically creates the web application for you based on how you have configured the application.
Inside the body of the HTML page that needs to be created, there needs to be a DIV with an ID of "AddressHelper like the following:

<div id="AddressHelper"></div>

Under this, some JavaScript needs to be inserted to place some dynamic HTML in the DIV and display to the user the AddressHelper application.
Firstly, you need to create a new instance of the application by inserting the following line:

var addressHelper = new AddressHelper();

Once this is done, the user is then free to set options to their liking. If the user does not set anything, then the application will use defaults. However, if the user wants to change some of the settings, then the user can change the values passed in the parameters:

	addressHelper.setDisplay('INLINE');
	addressHelper.setState(true, 'visible', '');
	addressHelper.setSuburb(true, 'visible', '');
	addressHelper.setStreetName(true, 'visible', '');
	addressHelper.setStreetType(true, 'visible', '');
	addressHelper.setStreetNumber(true, 'visible', '');
	addressHelper.setFlatNumber(true, 'visible', '');
	addressHelper.setAutoTab(true);
	addressHelper.setLayout('VERTICAL');
	addressHelper.setDelay(1.5);
	addressHelper.setAlias(true);
	addressHelper.setCoordinates(true);
	addressHelper.setXMLResponse(true, '_blank');
	addressHelper.setNumberAddressesReturned(10, 100);
	addressHelper.setDimensions(400, 500); // POPUP ONLY
	addressHelper.setClearButton(true);
	addressHelper.setStyle('http://www.mywebsite.com/css/addresshelper-main.css');
	addressHelper.setFreeForm(true, 10, 
		'<flatnumber>/<streetnumber> <streetname> <streettype>, <suburb>, <state>');
	addressHelper.setShowAllAddresses(true);
	addressHelper.setCopyToParent(true); // POPUP and FLOATING ONLY

setDisplay can be either INLINE, POPUP or FLOATING.
- Inline is when you want the application to be displayed in line with the rest of your website.
- POPUP is when you want a new window to to be displayed containing the AddressHelper application
- FLOATING is when you want your application to hover above your existing webpage and be displayed when an icon or text is selected.
setState - setFlatNumber enables or disables the state, suburb, street name, street type, street number and flat number address detail fields. The first parameter is whether to enable or disable the field. Second field is to set this field either to visible or hidden (enabled only), and the final parameter is the default value set for the field.
setAutoTab can either be true or false. If true, once a selection has been made from the suggestions, then the application will TAB to the next field.
setLayout is used to set the layout of the application. First parameter can be set to either VERTICAL or HORIZONTAL. The second optional parameter is the number of rows or columns the application should continue to place address detail fields before moving onto the next row or column.
setDelay is a number which represents the number of seconds before being presented with suggestions based on the users input into the given text field.
setAlias can either be true or false to display aliases or not.
setCoordinates can either be true or false to display coordinates or not
setXMLResponse can either be true or false to retrieve results back via an OpenLS XML Response or not. How an XML response can be used in a real life web application is visible in another TerraPages application known as MapAddress
The second parameter is a HTML target for where the results should be displayed. Possible values include _blank (New Window), _parent (Parent Window), _self (Same Window) or _top (Top Level Window)
setNumberAddressesReturned has two parameters too. The first one is the number of results to retrieve from the database. The second value is the height in pixels the suggestion box should be.
setDimensions is the width and height of the window that is created in pixels.
setClearButton can either be true or false to display a Clear button on the window to clear what the user has entered.
setStyle has a parameter which is a URL which can be another CSS file located on another server somewhere. As long as the CSS conforms to certain IDs and Classes, then the CSS changes will be visible.
setFreeForm has 3 parameters. First parameter can either be true or false depending on whether the free form text field is displayed and automatically copied to clipboard. Second parameter is the maximum number of addresses you want returned from the database. Final parameter is the format you want the free form address to be in. The tokens used must be followed closely if you want to retrieve the free form address correctly.
setShowAllAddresses can either be true or false. If true, then all valid addresses in G-NAF will be displayed. If false, then only addresses with a latitude and longitude will be displayed.
setCopyToParent can be either true or false depending on whether the user wants to copy the data automatically to the parent form which launched the application. To be able to copy to the parent form, the parent form fields must have IDs like the following:
Flat Number
```
<input id="flatNumber" type="text">
```
Street Number
```
<input id="streetNumber" type="text">
```
Street Name
```
<input id="streetName" type="text">
```
Street Type
```
<input id="streetType" type="text">
```
Suburb
```
<input id="suburb" type="text">
```
State
```
<input id="state" type="text">
```

Once all the settings have been entered by the user, the user needs to call the Create function to create the window based on the users settings. This is done by:

addressHelper.create();

If you decide to load AddressHelper into a popup window, you needs to add the following line to your exising webpage where you want to launch AddressHelper from.

<script>
function launchAddressHelper() {
	window.open('addresshelper.html', 'AddressHelper', 
	'resizable=yes,scrollbars=no,status=no,toolbar=no');
}
</script>

'addresshelper.html' is the new HTML page that you have just created.
The user also needs to add a link to call this JavaScript function. This can be achieved via a text link like the following:

<a href="javascript:void(0);" onclick="launchAddressHelper()"/>

or via an image link like the following:

<img src="addresshelper_logo.gif" onclick="launchAddressHelper()"/>

This GIF will be supplied upon purchase.

If however, you chose FLOATING as your preferred method, you need to create some text or an image with a certain ID. For example:

<img id="DisplayAddressHelper"
			src="addresshelper-logo.gif" alt="Launch Address Helper" />

Once clicked, your application will be displayed. You can either manually change the CSS for the AddressHelper DIV and display the application is an exact position, else the application will be displayed where the DIV is located. For INLINE, the application will be displayed where you have defined the AddressHelper DIV. Once all this is done, you should have a fully functional working AddressHelper product. Enjoy!