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
cacheLengthNumberDefault:1
The number of backend query results to store in cache. If set to 1 (the current result), no caching will happen. Must be >= 1.
dataTypeStringDefault: Intelligent Guess (xml or html)
The type of data that you're expecting back from the server. If none is specified, jQuery will intelligently pass either responseXML or responseText to your success callback, based on the MIME type of the response. The available types (and the result passed as the first argument to your success callback) are:
  • "xml": Returns a XML document that can be processed via jQuery.
  • "html": Returns HTML as plain text; included script tags are evaluated when inserted in the DOM.
  • "script": Evaluates the response as JavaScript and returns it as plain text. Disables caching unless option "cache" is used. Note: This will turn POSTs into GETs for remote-domain requests.
  • "json": Evaluates the response as JSON and returns a JavaScript Object.
  • "jsonp": Loads in a JSON block using JSONP. Will add an extra "?callback=?" to the end of your URL to specify the callback. (Added in jQuery 1.2)
  • "text": A plain text string.
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.
extraParams Dictionary Default: null
If needed, any extra data needed by the backend service can be attached to the request using the 'extraParams' dictionary.
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
If a result is found this Function will be called, this is called after the 'geocode' call, which means access to the longitude and latitude is available if geocode returned a result. *This does NOT override the boolean for 'geocode', if not set to true this will NOT geocode any results.
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
Hook for a call to a function when no suggestions are retruned from the backend service
hasSuggestions Function Default: null
Hook for a call to a function when suggestions are retruned from the backend service, not to be mistaken for when a result if found (selected)
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.
scroll Boolean Default: true
Boolean to set if scrolling is allowed on the autocomplete dropdown box, set to true (default) to allow scrolling results
autoTab Boolean Default: false
Boolean to set auto tab is enabled, if a single results is sent back from the server the result is auto filled in a the cursor is moved to the next input field
autoSearch Boolean Default: true
Auto search when the field has focus and is empty
autoSearchString String Default: a
The String autoSearch (see above) will use as the search string
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'
suggestionResultsStyleClass String Default: null
Override the style class for the suggestion dropdown box results.
suggestionLoadingStyleClass String Default: null
Override the style class for the suggestion box loading.
suggestionResultsOverStyleClass String Default: null
Override the style class for the suggestion dropdown box while mouse over.
suggestionResultsOddStyleClass String Default: null
Override the style class for the suggestion dropdown box odd results.
suggestionResultsEvenStyleClass String Default: null
Override the style class for the suggestion dropdown box even results.

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');