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 of this is shipped with Ebase as form
ADDRESS_TEST in the TEST project and 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
This is
implemented by form ADDRESS_TEST and scripts ADDRESS_LOOKUP and
GET_ADDRESS_FROM_ID in project TEST of the distributed sample forms. The form
looks like this:
Initially, just
the postcode field and the lookup 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:
