|
v 2.0 (updated 17/11/2009)
This quick step-by-step integration guide describes how to add a postcode based address finder to any website. No server-side coding is necessary, all the work is done by JavaScript supplied by CraftyClicks.
Preparation
Download the latest version of the integration pack from the developers section. Unzip the file.
Sign up for an account at www.craftyclicks.co.uk - you will be emailed an evaluation access token. Paste this token in place of xxxxx-xxxxx-xxxxx-xxxxx in Step 1 below.
Step 1
Upload the file crafty_postcode.class.js to your web server. Reference it in your HTML, by adding this code:
<script type="text/javascript" charset="ISO-8859-1" src="/crafty_postcode.class.js"></script>
Create and configure the JavaScript object:
<script>
var cp_obj = CraftyPostcodeCreate();
cp_obj.set("access_token", "xxxxx-xxxxx-xxxxx-xxxxx"); // paste your token here
cp_obj.set("result_elem_id", "crafty_postcode_result_display");
cp_obj.set("form", "address");
cp_obj.set("elements", ",address1,address2,address3,town,county,postcode");
</script>
Depending on where you upload the JS file, you may have to use a relative path. For example, you may have a directory on your server where you keep all JS code.
Don't forget to replace the X's with your own access token.
NOTE: the "ISO-8859-1" bit is important as the JS script is compressed.
NOTE: we recommend that the <script> tags are placed inside <head>. This is optional, they will work regardless of where you place them.
Step 2
You may already have a <form> with some postal address <input> fields on your web page. If not, create one first, e.g:
<form method="post" name="address">
Postcode:<br/>
<input type="text" name="postcode"/>
<button type="button" onclick="cp_obj.doLookup()">Find Address</button><br/>
<span id="crafty_postcode_result_display"> </span><br/>
Company:<br/>
<input type="text" name="companyname"/> <br/>
Address:<br/>
<input type="text" name="address1"/> <br/>
<input type="text" name="address2"/> <br/>
<input type="text" name="address3"/> <br/>
Town:<br/>
<input type="text" name="town"/> <br/>
County:<br/>
<input type="text" name="county"/>
</form>
If you copy the code above exactly, you can skip steps 3, 4 and 5, and go directly to Step 6.
The form HTML code can be styled/customised to fit your site.
NOTE: "companyname", "address2/3" and "county" are optional, you can leave these <input> fields out if it suits your site.
Step 3
Create a 'Find Address' button and link it to the script. If you copied the code in Step 2 exactly, you are done, go to the next Step. If not, then add this code to appear next to the postcode entry field:
<button type="button" onclick="cp_obj.doLookup()">Find Address</button>
Step 4
Add an element to hold the results drop-down box. If you copied the code in Step 2 exactly, you are done, go to the next Step. If not, then add this code to appear below the the postcode entry field:
<span id="crafty_postcode_result_display"> </span>
If you are using tables to style the address form, you could change it to:
<td id="crafty_postcode_result_display"> </td>
Step 5
Tell the script where to find the <input> fields it needs.
There are two methods:
1. Tell the script the name of the form and the names of the fields.
2. Attach unique IDs to all the fields.
If you copied the code in Step 2 exactly, you are done, go to Step 6. If not, read on.
Method 1:
Tell the script the name of the form and the names of all the fields. This method is useful if you don't have any control over the
<input> elements - e.g. if you are using a template driven system like JShop.
Add this to your HTML:
<script>
cp_obj.set("form", "XYZ");
cp_obj.set("elements", "companyname,address1,address2,address3,town,county,postcode");
</script>
Substitute "XYZ" with the name of your form and use the correct element names. Element names must be in the order shown above.
If you leave a few out don't delete the commas. E.g. a minimum set would be:
",address1,,,town,,postcode"
Method 2:
Add id=" ... " to every <input> field. Available id's are:
crafty_out_company,crafty_out_street1,crafty_out_street2,crafty_out_street3,crafty_out_town,crafty_out_county,crafty_in_out_postcode
<script>
cp_obj.set("form", "");
cp_obj.set("elements", "companyname_id,address1_id,address2_id,address3_id,town_id,county_id,postcode_id");
</script>
As in Method 1, element ids must be in the order shown above. If you leave a few out don't delete the commas.
E.g. a minimum set would be:
",address1_id,,,town_id,,postcode_id"
Step 6
Optional. Customise the way results are presented. Our JavaScript can be configured by calling
cp_obj.set("option_name", "option_value");
You could add these configuration calls to the code from Step 1, e.g:
<script>
cp_obj.set("access_token", "xxxxx-xxxxx-xxxxx-xxxxx");
cp_obj.set("option_1", "value_1");
...
cp_obj.set("option_n", "value_n");
</script>
See the file crafty_postcode_integration_steps.txt for a description of all available options.
Step 7
You are done. Test to make sure everything works OK. If you have any problems, try setting the script into debug mode and see if the error messages give any clues:
cp_obj.set("debug_mode", "1");
If you still have no luck - email any error codes/messages to support@craftyclicks.co.uk, we will be happy to help.
|
