Our new Inline services lets client side developers have all the services and flexibility that server side developers have had for sometime. We use technologies similar to AJAX to get the browser to make server requests to Postcode Anywhere without you needing any server components or configuration.

The inline service is an extension of our standard XML services. However, instead of returning XML formatted data, it actually returns JavaScript which is then executed by the browser. Because browsers can load JavaScript dynamically, it's possible to access any of the Postcode Anywhere services from a simple HTML page without the need for postbacks or server coding.

Actually using the Inline service is very simple, and entirely consistent with the other Postcode Anywhere services. Basically, you build a URL containing your account code, license key and information about what to find, then get the browser to make the request.

Unique to the Inline service though, you also provide the name of the function to be called when the results are present. This "callback" function is executed automatically when the browser completes the request.

This tutorial takes you step by step though setting up the JavaScript Inline service on a simple HTML page. It only takes a few minutes and you can see how powerful it really is!

Before starting this tutorial, we need to create a simple HTML page which we will add the inline code to. In this example we've put postcode and building fields at the top of the page so that the customer doesn't first begin entering their address before they see the auto complete facility. We have also added a search button.

You will also need a web service license key (just go through the setup wizard in My Account to get one if you don't already).

<form method=post>

   <table>
      <tr>
         <td>Postcode</td>
         <td><input type=text name=postcode name=postcode size=10></td>
      </tr>
      <tr>
         <td>Building</td>
         <td>
            <input type=text name=building name=building size=5> 
            <input type=button value="Find"> 
         </td>
      </tr>
      <tr>
         <td>Company name</td>
         <td><input type=text name=company id=company size=40></td>
      </tr>
      <tr>
         <td>Line 1</td>
         <td><input type=text name=line1 id=line1 size=40></td>
      </tr>
      <tr>
         <td>Line 2</td>
         <td><input type=text name=line2 id=line2 size=40></td>
      </tr>
      <tr>
         <td>Line 3</td>
         <td><input type=text name=line3 id=line3 size=40></td>
      </tr>
      <tr>
         <td>Town</td>
         <td><input type=text name=town id=town size=40></td>
      </tr>
      <tr>
         <td>County</td>
         <td><input type=text name=county id=county size=40></td>
      </tr>
   </table>

</form>

The first step is to add the inline code which actually makes the request to Postcode Anywhere. We can get this code direct from the FastAddress documentation.

function pcaFastAddressBegin(postcode, building, language, style, account_code, license_code, machine_id, options)
   {
      var scriptTag = document.getElementById("pcaScriptTag");
      var headTag = document.getElementsByTagName("head").item(0);
      var strUrl = "";

      //Build the url
      strUrl = "http://services.postcodeanywhere.co.uk/inline.aspx?";
      strUrl += "&action=fetch";
      strUrl += "&postcode=" + escape(postcode);
      strUrl += "&building=" + escape(building);
      strUrl += "&language=" + escape(language);
      strUrl += "&style=" + escape(style);
      strUrl += "&account_code=" + escape(account_code);
      strUrl += "&license_code=" + escape(license_code);
      strUrl += "&machine_id=" + escape(machine_id);
      strUrl += "&options=" + escape(options);
      strUrl += "&callback=pcaFastAddressEnd";

      //Make the request
      if (scriptTag) 
         {
            headTag.removeChild(scriptTag);
         }
      scriptTag = document.createElement("script");
      scriptTag.src = strUrl;
      scriptTag.type = "text/javascript";
      scriptTag.id = "pcaScript";
      headTag.appendChild(scriptTag);
   }

function pcaFastAddressEnd()
   {
      //Test for an error
      if (pcaIsError)
         {
            //Show the error message
            alert(pcaErrorMessage);
         }
      else
         {
            //Check if there were any items found
            if (pcaRecordCount==0)
               {
                  alert("Sorry, no matching items found");
               }
            else
               {
                  //PUT YOUR CODE HERE
               }
         }
   }

Now we need to add an OnClick expression to the button to start the search:

<input type=button value="Find" 
   onclick="Javascript:pcaFastAddressBegin
      (document.getElementById('postcode').value, 
       document.getElementById('building').value,
       'english',
       'simple',
       'AAAAA11111', 
       'AA11-AA11-AA11-AA11', '', ''
      )"> 

Obviously, you will need to put your own account code and license key in there too.

So far we've copied the code to make the request and hooked it onto our form but how do we get the response? This is where things are slightly different to what you might expect.

To make the request, we call pcaFastAddressBegin(). This completes almost right away as the request to our servers happens in the background. When the results have been downloaded, pcaFastAddressEnd() gets called automatically so it's here that we need to handle the response.

In this example, we want to copy the address into textboxes on the form so we update the pcaFastAddressEnd() function with some extra lines (shown in bold):

function pcaFastAddressEnd()
   {
      //Test for an error
      if (pcaIsError)
         {
            //Show the error message
            alert(pcaErrorMessage);
         }
      else
         {
            //Check if there were any items found
            if (pcaRecordCount==0)
               {
                  alert("Sorry, no matching items found");
               }
            else
               {
                  document.getElementById("company").value=pca_organisation_name[0];
                  document.getElementById("line1").value=pca_line1[0];
                  document.getElementById("line2").value=pca_line2[0];
                  document.getElementById("line3").value=pca_line3[0];
                  document.getElementById("town").value=pca_post_town[0];
                  document.getElementById("county").value=pca_county[0];
                  document.getElementById("postcode").value=pca_postcode[0];
               }
         }
   }

It's worth just looking at the function a bit more closely too. Notice all the variables highlighted in green; and that these aren't declared anywhere on the page. These are imported from the Postcode Anywhere service and provide information about the response along with the actual data.

Some of these variables provide useful information about the response:

The actual data is supplied in a series of string arrays. There's one array per field in the response and each one is prefixed pca_. The first item in each array corresponds to the 1st record in the resultset.

That really is it! As you can see, the process is very simple and most of the nasty code is automatically generated for you. You can access all the Postcode Anywhere core services using this mechanism and better still, it makes the pages look really slick!