Before using this field you must have a provider set up in the API Server's Postcode worker.
The address lookup field includes a text input box (so users can enter their postcode), a search button, and a drop-down list which will be populated with the returned addresses. The field does not submit any address data when the form is submitted - it is designed to pass the selected address onto other fields on your form.
Out of the box the address lookup field shows all of its input boxes and buttons, will use your Postcode worker's
The addresses returned from the search are stored in a variable called FIELDNAME_ADDRESSES, where FIELDNAME is the name of this field.
The address drop-down list will automatically be populated with the addresses returned from the search.
When a user picks an address form the drop-down the field will create the following variables, holding the details of the selected address:
- FIELDNAME_UDPRN
- FIELDNAME_COMPANY
- FIELDNAME_DEPARTMENT
- FIELDNAME_LINE1
- FIELDNAME_LINE2
- FIELDNAME_LINE3
- FIELDNAME_LINE4
- FIELDNAME_LINE5
- FIELDNAME_TOWN
- FIELDNAME_COUNTY
- FIELDNAME_POSTCODE
- FIELDNAME_WARD
- FIELDNAME_LOCATION
- FIELDNAME_EASTING
- FIELDNAME_NORTHING
- FIELDNAME_LATITUDE
- FIELDNAME_LONGITUDE
- FIELDNAME_CUSTODIAN
The variables above will not necessarily all have values - that will depend on the provider that holds the address data and what it returns.
The field's handler should be used to pass the details of the selected address into relevant input fields.
Address Format
For this field to work as described, addresses need to be returned from the postcode search in the format described in Postcode Lookups.
Custom Functions
Custom functions can be called from the handlers of other fields using .invokeCustomFieldFn.
These custom functions are generally used if you are not using the field's built-in search and drop-down, or if you need to trigger an address search from another element on your form.
getAddress([index]) - retrieves details of the last selected address. If the inbuilt address list has been disabled, this can be called with the index of the address required from the retrieved addresses, stored in the _ADDRESSES variablegetAddresses() - retrieves the array of addresses returned by the last postcode search, stored in the _ADDRESSES variablepopulateAddressVariables([index]) - populates a set of form helper variables with the current selected address or the address identified by the, optional, index from the available addressessearch(postCode) - performs a postcode search and stores the returned addresses within the _ADDRESSES variable, accessible via thegetAddresses() custom function.
Properties
| Label | Description | Type Name |
|---|---|---|
| Fieldset Label | The field's label | LABEL |
| Show Fieldset Label | Whether the fieldset's label should be visible | SHOWLABEL |
| Show Fieldset Border | Whether the fieldset's border should be visible | SHOWBORDER |
| Hint | Additional information displayed alongside the field to assist the user. The value of another field can be used by adding the field's name between # characters. See Common Field Properties for more information | HINT |
| Postcode Label | The postcode input field's label. If no label is provided, the inbuilt fields (postcode input and search button) will be omitted and the search can be initiated by a call to the custom | POSTCODELABEL |
| Postcode Validation | Validation to be applied to the entered postcode. By default "Normal" validation is used, which tolerates mixed case and missing spaces, for example sw1a1hq. Use "Strict" validation to enforce entry of the postcode in uppercase and with the appropriate spacing, ie SW1A 1HQ. Select "None" if no validation is required | POSTCODEVALIDATION |
| Postcode Width | The postcode's display width. This property adds/removes a class on the postcode input element. The styling itself is controlled by the site's stylesheet | POSTCODEWIDTH |
| Search Label | The search button's label | SEARCHLABEL |
| Address Label | The address drop-down field's label. If no label is provided, the drop-down will be omitted and a change event will be fired when the addresses are retrieved. You can instead use the | ADDRESSLABEL |
| Address Hint | Initial hint text that appears in the address drop-down field | ADDRESSHINT |
| Address Empty Message | The text to display in the drop-down field if the postcode search doesn't find any matching addresses | ADDRESSEMPTYMSG |
| Address Width | The address's display width. This property adds/removes a class on the address select element. The styling itself is controlled by the site's stylesheet | ADDRESSWIDTH |
| Auto Hide Address | Whether to automatically hide the address list until needed. If set to true, the address list will be hidden until the Search button is pressed and a list of addressed retrieved. The address list will then be hidden again once an address is selected | ADDRESSAUTOHIDE |
| Default | Default value for the field | DEFAULT |
| Default Function | A JavaScript function you can use to calculate the starting field value. This function is executed server-side when the field HTML is generated. See Common Field Properties for an example | DEFFUNC |
| Mark Field as Required | Controls the required/optional marker output on the field (and the aria markup in the page source), it doesn't set the field itself as required. You should place your required validation on the fields that will store the address once it has been looked up | REQUIRED |
| Error Message | The error message that will be displayed if this field fails its validation | ERRMSG |
| Handlers | A JavaScript function that is executed client-side whenever the page loads, or the field value changes. This function is generally used to populate other fields with elements of the address selected form the address drop-down, see below for an example | HANDLERS |
| Provider | The provider, supported by the API Server's postcode service, to be used to perform the postcode search. Leave empty to use the default provider configured for the API Server. See the configuration documentation for the Postcode worker for more information about providers | PROVIDER |
| Worker Service URL | The URL of the API Server's postcode worker. If no URL is supplied here, this field will assume a URL of "/apiserver/postcode". This assumes the site defines a proxy that will route this request to its local API Server. If required, the full URL can be specified, for example: http://localhost:5706/postcode | SERVICEURL |
| Method Name | The name of the worker method that will be invoked when an address lookup is performed. The default is | METHODNAME |
| Additional Parameters | A JavaScript function that can be used to return a map of key-value pairs. These will be passed to the postcode worker when performing a search | ADDITIONALPARAMETERSFUNC |
| Address Description Function | This optional function can manipulate the format of the addresses displayed in the drop-down. As a minimum the Fields are also supplied as explicit parameters. Note that they may contain empty strings. Some address providers may provide additional information which will only be available via the | ADDRESSDESCFUNC |
| Additional Styling Modifier | An optional CSS modifier for the field. See Common Field Properties for an example | ADDITIONALSTYLINGMODIFIER |
| Documentation | Add documentation to your field to help explain any complex functionality to future users. You might include information on what the field does and how it relates to other fields on the form. Notes added here are only ever visible in the Forms Designer, they can be searched for, viewed and downloaded from the action panel. See Common Field Properties for an example | DOCUMENTATION |
Examples
There's a more detailed look at this field, including a working example, in the Postcode Lookups knowledge base article.
Share this page
