Manual Reference Pages - GEO::POSTCODES::AJAX (3)
Geo::Postcodes::Ajax - A Tutorial in how to set up an Ajax service for the
This document uses the fictious country Utopia (with country code U2),
and the rest of this document will refer to the non-existent module
The files described in this tutorial are available in the eg/ directory of
THE HTML FILE
Only the relevant parts of the html code in the file index.html is shown
Put this line somehere in the beginning of the file, so that the ajax code is
available for the code.
02 <form name=one onSubmit="return false;">
The form does not need a name for the ajax code to work, but it does not
hurt. The onSubmit-code prevents the form from beeing submitted, as we would
like to keep the html page - and let the ajax-code do changes in-line.
03 Address: <input name="address" value="Something or other"><br>
This is not used by the example, but is there to make it more real.
04 Postcode: <input id="postcode_u2"
We have dropped naming this and the following element, as there are no program to
receive the submitted form. Do give them a name-attribute if the form is meant
for submission (and use the same name as the ID).
It does not matter what id we give these elements, byt they must be unique for
the html document. (The naming structure used in this example makes it easy to
add forms for several languages in the same html document.)
05 onBlur=get_location("location_u2", "u2", "postcode_u2");
When the postcode field looses the focus, the location is computed
automatically by this call. The first argument is the ID of the location
field, which is showing the updated location information. The second argument
is the name of the country module, as used to build up the name of the
cgi-program that the ajax-code calls; in this case location_u2.cgi. The
third argument is the ID of the postcode field, where the ajax-code gets hold
of the postcode.
The location field is cleared whenever the poscode field gets the focus, as a
visual hint that we are changing it - and the shown location would not be
07 maxlength=4 size=4><br>
Utoipian postcodes are no longer than four characters, so we prevent the user
from typing in longer strings.
08 Location: <span id="location_u2" style="color:red;"></span>
The style is just to make the location stand out.
The file postcodecheck.js:
01 function clear_it (dest)
03 document.getElementById(dest).innerHTML = "";
This function is used to clear the location field for us, when the postcode
field gets the docus.
05 function get_location (dest, country, code)
The dest variable is the ID of the location field, where the postal location
is written (and is the destination of the call). The country variable is the
name of the country class the postcode belongings to. The code varaiable is
the ID of the postcode field, where the postcode is taken from.
07 var postcode = document.getElementById(code).value;
Get the postcode.
08 var httpreq = getHTTPObject();
Ajax magic. This procedure is included in this file, but ius not shown here
as it is exactly as in the ajax documentation. (See the file
eg/postcodecheck.js in the distribution of the core module for the code.)
09 var url = "location_" + country + ".cgi?postcode=" + postcode;
Build up the url of the cgi program to call. This ensures that we can have
programs for different countries, as it would not be a good idea to mix them
all togetehr into one huge program.
10 httpreq.open("GET", url, true);
This will execute the cgi program.
11 httpreq.onreadystatechange = function ()
13 if (httpreq.readyState == 4)
15 document.getElementById(dest).innerHTML = httpreq.responseText;
Put the returned text from the cgi call into the location element.
17 return true;
THE CGI FILE
The file location_u2.cgi:
01 #! /usr/bin/perl
02 use strict;
03 use Geo::Postcodes::U2 0.30;
04 use HTML::Entities ();
05 use CGI ();
06 print CGI::header(), CGI::start_html(-);
07 if (CGI::param())
09 my $postcode = CGI::param(postcode);
Check that the program was given the ?postcode=xxxx argument.
10 if (!Geo::Postcodes::U2::legal($postcode))
12 print "<em>Illegal postcode</em>";
14 elsif (!Geo::Postcodes::U2::valid($postcode))
16 print "<em>Postcode not in use</em>";
Give an error message that is as helpful as possible.
20 print HTML::Entities::encode(Geo::Postcodes::U2::location_of($postcode));
If the postcode is valid, we return the location. The encode call transforms any
8-bit (non us-ascii) characters (as the danish and norwegian ae, o\k:/ and aa)
to html character codes, as they would otherwise get scrambled (as we chose to
send the location string in hmtl instead of xml).
23 print CGI::end_html(), "\n";
Copy the three files index.html, location_u2.cgi and postcodecheck.js
(available in the eg/ directory of the distribution) to a directory on a
web server, and make sure that execution of cgi-scrips are allowed there.
Choose a country module to use (as U2 is fictious),
e.g. Geo::Postcodes::NO. Install this module, if not already done. Rename
the file location_u2.cgi to <location_no.cgi>.
Swap all occurences of the string u2 in the two files index.html and
location_u2.cgi with no.
Open the index file in a web browser.
THINGS TO DO
There are several things that can be done to this ajax example:
will probably also fix the compatibility problem with Internet Explorer.
Speed it up considerably by setting it up as a mod_perl handler.
The tutorial perldoc Geo::Postcodes::Tutorial or
man Geo::Postcodes::Tutorial, and the documentation for the individual
country modules; e.g. perldoc Geo::Postcodes::NO or
COPYRIGHT AND LICENCE
Copyright (C) 2006 by Arne Sommer - firstname.lastname@example.org
This library is free software; you can redistribute them and/or modify
it under the same terms as Perl itself.
Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 163:
Non-ASCII character seen before =encoding in ae,. Assuming ISO8859-1
|perl v5.20.3 ||GEO::POSTCODES::AJAX (3) ||2006-10-01 |
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.