Postcode Lookup
Configure
access to Postcode Anywhere
Overview
Ebase includes two functions to allow you to lookup
The postcode lookup operates in two phases. Firstly, the
end-user enters a postcode and the system returns a pulldown list of all
addresses for the post code. Secondly, the selected address is resolved into
the individual address fields. An example is shown below under complete example.
Configure access to Postcode
Anywhere
Before you can access Postcode Anywhere from an Ebase form,
you must first obtain an account code and a licence. You can obtain these from
Postcode Anywhere at www.postcodeanywhere.co.uk (a free demo licence is
available). Then update the PostcodeAnywhere.properties file in
.../ufs/Web-inf/classes with the licence and account code. You should also
check that parameter url specifies the correct
url for accessing Postcode Anywhere (the delivered value for this is http://services.postcodeanywhere.co.uk/xml.asp).
Postcode lookup - phase I
The first
phase uses the addresslookup function. To use this you need to setup
three form fields:
·
The field for the postcode - POSTCODE in the
example below.
·
The field for the pulldown list of returned
addresses - ADDRESSES in the example below. This field should have the immediate
validation option specified.
·
The field to receive the number of addresses -
ADDRESS_COUNT in the example below. This must be defined as a field of type
NUMBER.
POSTCODE
and ADDRESSES should appear on the page, ADDRESS_COUNT need not appear on any
page.
In addition
to these three fields, you will probably want to place a button next to the
postcode with a text like 'Lookup address'. The FPL script executed when this
button is clicked will then call the addresslookup function as shown in
this example:
set POSTCODE = uppercase(POSTCODE);
set ADDRESS_COUNT = addresslookup(POSTCODE,
'ADDRESSES');
if [ ADDRESS_COUNT = 0 ]
message
E,1001;
// message 1001 informs the user that the postcode is invalid
endif
The quotes around ADDRESSES are important as we are passing
the name of the field to contain the list of addresses. The IF statement
following the call checks that we have received some addresses and displays an
error message if the postcode is invalid (this message needs to be defined).
An
alternative way of doing this would be to use the immediate validation option
on the POSTCODE field and skip the lookup button.
Errors and unusual situations are handled as follows:
- For
configuration errors such as incorrect account or licence, the form is
aborted with an appropriate message.
- If
the given postcode is too short, error message 'Please supply a
complete postcode' is displayed.
- If
no addresses currently exist at the given postcode, the function returns
zero.
Postcode lookup - phase II
The second
phase uses the addressidlookup function to resolve the end-user's
selection from the dropdown list on the ADDRESSES field into the individual
address fields. To use this you need to setup seven additional form fields:
The field for the result - RESULT in the example below. This
must be a field of type NUMBER.
Six fields
comprising the individual address fields:
COMPANY_NAME
ADDRESS_LINE_1
ADDRESS_LINE_2
ADDRESS_LINE_3
TOWN
COUNTY
The address
fields should appear on the page.
It is not
possible to tell which of these fields will contain data after the lookup call -
it is very unlikely that all fields will be completed. The complete example
shown below hides all these fields and only makes them visible if they contain
data. Alternatively, you may choose to make all these fields permanently
visible.
set
RESULT = addressidlookup(ADDRESSES, 'COMPANY_NAME', 'ADDRESS_LINE_1',
'ADDRESS_LINE_2', 'ADDRESS_LINE_3','TOWN', 'COUNTY');
Again, the
quotes around the individual address fields are important as we are passing the
field names, not their values.
Complete example
The form
below provides an example:
Initially,
just the postcode field and the lookup (“Find Address”) button are visible and
all other fields are hidden.
When the
lookup button is clicked, the ADDRESS_LOOKUP script runs. This calls the addresslookup
function, checks the result and builds a list of the results of the lookup:
set POSTCODE = uppercase(POSTCODE);
set ADDRESS_COUNT = 0;
set ADDRESSES hidden;
set COMPANY_NAME hidden;
set LINE_1 hidden;
set LINE_2 hidden;
set LINE_3 hidden;
set TOWN hidden;
set COUNTY hidden;
//
call the phase I lookup function
set ADDRESS_COUNT = addresslookup(POSTCODE,'ADDRESSES');
if [ ADDRESS_COUNT = 0]
message
E,1001;
// Invalid postcode
else
unset ADDRESSES hidden;
if [ ADDRESS_COUNT > 1 ]
message W,1002,
ADDRESS_COUNT; // Inform the user of the number
of address found
else
message
W,1003;
// Only 1 address at this postcode
endif
endif
This populates and displays the ADDRESSES field as a
pulldown list of all valid addresses for the postcode.
When the end-user makes a selection from this list, the
GET_ADDRESS_FROM_ID script is run.
set ADDRESSES hidden;
set ADDRESS_ID = ADDRESSES;
//
call the phase II lookup function
set
ADDRESS_COUNT =
addressidlookup(ADDRESS_ID,'COMPANY_NAME','LINE_1','LINE_2','LINE_3','TOWN','COUNTY');
//
hide or unhide the address fields
if [ COMPANY_NAME = null]
set COMPANY_NAME hidden;
else
unset COMPANY_NAME hidden;
endif
if [ LINE_1 = null ]
set LINE_1 hidden;
else
unset LINE_1 hidden;
endif
if [ LINE_2 = null ]
set LINE_2 hidden;
else
unset LINE_2 hidden;
endif
if [ LINE_3 = null ]
set LINE_3 hidden;
else
unset LINE_3 hidden;
endif
if [ TOWN = null ]
set TOWN hidden;
else
unset TOWN hidden;
endif
if [ COUNTY = null ]
set COUNTY hidden;
else
unset COUNTY hidden;
endif
This script calls the addressidlookup function to
populate the individual address fields and make them visible:
