X-Cart Integration Guide

Integration with X-Cart address forms made simple

A step-by-step guide to integration with X-Cart address forms.

Preparation

Download

Download one of our X-Cart plugins from the plugins page. We offer plugins for Address Auto-Complete (global address lookup for over 240 countries) and Postcode Lookup (UK only). The plugins are free to download.

Visit the download page  

Sign Up

Next, you need to sign up for a Crafty Clicks account.

When you sign up, you will receive an access token by email. There is no obligation to buy anything and you automatically get 30 trial credits. If you need more credits to test the integration, please get in touch (support@craftyclicks.co.uk) and we will try to accommodate you.

Installation

Select the plugin you would like to install.

Install Address Auto-Complete

Step 1

Backup these files as they will be changed:

  • /skin/common_files/main/zipcode.tpl
  • /skin/common_files/css/admin.css

Step 2

Download then extract the zip file.

Step 3

Copy the skin folder you have just extracted to your X-Cart installation, merging it with the existing skin folder.

Step 4

On line 51 of /skin/common_files/js/cc_c2a_xcart.js, replace xxxxx-xxxxx-xxxxx-xxxxx with your own access token.

Step 5

For the lookup search bar to appear correctly in the admin panel, you may need to edit the file /skin/common_files/css/admin.css. Try removing the following code:

li {
	list-style-position: inside;
	list-style-type: disc;
}

If you want to use the dark colour scheme for the address lookup interface, you may need to remove the following line of code from /skin/common_files/css/admin.css:

color: #2c3e49;

Step 6 (optional)

  • line 53: ambient can be used to set a ‘dark’ or ‘light’ colour scheme for the interface.
  • line 54: accent can be used to set an additional colour for the dropdown.
  • line 58: gfxMode can be set to 1 or 2, and lets you choose whether to display the interface underneath or surrounded by the search field.
  • line 61: showLogo can be set to 0 or 1, and lets you show or hide the logo.
  • line 190: Here you can set the default country.

Install Postcode Lookup

Step 1

Backup these files as they will be changed:

  • skin1/customer/main/register.tpl
  • skin1/customer/main/register_billing_address.tpl
  • skin1/customer/main/register_shipping_address.tpl

If you are on an older version of X-Cart the register_*_address.tpl files may be in skin1/main/

If your template is not heavily customised and has not modified the address forms, you should be able to simply copy the skin1 folder structure contained in this package on top of your x-cart installation.

If your template files need merging, read the rest of the installation steps.

Step 2

Copy this file to your X-Cart installation:

skin1/js/crafty_postcode.class.js

Step 3

Edit this file: skin1/customer/main/register.tpl

At the top of the file, after the opening header tag, add the following:

<script type="text/javascript" charset="ISO-8859-1" src="{$SkinDir}/js/crafty_postcode.class.js"></script>
<script>
// <![CDATA[
var cp_access_token = "xxxxx-xxxxx-xxxxx-xxxxx"; // Replace with your own access token
//]]>
</script>

Note: You should replace xxxxx-xxxxx-xxxxx-xxxxx with your own access token.

Step 4

Now edit this file: skin1/customer/main/register_billing_address.tpl

After:

<input type="text" id="b_zipcode" name="b_zipcode" size="32" maxlength="32" value="{$userinfo.b_zipcode|escape}" onchange="javascript: check_zip_code();" />

Add:

&nbsp;&nbsp;
<button type="button" onclick="cp_obj_1.doLookup()">Find Address</button>

After:

<input type="text" id="b_zipcode" name="b_zipcode" size="32" maxlength="32" value="{$userinfo.b_zipcode|escape}" onchange="javascript: check_zip_code();" />
&nbsp;&nbsp;
<button type="button" onclick="cp_obj_1.doLookup()">Find Address</button>
{if $reg_error ne "" and $userinfo.b_zipcode eq "" and $default_fields.b_zipcode.required eq 'Y'}
<span class="error-message">&lt;&lt;</span>
{/if}
</td>
</tr>

Add:

<tr>
<td colspan="2">&nbsp;</td>
<td colspan="1" id="crafty_postcode_result_display_1">&nbsp;</td>
</tr>

You should end up with something like:

{if $default_fields.b_zipcode.avail eq 'Y'}
<tr>
<td class="data-name">{$lng.lbl_zip_code}</td>
<td class="data-required">{if $default_fields.b_zipcode.required eq 'Y'}*{/if}</td>
<td>
<input type="text" id="b_zipcode" name="b_zipcode" size="32" maxlength="32" value="{$userinfo.b_zipcode|escape}" onchange="javascript: check_zip_code();" />
&nbsp;&nbsp;
<button type="button" onclick="cp_obj_1.doLookup()">Find Address</button>
{if $reg_error ne "" and $userinfo.b_zipcode eq "" and $default_fields.b_zipcode.required eq 'Y'}
<span class="error-message">&lt;&lt;</span>
{/if}
</td>
</tr>
<tr>
<td colspan="2">&nbsp;</td>
<td colspan="1" id="crafty_postcode_result_display_1">&nbsp;</td>
</tr>
{/if}

At the bottom of the file, before:

{/if}

Add:

{literal}
<input type="hidden" name="b_temp_county" id="b_cp_temp_county"/>
<script>
// <![CDATA[
var cp_obj_1 = CraftyPostcodeCreate();
cp_obj_1.set("access_token", cp_access_token);
cp_obj_1.set("max_width", "300px");
cp_obj_1.set("max_lines", "8");
cp_obj_1.set("first_res_line", "");
cp_obj_1.set("res_autoselect", "0");
cp_obj_1.set("traditional_county", "1");
cp_obj_1.set("result_elem_id", "crafty_postcode_result_display_1");
cp_obj_1.set("form", "");
cp_obj_1.set("elem_company" , "b_address");
cp_obj_1.set("elem_street1" , "b_address");
cp_obj_1.set("elem_street2" , "b_address_2");
cp_obj_1.set("elem_street3" , "");
cp_obj_1.set("elem_town" , "b_city");
cp_obj_1.set("elem_county" , "b_cp_temp_county");
cp_obj_1.set("elem_postcode" , "b_zipcode");
cp_obj_1.set("on_result_selected",_cp_handle_selection);

function _cp_handle_selection() {
	var county_name = document.getElementById("b_cp_temp_county").value.toLowerCase();
	var county_list = document.getElementById("b_state");
	if (county_list) {
		// clear the currently selected one
		county_list.options[county_list.selectedIndex].selected = "0";
		for (var ii = 0; ii < county_list.options.length; ii++) {
			if (county_list.options[ii].text.toLowerCase() == county_name) {
				// got it
				county_list.options[ii].selected = "1";
			}
		}
	}
}

//]]>
</script>
{/literal}

Step 5 (optional)

Customise the look and feel. Some options/suggestions:

  1. Remove the county field (using X-Cart admin panel). The county is ignored by Royal Mail and others during delivery. Fewer fields on the address form means better usability. If you really want it, at least make it optional.
  2. Change the height of the result box – this is done by adjusting the max_line setting.
  3. Move the country and postcode fields to the top of the form. If you copied the .tpl files enclosed in this package, this is already done for you.

FAQ

Test

Before you go live, test the integration to make sure it is working properly.

For the Postcode Lookup integration only, we have the following free postcodes for testing: AA1 1AA, AA1 1AB, AA1 1AD and AA1 1AE.

If you need assistance, drop us an email on support@craftyclicks.co.uk – we will help!

Go Live

Once your trial credits run out, you will need to decide on the best purchasing option based on the volume of usage you expect on your site. If you would like us to advise you then please get in touch.

Questions

  • Do you offer support? Yes, we do offer support during normal business hours in the UK. If you run into any issues, let us know and we will be happy to help.
  • Is this free? The extension is free to download and try, but to use it on a live site you will need a paid account with us.
  • Do I need to sign up for an account to try it? Yes, you’ll need a trial account, at least. You can easily sign up for a free trial account.
Last Updated: 9/11/2018, 1:32:56 PM