This is a shipping module originally written for one of our sites as we couldn't find anything already written that would allow us to do what we needed.

This module allows you to setup zones based on lists of UK postcodes, generic postcodes, county codes or country codes, each zone has a base shipping rate and the module has 6 choices for how to modify that base rate. The module also has quite a few extra options - see the readme file below for full details.

We're offering this module as is for the VM community, it has been tested and refined with feedback by various members of the VM forums (our thanks to them).

Please post support requests to http://forum.virtuemart.net/index.php?topic=82598.0.

NEW - version 1.51, several bug fixes - see Readme below for details.

Updating

Originally the module zip file contained a default config file. I've now removed this and the module will create the config file if it doesn't exist. Also if the module finds a config file from an older version of the module it will perform and upgrade on the config file preserving your current settings. This means it is perfectly safe to update any older version of this module with the current version just by uploading the contents of the zip file and you will keep all current settings.

Todo

Zones, options etc are currently marked for deletion with an empty name, which means a zone that is not named will not be saved. Change deletion marking to use a hidden form field to fix this.

Add a debug setting that echo's out information.

Rate types per zone to override the module wide rate type setting.

Option to set free shipping for the pre tax order total or the post tax order total.

An Inclusion / Exclusion list for shipping options so that a particular option can be turned on or off depending on the zone that the customers address falls into.

Expander for inner London postcodes (eg can write EC1A-F)

Sector zone match type. Matches on the UK postcode including the last digit (eg the sector for my postcode - TR18 2ES- would be TR182)

Expander for sector postcodes (eg can write TR181-9)

Modify generic postcode match type definitions to use a substr() style definition of start and length options.

Auto upgrade of instances.

UK postcode/county/country code zones shipping module. Creates zones that are matched to UK postcodes or county or country codes. v1.51

(C) 2011 altcom Ltd (http://www.altcom.co.uk)

Elements of this Open Source development were sponsored by Ellmore Consultancy, http://www.ellmoregroup.com

Installation
------------

Upload the files to /administrator/components/com_virtuemart/classes/shipping/

Configuration
-------------

Go to Components->VirtueMart.
Click on the Admin tab and click Configuration then the Shipping tab.
Tick the check box for "UK Postcode, State or Country Zones: Shipping rates by zones defined by UK centric postcodes or states or country codes" to enable the module.
Click on the Store tab and click Shipping module List.
Find the "UK Postcode, State or Country Zones" entry and click Configure Ship Method.

Options
-------

Carrier Name: This is the name shown in the shipping information on the order screen and also the start of the name in the checkout ship methods stage.

Zone Type: you can set what part of the address a zone will match, one of: UK Postcode, Generic Postcode, State 2 Code, State 3 Code, Country 2 Code or Country 3 Code.

Tax Rate: set the tax rate for shipping.

Enable default zone: you can enable a default zone to catch any postcodes that don't match any zones you've set up, you can give teh default a name and base rate just like normal zones.

No zone match message: text to display if the default zone is disabled and the postcode doesn't match any normal zones (can be left blank to display no message).

Rate type: you can choose from 6 rate types - flat rate, percentage of order total, by weight, by weight bands, by price bands or by items bands, see below for more info.

Shipping options: you can create shipping options that will present extra choices to the user and modify the zone rate (eg 9am delivery, Saturday delivery etc - see below for more details).

Maximum shipping rate: you can set a maximum shipping rate to cap the amount of shipping charged (can be used to give free shipping for a period without changing the zones or max £50 shipping etc).

Total order price for free shipping: you can set an amount to trigger free shipping. Each zone also has a free shipping option and here you can set which overrides the other. Please note that it has been reported that setting the virtue mart free shipping option can interfere with this option so please make sure the virtue mart free shipping is disabled before using this.

Check address is in GB: if enabled the module will check if the address country is GB and immediately exit if not. If enabled you can enter a message to show if country is not in GB.

Not allowed product message: message to show if the customer has added a product(s) that are disallowed for the zone.

Show list of disallowed products: choose whether to display a list of the disallowed products that are in the users cart.

Zones
-----

Each zone has the following settings.

Zone name: the name of the zone (this does not have to be unique so you can create several different zones with different matching criteria but the same name to give the illusion of one zone).

Postcodes/States/Country codes in zone: a comma seperated list of matches for this zone. The Zone Type setting controls what will be matched against here, either postcodes or parts of postcodes as controlled by the match type setting (see below) or state 2, state3, country 2 or country 3 codes.

Base rate: the base amount to charge for the zone (or the percentage of the total order to charge if the rate type is set to "Percentage of Total Order"), this will be modified depending on the rate type settings (see below) and the shipping option choosen (if any).

Free Shipping

Match type: (only used if Zone Type is set to UK Postcode or Generic Postcode).

For UK Postcode each zone can be set to match either the "area" or "outward" part of the postcode or the full postcode. The "area" part is the first letter(s) (eg TR for Cornwall where I live), the "outward" part is the letter(s) and number(s) upto the space (eg TR18 for Penzance), the full postcode is, of course the full postcode.

For Generic Postcode each zone can be set to match the full postcode or any number of user created match types. User created match types are given a name and a pattern, the pattern consists of the characters o and x where o is a character to skip and x is a character to keep for the match, any characters after the last x will be dropped. The x's must all be contiguous and there is no point adding o's after the x's. Eg "xxx" means use the first 3 characters of the postcode to match against and "ooxx" means use the 3rd and 4th charcters of the postcode to match against. "xox" would be incorrect and "xoo" would be a redundant use of o's.

If the zone type is Generic Postcode you can enter postcode ranges like "50-53" as an equivalent for "50,51,52,53".

Likewise if the zone type is UK Postcode and a zone is set to "outward" match type you can enter postcode ranges like "TR15-18" as an equivalent of writing "TR15,TR16,TR17,TR18". There are no ranges for area or full match zones.

A postcode will always be tried against all "full" match zones first then for UK Postcode against "outward" match zones and finally "area" match zones, for Generic Postcodes any user match types will be checked in the order the match types were created (oldest first).

This allows you to setup a full match zone for a handfull of postcodes around your business (eg "TR181AB,TR182BC,TR183ED"), then an outward match zone for your postcode district (eg "TR18") and finally area match zones for the 'standard' zones for your carrier (eg "TR,PL,TQ"). this way the postcode TR18 1AB will match the full match zone, while TR18 9ZZ will match the outward match zone and TR19 4FG will match the area match zone.

See http://en.wikipedia.org/wiki/List_of_postcode_areas_in_the_United_Kingdom for a list of all the "area" postcodes in the UK. See http://en.wikipedia.org/wiki/Postcodes_in_the_United_Kingdom for an overview of UK postcodes.

Allowed Products: here you can add a comma seperated list of product id's to configure products that are not allowed for this zone. As with generic postcode you can enter ranges of numbers like "3-9" as an equivelant for "3,4,5,6,7,8,9". You can also set whether the list is ignored and all products are allowed ("Allow All"), only the products on the list are allowed ("Allow Only These") or allow all products except those listed ("Disallow These")

Rate Type
---------

As stated above there are 6 rate types to choose from.

Flat rate
---------

The zone's base rate will be charged no matter what the order contains.

Percentage of Order Total
-------------------------

The shipping rate will be calculated as a percentage of the total order value where the percentage is the zone's base rate. eg. if the total order value is £100 and the zone's base rate is 10 then the shipping rate will be 10% of £100 or £10.

By weight
---------

You set a weight amount (in kg's) for the base rate and any extra weight will be charged in multiples of the base rate. So an order with a total weight of upto the amount set will be charged the zone's base rate, an order with up to twice the amount will be charged twice the zone's base rate etc.

You can also configure whether to show info of the weight on the shipping method choice list eihter nothing, show the number of "units" of weight or show the total weight. If you set the show option you can set a display label and whether to pluralise the lable.

As an example if you needed to be able to charge shipping per pallet with each item taking one or more pallets you could: Set the rate type to "By weight" and set the amount to 1 and to display the number of units of weight with a display label "pallet" with pluralise lable enabled. Then you can set the weight of each item to 1 kg for each pallet it takes and the shipping method will charge 3 times the base rate for an item taking 3 pallets and will show "3 pallets" on the choose shipping method choice. Obviously this will only work if all items are to be shipped on pallets, it would be possible to have items with 0 weight and they wouldn't add extra pallets to an order but they would still count as one pallet if they where the only item in an order.

By weight band
-------------

You can set up weight bands with a minimum weight to trigger the band and a modifier to apply to the zone's base rate. The modifier can be either a multiplication (*x), a division (/x), an addition (+x), a subtraction (-x) or a setter (=x) and it will be applied to the zone's base rate.

So if you set a band with a minimum of 1kg and a modifier of +5 and a second band with a minimum of 5kg and a modifier of +10 then an order with a total weight of less than 1kg
will cost the zone's base rate, while orders from 1kg but less than 5kg will add £5 to the zone's base rate while orders of 5kg+ will add £10 to the zone's base rate.

By price band
-------------

Works the same as By weight band above except the total price of the order is used.

So if you set a band with a minimum of £10 and a modifier of +5 and a second band with a minimum of £100 and a modifier of =0 then an order of less than £10
will cost the zone's base rate, while orders between £10.01 and £99.99 will add £5 to the zone's base rate while orders of £100+ will be charged £0.

By Items band
-------------

Works similar to By price band above except that the bands affect the number of items that fall within that band.

So if you set up a band with a minimum of 3 and a modifier of /2 and a second band with a minimum of 10 and a modifier of =0 then the first and second item would be charged the zone's base rate each, the third until the ninth item would be charged 1/2 the zone's base rate each and the tenth item upwards would not be charged.

Shipping Options
----------------

These have a name and a modifier (as above the modifier can be +,-,/,* or =).

When the module ouputs it's radio button on the shipping method choice stage of the checkout it will show an additional radio button choice for each option set.

So if you set an option with name equals "9am delivery" and modifier equals +15 and another option with name equals "Saturday delivery" and modifier equals +25 on the shipping methods stage of the checkout you will get 3 radio buttons from this module:

   ( ) STD, Zone 1: £10
   ( ) STD, Zone 1 [9am delivery]: £25
   ( ) STD, Zone 1 [Saturday delivery]: £35

Multiple modules
-----------------

This module can only be configured for one zone type and with the zones for one carrier, however the module has been designed to be "cloned" as easily as possible to allow multiple versions to act for seperate zone types and / or couriers.

To create a new module instance click on Add instance in the Instances fieldset and enter a name and description for the new module instance. When you save the settings the new instance will be created with a default config, you will need to enable it on the Admin tab and click Configuration then the Shipping tab.

You can delete an instance (other than the main or current instance) by clicking on Delete next to the desired instance - it will be deleted when you save the settings (be careful doing this as you won't be asked twice and the instance's config file will be deleted and then cannot be recovered).


Versions
--------
v1.51 2011/2/24

Fixed error in sql selecting users shipping info where in some versions of VirtueMart the state field is set to " - " if a state is not selected instead of "-".

Fixed error where destination postcode was set in the description of the shipping rate even when match type was set to county or country code.

Added code to strip spaces from comma seperated lists which otherwise would cause items not to match.

Added javascript to validate the modifier parameters to highlight invalid user input.


v1.5 2011/2/18

Added zone based disallowed products by product id with configurable message and option to list the products in the cart that have been disallowed.


v1.4 2010/09/27

Fixed error in the postcode expansion (AA1-3 into AA1,AA2,AA3) that stopped it working.

Fixed error saving user entered strings with a ' (apostraphe) in the config file.

Added new "generic_postcode" Zone Type which doesn't use UK specific postcode matches. Instead added the ability to create new Match Types to control which part of the post code the zone will match on.

Added functionality to only show rate type options for the currently selected rate type.

Added ability to enable / disable shipping options so you can remove them without deleting them.

Added functionality to create / delete extra module instances to handle different carrier zones or other situations that require seperate configuration options.


v1.3 2010/08/04

Fixed error in sql selecting user info not working when country doesn't have states.


v1.2 2010/08/03

Fixed error rendering zones when Zone Type set to non UK Postcode setting.


v1.1 2010/07/05

Fixed By Items band rate type not getting number of items.


v1 2010/06/24

No changes, bumped version for release on VMED.


v0.7 2010/06/14

Added option to check zones on UK Postcode, State code or Country code.

Added "Percentage of Total Order" Rate Type option.

Changed "Check address is within GB" option to "Check address is within country" with a drop down box to choose country.

Fixed error in "new zone" javascript which stopped new zones from appearing on the config page.


v0.6 2010/06/04

Added zone based free shipping and an option for whether the base free shipping or the zone free shipping overrides the other.

Removed the free shipping text from options when free shipping is triggered.

Added version number to config file and the module. Module now detects version of config file and can upgrade it in place without losing current configuration.


v0.5 2010/05/24

Fixed maximum rate option wouldn't work if set to 0.

Fixed total order price for free shipping wouldn't work if set to 0.

Fixed instance name being appended to class name when working out config file name.

Changed the order that weight/price/item bands are stored in the config file so they are the correct way round for testing in the rate calculation code and need to be reversed for showing on the config screen.


v0.4 2010/05/13

Fixed weight and price band minimums wouldn't allow decimal numbers.

Added <br /> tags after the last rate and option radio buttons and also the no default zone and not in GB messages.


v0.3 2010/05/11

Added weight bands.


v0.2 2010/05/10

Fixed weight calculation only worked with products having whole number units of weight and the rate limit also in whole numbers.


v0.1 2010/04/23

Initial version released to Virtue Mart forum for testing.