Zen Cart Integration Guide

Integration with Zen address forms made simple

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

Preparation

Compatibility

Verified with Zen Cart v1.3.8a, v1.3.9f, v1.3.9h and v1.5.0.

Download

Download our Zen Cart plugin from the plugins page. We only offer a plugin for Postcode Lookup (UK only). The plugin is 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 100 trial lookups. If you need more lookups to test the integration, please get in touch (support@craftyclicks.co.uk) and we will try to accommodate you.

Installation

If you have an unmodified Zen Cart installation, simply extract the archive folder on top of your ZenCart folder. Address lookup will be added to the default template (in templates/template_default/). You will now have a ‘Find Address’ button next to all postcode input boxes and the results in a drop down box directly below it.

If you are on an older version of ZenCart (before 1.3.9h), please use admin/customers.php from version 1.2 of the module. All other files can be used from the current v1.3 version.

If you have a modified installation, read on. The instructions below apply to all supported versions of ZenCart.

Step 1

You will need to create the directory:

includes/modules/craftyclicks

and copy these files:

includes/modules/craftyclicks/crafty_html_output.php includes/modules/craftyclicks/crafty_postcode_busy.gif includes/modules/craftyclicks/crafty_postcode.class.js includes/modules/craftyclicks/button_find_address.gif

Step 2

Paste your access token in place of xxxxx-xxxxx-xxxxx-xxxxx at the top of the file /includes/modules/craftyclicks/crafty_html_output.php.

Step 3

In the file includes/templates/YOURTEMPLATE/templates/tpl_modules_address_book_details.php

(Note: YOURTEMPLATE needs to be substituted with your own template directory name)

Insert at the top (around line 13, after the comments):

<?php
require(DIR_WS_MODULES.'craftyclicks/crafty_html_output.php');
echo tep_crafty_script_add('addressbook', 1);
?>

Find (around line 97):

<?php echo zen_draw_input_field('postcode', $entry->fields['entry_postcode'], zen_set_field_length(TABLE_ADDRESS_BOOK, 'entry_postcode', '40') . ' id="postcode"') . (zen_not_null(ENTRY_POST_CODE_TEXT) ? '<span class="alert">' . ENTRY_POST_CODE_TEXT . '</span>': ''); ?>

Insert before the last semicolon:

. '&nbsp;&nbsp;' . tep_crafty_button_add(1)

The result should be:

<?php echo zen_draw_input_field('postcode', $entry->fields['entry_postcode'], zen_set_field_length(TABLE_ADDRESS_BOOK, 'entry_postcode', '40') . ' id="postcode"') . (zen_not_null(ENTRY_POST_CODE_TEXT) ? '<span class="alert">' . ENTRY_POST_CODE_TEXT . '</span>': ''). '&nbsp;&nbsp;' . tep_crafty_button_add(1); ?>

Find (just below around line 98):

<br class="clearBoth" />

Insert after:

<span id="crafty_postcode_result_display">&nbsp;</span>
<br class="clearBoth" />

Insert at the bottom of the file:

<? echo tep_crafty_country_handler(1); ?>

Step 4

In file includes/templates/YOURTEMPLATE/templates/tpl_modules_checkout_new_address.php

Insert at the top (around line 13, after the comments):

<?php
require(DIR_WS_MODULES.'craftyclicks/crafty_html_output.php');
echo tep_crafty_script_add('checkout_address', 1);
?>

Find (around line 94):

<?php echo zen_draw_input_field('postcode', '', zen_set_field_length(TABLE_ADDRESS_BOOK, 'entry_postcode', '40') . ' id="postcode"') . (zen_not_null(ENTRY_POST_CODE_TEXT) ? '<span class="alert">' . ENTRY_POST_CODE_TEXT . '</span>': ''); ?>

Insert before the last semicolon:

. '&nbsp;&nbsp;' . tep_crafty_button_add(1)

The result should be:

<?php echo zen_draw_input_field('postcode', '', zen_set_field_length(TABLE_ADDRESS_BOOK, 'entry_postcode', '40') . ' id="postcode"') . (zen_not_null(ENTRY_POST_CODE_TEXT) ? '<span class="alert">' . ENTRY_POST_CODE_TEXT . '</span>': ''). '&nbsp;&nbsp;' . tep_crafty_button_add(1); ?>

Find (just below line 95):

<br class="clearBoth" />

Insert after:

<span id="crafty_postcode_result_display">&nbsp;</span>
<br class="clearBoth" />

Insert at the bottom of the file:

<? echo tep_crafty_country_handler(1); ?>

Step 5

In file includes/templates/YOURTEMPLATE/templates/tpl_modules_create_account.php

Insert at the top (around line 14, after the comments):

<?php
require(DIR_WS_MODULES.'craftyclicks/crafty_html_output.php');
echo tep_crafty_script_add('create_account', 1);
?>

Find (around line 110):

<?php echo zen_draw_input_field('postcode', '', zen_set_field_length(TABLE_ADDRESS_BOOK, 'entry_postcode', '40') . ' id="postcode"') . (zen_not_null(ENTRY_POST_CODE_TEXT) ? '<span class="alert">' . ENTRY_POST_CODE_TEXT . '</span>': ''); ?>

Insert before the last semicolon:

. '&nbsp;&nbsp;' . tep_crafty_button_add(1)

The result should be:

<?php echo zen_draw_input_field('postcode', '', zen_set_field_length(TABLE_ADDRESS_BOOK, 'entry_postcode', '40') . ' id="postcode"') . (zen_not_null(ENTRY_POST_CODE_TEXT) ? '<span class="alert">' . ENTRY_POST_CODE_TEXT . '</span>': ''). '&nbsp;&nbsp;' . tep_crafty_button_add(1); ?>

Find (just below around line 111):

<br class="clearBoth" />

Insert after:

<span id="crafty_postcode_result_display">&nbsp;</span>
<br class="clearBoth" />

Insert at the bottom of the file:

<? echo tep_crafty_country_handler(1); ?>

Step 6

In file admin/customers.php

Find (around line 485)

</head>

Insert before:

<?php
require(DIR_FS_CATALOG.DIR_WS_MODULES.'craftyclicks/crafty_html_output.php');
echo tep_crafty_script_add('customers', 1, true);
?>

Find (around line 703):

<?php
if ($error == true) {
if ($entry_post_code_error == true) {
echo zen_draw_input_field('entry_postcode', $cInfo->entry_postcode, zen_set_field_length(TABLE_ADDRESS_BOOK, 'entry_postcode', 10)) . '&nbsp;' . ENTRY_POST_CODE_ERROR;
} else {
echo $cInfo->entry_postcode . zen_draw_hidden_field('entry_postcode');
}
} else {
echo zen_draw_input_field('entry_postcode', $cInfo->entry_postcode, zen_set_field_length(TABLE_ADDRESS_BOOK, 'entry_postcode', 10), true);
}
?></td>
</tr>

Insert before ?></td>:

echo '&nbsp;&nbsp;' . tep_crafty_button_add(1);

Insert after the </tr>

<tr>
<td class="main">&nbsp;</td>
<td class="main" id="crafty_postcode_result_display">&nbsp;</td>
</tr>

The result should be:

<?php
if ($error == true) {
if ($entry_post_code_error == true) {
echo zen_draw_input_field('entry_postcode', $cInfo->entry_postcode, zen_set_field_length(TABLE_ADDRESS_BOOK, 'entry_postcode', 10)) . '&nbsp;' . ENTRY_POST_CODE_ERROR;
} else {
echo $cInfo->entry_postcode . zen_draw_hidden_field('entry_postcode');
}
} else {
echo zen_draw_input_field('entry_postcode', $cInfo->entry_postcode, zen_set_field_length(TABLE_ADDRESS_BOOK, 'entry_postcode', 10), true);
}
echo '&nbsp;&nbsp;' . tep_crafty_button_add(1);
?></td>
</tr>
<tr>
<td class="main">&nbsp;</td>
<td class="main" id="crafty_postcode_result_display">&nbsp;</td>
</tr>

At the bottom of the file, add:

<? echo tep_crafty_country_handler(1); ?>

Step 7 (optional)

Play around with configuration options near the top of file crafty_html_output.php.

On line 4: set CP_ADDRESS_LOOKUP_BUTTON_STYLE = 1 for a graphical button, or = 0 for a plain browser generated button. Or modify the html in function tep_crafty_button_add() to make up your own flavour.

County names are not required by Royal Mail. We recommend that county is left out from your address forms. To leave county out, simply remove the field in your html. If you want to keep the field, but want to prevent CraftyPostcode from populating it, go to lines 9 and change the define CP_COUNTY_NAME to 2.

If you prefer to use county names we provide two options: Traditional County Name and Postal County Name. To get the traditional county name set CP_COUNTY_NAME to 1. To go for the Royal Mail postal county name set it to 0 (default).

If you set the CP_HIDE_ADDRESS_LOOKUP_FOR_NON_UK_COUNTRY config to 1, the ‘find address’ button will be visible only if country is UK.

Step 8 (optional)

Enable searching by house name/number. In crafty_html_output.php you need to change:

define('CP_ENABLE_SEARCH_BY_HOUSE_NAME_NUMBER', 1);

Then in these files:

includes/templates/template_default/templates/tpl_modules_address_book_details.php includes/templates/template_default/templates/tpl_modules_checkout_new_address.php includes/templates/template_default/templates/tpl_modules_create_account.php

Find:

<label class="inputLabel" for="postcode"><?php echo ENTRY_POST_CODE; ?></label>

Insert before:

<?php
if (1 == CP_ENABLE_SEARCH_BY_HOUSE_NAME_NUMBER) {
?>
<label class="inputLabel" for="house_name">House Name/Number:</label>
<?php echo zen_draw_input_field('cp_house_name_number_in'); ?>
<br class="clearBoth" />
<?php
}
?>

Step 9 (Optional)

Hide address lines until lookup is complete. This can be a usability aid. In crafty_html_output.php you need to change:

define('CP_HIDE_ADDRESS_LINES_BEFORE_LOOKUP', 1);

In all files in steps 2.x place this before / after any lines you want hidden during lookup. Normally this will be address1,2,town, county.

<?php
if (CP_HIDE_ADDRESS_LINES_BEFORE_LOOKUP) { echo '<div id="crafty_hide_address_lines1" style="display:none;">'; }
?>

// … address lines html …

<?php
if (CP_HIDE_ADDRESS_LINES_BEFORE_LOOKUP) { echo "</div>"; }
?>

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 lookups 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: 4/1/2019, 1:32:39 PM