Options

All Options can be changed when an AddressHelper is first initialised. This is done by using a JavaScript Dictionary {key: value, key: value} object sent to the new AddressHelper as the first parameter, as seen in all of our examples. Below are all the Options that can be changed for the AddressHelper Object & the Options that can be changed for individual fields.

Example:

var addressHelper = new AddressHelper({id: 'ah1', prefix: 'mudStore'});


Options for AddressHelper

NameType
debug Boolean Default: false
Set to true to enable FireBug logging.

delay Number Default: 1
Set the delay before an AJAX query is made to the backend service. Set in milliseconds

displayElementId String Default: null
Setting the displayElementId to the ID of a DIV will automatically fill the DIV with the currently selected data. This works on the trigger response of results from the backend service.

geocode Boolean Default: false
Set this value to true to enable geocoding of the currently top ranked result.

geocodeResult Function Default: null
Set this to a function to allow an event to be triggered upon a geocode result. That is, if a geocode result is found by the backend service this function will be called. If set, overrides the 'geocode' boolean to true.

id String Default: addresshelper || hotlocality
Set to override the default ID of the AddressHelper DIV ID. This can be used to easily name the AddressHelper DIV where a DIV already has an ID in a pre-existing website.

latitudeElementId String Default: null
Setting the 'latitudeElementId' to the ID of a DIV will automatically fill the DIV with the currently selected data's geocode. If both 'longitude' and 'latitude' are both set to the same DIV both will be added to the DIV delimited by the 'separator' option.

longitudeElementId String Default: null
Setting the 'longitudeElementId' to the ID of a DIV will automatically fill the DIV with the currently selected data's geocode. If both 'longitude' and 'latitude' are both set to the same DIV both will be added to the DIV delimited by the 'separator' option.

matchContains Boolean Default: true
Whether or not the comparison looks inside (i.e. does "ba" match "foo bar") the search results. Important only if you use caching. Don't mix with autofill.

maxReturnValues Number Default: 10
The number of results returned from the service end point. This also restricts the number of autocomplete results displated in the dropdown suggestion box.

minChars Number Default: 1
The minimum number of characters a user has to type before the autocompleter activates.

mustMatch Boolean Default: false
If set to true, the autocompleter will only allow results that are presented by the backend. Note that illegal values result in an empty input box.

prefix String Default: null
Set a profix on the AddressHelper DIV & INPUT elements. This is used to add a unique prefix to the Addresshelper object where by doing so allows easy integration into pre-existing websites and multiple AddressHelpers on the one site.

result Function Default: null
Hooks a callback function that is called when a suggestion is selected from the list. Note that if 'geocoding' option is set, the resulting coordinates will be available when this is called.

separator String Default: ' '
Used to separate the longitude and latitude when both longitudeElementId and latidudeElementId are set to the same ID.

serviceEndPoint String Default: http://terrapages.net/addresshelper/processlauncherservlet
Change this URL connect your AddressHelper client JavaScript to a different Backend Service.

style String Default: null
Change the inline style of the AddressHelper wrapper DIV by setting this option to CSS styling.

styleClass String Default: null
Change the Style Class of the AddressHelper wrapper DIV by setting this option to a CSS styling, this style name must be available to the page with in page style element or a linked CSS file.

type String Default: hotlocality
Set to tell Addresshelper which type of setup you intend. Two options are available: 'hotlocality' or 'addresshelper'. by default 'hotlocality' is set which will populate your page with a single DIV for Free Form Address resolution. If set to 'addresshelper' a tokenized set of DIVs are populated.

excludeUngeocoded String Default: false
Set to true to exclude all addresses that do not have a geocode from returning as a suggestion
returnTokens String Default: true
HotLocality only: When a geocode is returned along with it are tokenized street details: state, suburb and street name.
noSuggestions Function Default: null
Hooks a callback function that is called when no suggestions are returned from the backend service. This is called on retrieval of suggestions and should not to be mistaken for when a suggestion is selected from the list.

hasSuggestions Function Default: null
Hooks a callback function that is called when the number of suggestions returned from the backend service is more than one. This is called on retrieval of suggestions and should not to be mistaken for when a suggestion is selected from the list.

noSuggestionsText String Default: No Suggestions
Override the No Suggestions text for when no addresses are returned from the backend service

retrieveAliasAddresses Boolean Default: false
Override to have Alias Addresses returned with the result set, false by default because AddressHelper does not use them

showAllAddresses Boolean Default: true
Override to have all addresses shown regardless of if it has a Geocode

showPostcode Boolean Default: true
Override to stop the display of postcode in the suggestion box, this will not stop the postcode search feature

unsuccessfulGeocode Function Default: null
Set this to a function to allow an event to be triggered upon an unsuccessful Geocode result. That is, if a geocode result can not be found by the backend service for an address, this function will be called. The 'geocode' option must be set to true to use this function.

size Number Default: 60
The size of input field. Only applicable to AddressHelper of type 'hotlocality' setup


Field Specific Options

Each field can override the Options from the Addresshelper. For instance the 'style' option can we changed for the entire AddressHelper which would change all the Fields upon creation. If one field needed a particular style this can be achieved by changing that fields 'style' option. See the examples of how to change field options.

Here is a list of options that can be overridden for each field:


NameType
autoComplete Boolean Default: true
Set to false to disable autocomplete on this field. For instance if you need to turn this field 'off' for any purpose. can be changed

elementId String Default: null
If overridden Addresshelper uses this elementId to search the DOM for an element with this ID. This element of type DIV will be the host of the Field.

label String Default: 'state', 'suburb', 'streetName', streetType', 'streetNumber', 'flatNumber'
Override to change the name of the element, this is a default ID of the field, this is used to search the page of element types with the ID == to this label. For instance say a field label was set to 'mudStoreSuburb' and the prefix was set to 'red'. AddressHelper would look for elements in the following order:

  • Element with INPUT ID set to 'elementId'
  • Element with DIV ID set to AddressHelper.id
  • Element with DIV ID set to prefix_label (which is 'red_mudStoreSuburb'

Data from AddressHelper

NameType
current String Default: null
Once a result has been found this String is populated with the currently top rated result. This can be accessed by simply accessing the option like you would for setting an option: var current = addressHelper.get('current');

data Array Default: null
Once a result has been found this Array is populated with the current result set. This can be accessed by simply accessing the option like you would for setting an option: var currentResults = addressHelper.get('data');

latitude String Default: null
Once a result has been found this String is populated with the currently top rated results geocode. This can be accessed by simply accessing the option like you would for setting an option: var current = addressHelper.get('latitude');

longitude String Default: null
Once a result has been found this String is populated with the currently top rated results geocode. This can be accessed by simply accessing the option like you would for setting an option: var current = addressHelper.get('longitude');

Styling AddressHelper

There are few ways to customise the style and behaviour of how the suggestions are displayed. One way is to override the default styles on the elements containing the suggestions list. Note that this uses jQuery UI 1.8 - Autocomplete.

Examples:

.ui-autocomplete ul {
width: 100%;
}

.ui-autocomplete li {
font: menu;
font-size: 12px;
}

Another way is to implement the styles AddressHelper sets. These are provided so that we can still hook styles on scenarios which the first method above cannot handle. Kindly see full list of options below.

NameType
ac_loading CSS Class Default: none
This style is set to the auto-complete field. This can be implemented to set a loading spinner or image to indicate retrieval of suggestions. This class is set when the auto-complete's "search" event is triggered and is unset when the "open" event is triggered.

.ac_loading { background: white url('../images/indicator.gif') right center no-repeat; }

ac_odd CSS Class Default: none
This style is set to odd rows of the suggestions list. This can be implemented to provide an alternating row style on the suggestions list.

.ac_odd { background-color: #eee; }

ac_even CSS Class Default: none
This style is set to even rows of the suggestions list. This can be implemented to provide an alternating row style on the suggestions list.

.ac_even { background-color: white; }