In the <head> of your web page, add these lines (replacing ‘https://cloud.hopewiser.com/jsclient’ with the relative path of the folder you used above, if you chose to install these files on your own web server):
<link rel="stylesheet" href="https://cloud.hopewiser.com/jsclient/jquery-ui.min.css" />
<link rel="stylesheet" href="https://cloud.hopewiser.com/jsclient/hpw-autoc-jsclient.css" />
Before the </body> closing tag of your web page, add these lines (replacing ‘https://cloud.hopewiser.com/jsclient’ with the relative path of the folder you used above, if you chose to install these files on your own web server):
<script src="https://cloud.hopewiser.com/jsclient/jquery.min.js"></script>
<script src="https://cloud.hopewiser.com/jsclient/jquery-ui.min.js"></script>
<script src="https://cloud.hopewiser.com/jsclient/json2.min.js"></script>
<script src="https://cloud.hopewiser.com/jsclient/easyXDM.min.js"></script>
<script src="https://cloud.hopewiser.com/jsclient/hpw-autoc-jsclient.min.js"></script>
If your web site is already using jQuery, jQuery UI, json2 or easyXDM, you may be able to omit the applicable lines or reference your existing installation as necessary.
Replace ‘https://cloud.hopewiser.com/jsclient’ with the relative path of the folder if you chose to install these files on your own web server instead of using our cloud resources. Details of how to obtain local JavaScript components required can be located in the Customisation section “How do I install AutoComplete JavaScript Client service files locally?”.
Finally, add a script to enable the address autocomplete feature on a nominated input field by association with a HPWAUTOC.FindAddress() function:
<script>
HPWAUTOC.FindAddress({
server: X, // optional (default = "https://cloud.hopewiser.com")
auth: X, // required
dataset: X, // required
minLength: N, // optional numeric value (default = 1)
delay: N, // optional numeric value (default = 300)
input: X, // required
outputlines: N, // optional range value 2-9 (default = 7)
output: {
line1: X, // required
line2: X, // required
line3: X, // optional
line4: X, // optional
line5: X, // optional
line6: X, // optional
line7: X, // optional
line8: X, // optional
line9: X, // optional
country: X // optional
},
success: X, // optional callback function
LabelFormat: X, // optional (default = "Standard")
ReserveOrganisationLine: X, // optional (default = "AsRequired")
IncludeCounty: X, // optional (default = "AsRequired")
DropCountyToFitLabel: X, // optional (default = "Never")
TownFormat: X // optional (default = "Uppercase")
});
</script>
The HPWAUTOC.FindAddress() function takes a JavaScript object containing:
- your authorisation code,
- the dataset to look up against,
- the HTML ID of your input field,
- an object containing the HTML IDs of your output fields, and
- optionally, parameters to influence other service behaviours referenced in the below Optional Parameter table.
| Mandatory Parameter |
Description |
| auth |
A valid authorisation code is required to access the required dataset. |
| dataset |
A dataset ID associated with the MAF and AutoComplete database files. |
| input |
The search field to invoke the AutoComplete address lookup. |
| output.line1 to output.line2 |
The first two lines of the formatted label for the selected address. |
| Optional Parameter |
Description |
| server |
This is the URL to the AutoComplete Server. It defaults to “https://cloud.hopewiser.com”. |
| minLength |
This is the minimum number of characters a user must type before a search is performed. Its default value is 1. |
| delay |
This is a delay in milliseconds between when a keystroke occurs and when a search is performed. No menu will be displayed until the typist pauses for the specified delay period after the last keystroke. Its default value is 300. |
| outputlines |
This parameter is used to specify the maximum number of formatted output lines which should to be mapped accordingly in the “output.line” block. Allowed range is 2 to 9. Its default value is 7. |
| output.line3 to output.line9 |
Configure field mappings to include additional address label lines. |
| output.country |
Configure a field mapping to include the country field information. |
| ‘detail’ matched address output fields |
This optional configuration section contains mapping information for some of the common address output fields.
The available detail elements will depend on your dataset. To view the available detail elements, visit:
https://cloud.hopewiser.com/autoc/json/dataset?q=listoutputs
Replace dataset with the dataset you want to use, e.g. https://cloud.hopewiser.com/autoc/json/uk-nspd-paf-external?q=listoutputs. Enter your User name and Password when prompted. The available detail elements are those Outputs that have a TableName of “Address Fields” or “Data”. |
| ‘extra’ data fields |
This optional configuration section contains mapping information for “Extra Data” fields of a given matched address.
The available extra data elements will depend on your dataset. To view the available extra data elements, visit:
https://cloud.hopewiser.com/autoc/json/dataset?q=listoutputs
Replace dataset with the dataset you want to use, e.g. https://cloud.hopewiser.com/autoc/json/uk-nspd-paf-external?q=listoutputs. Enter your User name and Password when prompted. The available extra data elements are those Outputs that have a TableName of “Extra Data”. |
| success |
Calls a callback function at the end of populating the returned address if this parameter is configured. |
| LabelFormat |
Select the position of the town, county and postcode within the formatted address label. Allowed values are Standard (the default), FixedPostcode or FixedTown.
The value FixedPostcode reserves the last line of the formatted address label for the postcode and forces it to be output on a separate line.
The value FixedTown reserves the last three lines of the formatted address label for the town, county and postcode and forces each value to be output on a separate line. Please note that a line is reserved for the county even if none is output.
When a fixed value is requested, the formatted address label will comprise the maximum allowed number of address lines, some of which may be empty. |
| ReserveOrganisationLine |
Select the position of the organisation within the formatted label. Allowed values are Always, Never or AsRequired (the default).
The value AsRequired includes the organisation within the address label following standard formatting rules.
The value Always reserves the first line of the formatted address label for the organisation and forces it to be output on a separate line. If there is no organisation then the first line will be empty.
The value Never removes the organisation from the formatted address label. |
| IncludeCounty |
Select when the county should be included within the formatted address label. Allowed values are Always, Never or AsRequired (the default). |
| DropCountyToFitLabel |
Select if the county may be dropped when it does not fit within the formatted address label. Allowed values are Never (the default), or Always. |
| TownFormat |
Select the required town format. Allowed values are Uppercase (the default) or Lowercase. |
If your web page has separate address fields
Specify their HTML IDs in the output object, e.g.
HPWAUTOC.FindAddress({
auth: "yourAuthCode", // required
dataset: "uk-rm-paf-external", // required
input: "txtInput", // required
output: {
line1: "txtLine1", // required
line2: "txtLine2", // required
line3: "txtLine3", // optional
line4: "txtLine4", // optional
line5: "txtTown", // optional
line6: "txtCounty", // optional
line7: "txtPostcode", // optional
country: "txtCountry" // optional
},
LabelFormat: "FixedTown", // optional (default = "Standard")
ReserveOrganisationLine: "Never", // optional (default = "AsRequired")
IncludeCounty: "Always", // optional (default = "AsRequired")
TownFormat: "Lowercase" // optional (default = "Uppercase")
});
If your web page has a single multi-line address field
Specify its HTML ID against each address line you want to be returned, e.g.
HPWAUTOC.FindAddress({
auth: "yourAuthCode", // required
dataset: "uk-rm-paf-external", // required
input: "txtInput", // required
outputlines: 9, // optional range value 2-9 (default = 7)
output: {
line1: "txtAddress", // required
line2: "txtAddress", // required
line3: "txtAddress", // optional
line4: "txtAddress", // optional
line5: "txtAddress", // optional
line6: "txtAddress", // optional
line7: "txtAddress", // optional
line8: "txtAddress", // optional
line9: "txtAddress", // optional
country: "txtAddress" // optional
},
IncludeCounty: "Always" // optional (default = "AsRequired")
});
If your web page has a mixture of multi-line and individual address fields
For each address line you want, specify the HTML ID of the field you want it returned to, e.g.
HPWAUTOC.FindAddress({
auth: "yourAuthCode", // required
dataset: "uk-rm-paf-external", // required
input: "txtInput", // required
output: {
line1: "txtAddress", // required
line2: "txtAddress", // required
line3: "txtAddress", // optional
line4: "txtAddress", // optional
line5: "txtTown", // optional
line6: "txtCounty", // optional
line7: "txtPostcode", // optional
country: "txtCountry" // optional
},
LabelFormat: "FixedTown", // optional (default = "Standard")
ReserveOrganisationLine: "Never", // optional (default = "AsRequired")
IncludeCounty: "Always", // optional (default = "AsRequired")
TownFormat: "Lowercase" // optional (default = "Uppercase")
});
(Replace yourAuthCode with your authorisation code and the example HTML IDs with your actual HTML IDs.) If you do not specify an ID for line3..line6, the returned address will be formatted to fit the available lines. The county ID should be used in conjunction with the IncludeCounty parameter, and must be specified when the county is required. If you do not specify an ID for country, then it will be omitted. The input field does not have to be a separate field; it can be one of the output fields, in which case it would most likely be the postcode field.
