Toggle menu

Address Lookup

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 defaultProvider (set in the API Server's configuration file) and calls the postcodeSearch method.

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 variable
  • getAddresses() - retrieves the array of addresses returned by the last postcode search, stored in the _ADDRESSES variable
  • populateAddressVariables([index]) - populates a set of form helper variables with the current selected address or the address identified by the, optional, index from the available addresses
  • search(postCode) - performs a postcode search and stores the returned addresses within the _ADDRESSES variable, accessible via the getAddresses() custom function.

Properties

LabelDescriptionType Name
Fieldset LabelThe field's labelLABEL
Show Fieldset LabelWhether the fieldset's label should be visibleSHOWLABEL
Show Fieldset BorderWhether the fieldset's border should be visibleSHOWBORDER
HintAdditional 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 informationHINT
Postcode LabelThe 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 search(postCode) functionPOSTCODELABEL
Postcode ValidationValidation 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 WidthThe postcode's display width. This property adds/removes a class on the postcode input element. The styling itself is controlled by the site's stylesheetPOSTCODEWIDTH
Search LabelThe search button's labelSEARCHLABEL
Address LabelThe 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 getAddress([index]) custom function to retrieve details of the relevant address in the _ADDRESSES variableADDRESSLABEL
Address HintInitial hint text that appears in the address drop-down fieldADDRESSHINT
Address Empty MessageThe text to display in the drop-down field if the postcode search doesn't find any matching addressesADDRESSEMPTYMSG
Address WidthThe address's display width. This property adds/removes a class on the address select element. The styling itself is controlled by the site's stylesheetADDRESSWIDTH
Auto Hide AddressWhether 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 selectedADDRESSAUTOHIDE
DefaultDefault value for the fieldDEFAULT
Default FunctionA 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 exampleDEFFUNC
Mark Field as RequiredControls 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 upREQUIRED
Error MessageThe error message that will be displayed if this field fails its validationERRMSG
HandlersA 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 exampleHANDLERS
ProviderThe 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 providersPROVIDER
Worker Service URLThe 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 NameThe name of the worker method that will be invoked when an address lookup is performed. The default is postcodeSearch since this is the method used by the default postcode worker service. This should only be changed if a different worker is used. For example if an End Point is being called by setting the ajaxlibrary worker then this should be the name of the End Point.METHODNAME
Additional ParametersA 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 searchADDITIONALPARAMETERSFUNC
Address Description FunctionThis optional function can manipulate the format of the addresses displayed in the drop-down. 

As a minimum the addressData object will contain the following fields: company, department, line1, line2, line 3, line4, line5, town, county, postcode

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 addressData object  
ADDRESSDESCFUNC
Additional Styling ModifierAn optional CSS modifier for the field. See Common Field Properties for an exampleADDITIONALSTYLINGMODIFIER
DocumentationAdd 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 exampleDOCUMENTATION

Examples

There's a more detailed look at this field, including a working example, in the Postcode Lookups knowledge base article.

Share this page

Facebook icon Twitter icon email icon

Print

print icon