OZPOST MODULE – Rod G April 2009
This module is all new code based on lessons learned from development of the 'AustPost improved' module.
It currently supports over 30 different shipping options ranging from small letters through to Express Courier international.
All methods can be enabled/disabled with a simple checkbox. Some of the improvements made over the original module are:
· Improved OOP code (should work well with the upcoming Zencart V2 release)
· Only a single quotation server is now used for all quotes (no more nasty redirects) and a much improved response time.
· Quotes are returned in XML format, making for much simpler processing and future expansion (e.g. more postage methods, not necessarily Australia Post)
· Improved debugging
· Icons can be enabled/disabled with a simple checkbox.
· Icons now better controlled and will only show in the quotation windows (regular text will be used on invoices, etc)
Please note this is ALL NEW CODE. At time of writing this (and uploading to the server) it has had very limited testing. Don't be surprised if a bug or two exists. PLEASE REPORT ANY PROBLEMS FOUND.
********************************************************************************
Although not advisable, this module can be run in conjunction with the AustPost improved module. This means that the more brave among you can try this module and if it doesn't work, simply disable it and re-enable the original. You'll have virtually no down time. Enjoy!
********************************************************************************
This module relies on data obtained from ozpost.vcsweb.com. Data is returned in XML format for easy integration into almost any e-commerce site. http://ozpost.vcsweb.com is a free service. No registration or subscription required.
********************************************************************************
Installation:
------
Unzip and copy the files into their default destinations (i.e. same file structure as the zip archive).
There is one file that goes into the 'classic' template directory by default. If you are using a different template/theme then you will need to relocate the file "tpl_modules_shipping_estimator.php" to suit.
The following admin files are overwritten. A backup is recommended (although in an emergency they can be restored from the Zencart distribution files):
/admin/includes/languages/english/product.php
/admin/includes/modules/update_product.php
/admin/includes/modules/product/collect_info.php
After installation:
Log on to /admin/ select modules/shipping, locate this module (ozpost), click 'install' then set your shipping methods and packaging & handling fees.
Enjoy!
********************************************************************************
Although all care has been taken to ensure that all quotes a 'valid', there are times where you'll find that things just aren't right.
The most common cause for invalid quotes is because the 'kgs/gms' setting is incorrect.
Although zen-cart appears to use 'lbs' as its default weight, this is little more than a 'display' value. The actual weight is basically a number of 'units'.
e.g. if you set an item’s weight as "10", this could be 10lbs, 10gms, or 10kgs.
The Australia Post module assumes your weights are either gms or kgs (not lbs), but it is up to you to specify the correct option when you configure the module.
Tip: If you haven't entered any product data yet, use the following rule of thumb:
If *most* of your products weight 1kg or more, use 'kgs'.
If *most* of your products weight less than 1kg, use 'gms'.
If you have already entered product weight data then choose the setting that matches the data you have input.
Whatever you elect to use, KEEP YOUR WEIGHTS CONSISTANT. Don't try to use gms for some items, and kgs for others because it isn't going to work correctly.
Almost any invalid quote can usually be identified by temporarily enabling the 'debug' option to see exactly what data is being sent to the servers.
The DEFAULT settings in the AustPost module will preclude the use of letter rates (even if enabled).
If you wish to offer your customers letter rates it is highly recommended that you set suitable dimensions on the items that are 'letter sized' rather than alter the 'default' dimensions, because this will help prevent larger items (with no dimensions defined) from being classed as a letter.
Please check the Australia Post website for details as to what constitutes a 'letter'.
********************************************************************************
PATCHING
MOST USERS WILL NEVER NEED TO DO THIS!
If you prefer (or need) to patch your own /admin/ files (so you can easily edit product dimensions)
The file : /admin/includes/modules/update_product.php needs to have the following lines added.
Look for:
......
$tmp_value = zen_db_prepare_input($_POST['products_weight']);
$products_weight = (!zen_not_null($tmp_value) || $tmp_value=='' || $tmp_value == 0) ? 0 : $tmp_value;
......
Insert/Add:
......
$tmp_value = zen_db_prepare_input($_POST['products_height']);
$products_height = (!zen_not_null($tmp_value) || $tmp_value=='' || $tmp_value == 0) ? 0 : $tmp_value;
$tmp_value = zen_db_prepare_input($_POST['products_length']);
$products_length = (!zen_not_null($tmp_value) || $tmp_value=='' || $tmp_value == 0) ? 0 : $tmp_value;
$tmp_value = zen_db_prepare_input($_POST['products_width']);
$products_width = (!zen_not_null($tmp_value) || $tmp_value=='' || $tmp_value == 0) ? 0 : $tmp_value;
......
Then a few lines further down, locate
......
$sql_data_array = array('products_quantity' => $products_quantity,
'products_type' => zen_db_prepare_input($_GET['product_type']),
'products_model' => zen_db_prepare_input($_POST['products_model']),
'products_price' => $products_price,
'products_date_available' => $products_date_available,
'products_weight' => $products_weight,
......
(yours may not look *exactly* like this if you have applied other patches, as I have done)
Insert:
......
'products_height' => $products_height,
'products_length' => $products_length,
'products_width' => $products_width,
......
Then, in the /admin/includes/modules/product/collect_info.php file, find: (at the very start of the program)
......
$parameters = array('products_name' => '',
'products_description' => '',
'products_url' => '',
'products_id' => '',
'products_quantity' => '',
'products_model' => '',
'products_image' => '',
'products_price' => '',
'products_virtual' => DEFAULT_PRODUCT_PRODUCTS_VIRTUAL,
'products_weight' => '',
......
Insert:
......
'products_height' => '',
'products_length' => '',
'products_width' => '',
......
Find:
......
if (isset($_GET['pID']) & empty($_POST)) {
$product = $db->Execute("select pd.products_name, pd.products_description, pd.products_url,
p.products_id, p.products_quantity, p.products_model,
p.products_image, p.products_price, p.products_cost, p.products_markup, p.products_margin_gross_dollar, p.products_margin_gross_percent, p.products_virtual, p.products_weight,
p.products_date_added, p.products_last_modified,
date_format(p.products_date_available, '%Y-%m-%d') as
products_date_available, p.products_status, p.products_tax_class_id,
p.manufacturers_id,
......
Insert:
p.products_height,p.products_length, p.products_width,
......
Find:
......
<tr>
<td class="main"<?php echo TEXT_PRODUCTS_WEIGHT; ?</td>
<td class="main"<?php echo zen_draw_separator('pixel_trans.gif', '24', '15') . ' ' . zen_draw_input_field('products_weight', $pInfo->products_weight); ?</td>
</tr>
......
Insert:
......
<tr<td class="main"<?php echo TEXT_PRODUCTS_HEIGHT ; ?</td>
<td class="main"<?php echo zen_draw_separator('pixel_trans.gif', '24', '15') . ' ' . zen_draw_input_field('products_height', $pInfo->products_height); ?</td>
</tr<tr<td class="main"<?php echo TEXT_PRODUCTS_LENGTH; ?</td>
<td class="main"<?php echo zen_draw_separator('pixel_trans.gif', '24', '15') . ' ' . zen_draw_input_field('products_length', $pInfo->products_length); ?</td>
</tr<tr<td class="main"<?php echo TEXT_PRODUCTS_WIDTH; ?</td>
<td class="main"<?php echo zen_draw_separator('pixel_trans.gif', '24', '15') . ' ' . zen_draw_input_field('products_width', $pInfo->products_width); ?</td>
</tr>
......
Configuration options / notes
------
GST
If you are registered for GST, please set the appropriate tax class for your particular setup.
This does not affect the quotations in any way, but it does affect the GST display calculations.
Dimensions
Please set some *default* dimensions for the parcels that you will be mailing out. These dimensions are used when there are no dimensions found for a specific product.
Note: Dimensions are in centimetres.
COD
Although this module offers COD as a _shipping method_, if you wish to use it, you will also need to install/activate the COD _payment_ module, available from www.zencart.com (but DON'T assign any fees or charges to it).
This apparent duplication is required because after selecting a shipping method (in this case COD), the next screen presented is the payment options (along with provision for gift voucher and coupon redemptions). Without a COD option on this screen too, a COD paying customer will never be able to check-out.
DEBUG
DO NOT ENABLE IN A PRODUCTION ENVIRONMENT.
If enabled, this module will echo a considerable amount of debugging information to the screen. You'll find this very useful if things aren't working correctly.
Admin:
The products database will have 3 new fields added (length, height, width) when you install this module. These fields are NOT removed if you uninstall this module. No harm is done by leaving them intact, and if you did enter data into these fields you probably wouldn't want them removed anyway.
Dimensions for individual products are an over-ride of the default dimensions (see above), they can be added or edited via the usual admin interface.
A word about cubing:
Getting this module to support the cubing rules has not been an easy task. I'm not a mathematician, nor am I an expert in 3d modelling, and there were some tough choices that needed to be made when multiple items of different dimensions are purchased at the same time. Simply adding the cubes of each item wouldn't give a 'real world' parcel size.
length width height cube
Example: parcel 'A' 100cm x 50cm x 20cm = 100,000ccm
parcel 'B' 10cm x 10cm x 10cm = 1,000ccm
If we sum the cubes, we get 101,000ccm.
However, how big will our parcel be? We can’t use the cube root (46.57) because it is kinda obvious that we probably shouldn't be chopping item 'A' in half or scrunching it up to make it fit inside of 'cube'.
What I opted to do was to 'stack' the objects on top of the largest item purchased. Using the same parcels above, this means our parcel will need to be:
100cm x 50cm * (20cm + 10cm) = 150,000ccm - i.e. there's going to be a lot of 'air' in the box.
This problem is compounded if a person buys 2 of item 'B', because although both you and I know that we can stack the two small items side by side on top of the larger item I really don't have the foggiest idea of how to tell the software that we can do that, so what it does is stack all three items, giving a parcel size of:
100cm x 50cm * (20cm + (10cm x 2)) = 200,000ccm - i.e. there's going to be a lot more 'air' in the box.
This means that some of your quotes will probably end up higher than reality, because in this case we can easily fit both items into a box measuring 100x50x20.
If THAT isn't enough to worry about, the fact that we are stacking items means that we run a real risk of exceeding the maximum 'length' of any given parcel. If we assume someone buys 20 of item "B", when we stack 'em we get a parcel measuring 200x10x10 - the 'height' becomes the 'length' and this parcel will be too long to mail. Of course, in the 'real world' we wouldn't pack these items in this manner - we'd stack them in rows and columns instead of the single dimension - these 20 items would fit into a box measuring 100x20x10 and even 50x20x20, depending how they are stacked, both boxes are well within the limits imposed by AustPost.
To help alleviate this scenario the software performs a check on the calculated height of our stacked parcel, and if it exceeds the 105cm limit I set the width of our parcel to 105, then recalculate the 'new' height.
Another check is then performed on the *girth* of the parcel to ensure that doesn't exceed the allowed maximum, and if it does, the parcel is then rejected as being unquotable.
THE END