WooCommerce Shipping Plugin Developer Notes

WooCommerce Logo Myfreight Logo Myparcel logo

Developer Notes

If you wish to customise the WooCommerce Shipping Plugin for Myfreight/Myparcel to your website's specific requirements, the following sections provide some guidelines on how to do this. For further assistance in customising the plugin, contact your Myfreight account manager or raise a Myparcel support request.

 

Customising the Address Helper

The Address Helper assists the customer in the correct entry of suburbs, states and postcodes, and may appear on the Cart page, the Checkout page and/or the Single Product page, depending upon your selections in the Myfreight/Myparcel administrator settings.

Note that the following plugin is required to display the shipping calculator and Address Helper on single product pages:

  • "WooCommerce Shipping Calculator on Single Product Page" by Magerips

 

There are 3 ways to customise the styling of the Address Helper:

1. Change the text on the Apply button

The text label on the button used to apply a new locality (suburb, state and postcode) may be changed to suit your requirements by entering text into appropriate field(s) in the Myfreight/Myparcel administrator settings.

You can even include brief instructions on the button such as "Enter suburb, select, then click here".

2. Use CSS or JS to change the styling

The Address Helper fields can be styled with CSS using the selector div#cart_locality_field as the starting point.

For example, to change the width of the suburb/postcode input field, add the following to the theme's "style.css" file (Appearance → Theme Editor):

div#cart_locality_field input {
width: 300px;
}

Note that the original WooCommerce "Calculate shipping" form (with 4 input fields) remains on the Cart page, but is hidden. To unhide this form, use JS to remove the class "hide_change_address" from the element div#cart_locality_field.

3. Use PHP hook to fully customise the Address Helper HTML

The Address Helper HTML can be changed or re-arranged using the WordPress filter hook 'my_locality_helper'.

Following is an example of how to intercept and modify the HTML prior to rendering the page. It uses the WordPress "add_filter" function to access the raw HTML (provided by the $html argument) before customising and returning it. The $placement argument contains text indicating the page location of the Address Helper ("cart", "billing", "shipping" or "product"), so that the HTML can be modified independently for each location if required.

Insert the code into the theme's "functions.php" file (Appearance → Theme Editor → Theme Functions):

/* Customise Myfreight Address Helper HTML */
add_filter( 'my_locality_helper', 'customise_helper', 10, 2 );
function customise_helper( $html, $placement ) {
// Change the input placeholder text
$html = str_replace( 'Enter suburb or postcode', 'Start entering suburb or postcode', $html );
// Add context specific instructions below the Apply button
switch ( $placement ) {
case 'cart':    // Helper on cart page
$html .= '<p class="helper-instructions">Adding instructions on Cart page</p>';
break;
case 'billing':    // Helper on checkout page in billing column
$html .= '<p class="helper-instructions">Adding instructions on Checkout page for Billing</p>';
break;
case 'shipping':    // Helper on checkout page in shipping column
$html .= '<p class="helper-instructions">Adding instructions on Checkout page for Shipping</p>';
break;
case 'product':    // Helper on single product page
$html .= '<p class="helper-instructions">Adding instructions on Single Product page</p>';
break;
}
return $html;
}

Any PHP string manipulation functions can be used to alter the HTML as required. However, be aware that element id's and classes are used by the plugin CSS and Javascript to hide and style elements and should be modified with care.

 

Changing the Shipping Item Type

Shipping pricing varies according to the type of item being shipped, even if the weights and dimensions are unchanged. Couriers generally offer a lower price for Satchels compared to cartons, while large national carriers generally offer a lower price for pallets compared to cartons (as they are more easily handled with a forklift).

By default, the item type will be automatically estimated from the product weight and dimensions. If there is no clear item type, the default item type is assumed to be "Carton".

You can programmatically change both the default item type and the item type estimation calculation using a PHP hook.

1. Use PHP hook to change default Item Type

The default item type can be changed from Carton using the WordPress filter hook 'my_est_item_type'.

Following is an example of how to set the default item type to Pallet.

Insert the code into the theme's "functions.php" file (Appearance → Theme Editor → Theme Functions):

/* Customise Default Shipping Item Type */
add_filter( 'my_est_item_type', 'default_shipping_item_type', 5, 8 );
function default_shipping_item_type( $item_type, $quantity, $weight, $length, $width, $height, $shipping_class, $account ) {
return 'Pallet';
}

This will set the default item type to Pallet prior to auto item type estimation being invoked. If you wish all item types to be Pallet, simply disable "Auto Item Type Activation" in the Myfreight/Myparcel Shipping Settings.

Note that any item type specified for a product using the product's Shipping Class will still override the default item type.

2. Use PHP hook to customise Item Type calculation

You can provide your own item type estimation using the WordPress filter hook 'my_est_item_type'.

It is recommended that you start by copying and renaming the function "estimate_item_type" from the plugin file "myfreightshipping/myfreight-ancillary.php".

Insert the code into the theme's "functions.php" file (Appearance → Theme Editor → Theme Functions):

/* Customise Shipping Item Type Estimation */
add_filter( 'my_est_item_type', 'custom_shipping_item_type', 10, 8 );
function custom_shipping_item_type( $item_type, $quantity, $weight, $length, $width, $height, $shipping_class, $account ) {
// Insert your custom code here ...
return $custom_item_type;
}

This will set the shipping item type to whatever string the function returns. You should disable "Auto Item Type Activation" in the Myfreight/Myparcel Shipping Settings to prevent unnecessary processing.

Note that any item type specified for a product using the product's Shipping Class will still be passed to your custom function. You have the option of accepting or overriding Shipping Class defined item types.

The arguments passed to the 'my_est_item_type' filter functions have the following types:

string $item_type (normally 'Carton', 'Satchel', 'Skid', 'Pallet' or null)
int $quantity
float $weight
int $length
int $width
int $height
string $shipping_class
string $account ('Myfreight' or 'Myparcel')

 

Changing the Packing Method

Whenever there is more than 1 product item in the Cart, Checkout or Order, there is the option of shipping them as individual items or as a single item packed together. The packing option chosen may affect the cost of shipping, the eligible transport carriers, and the type of shipping service required (e.g. whether a truck with tailgate lift is required because the packed item now exceeds 30kg).

By default, it is assumed that multiple product items will be packed together and shipped as a single shipping item. The weight, dimensions and shipping item type are estimated by the plugin. Obviously, it is not always possible to predict how items are packed together with 100% accuracy.

If you would rather de-activate the auto packing estimate, simply untick the Myfreight/Myparcel shipping setting "Auto Packing Activation".

If you wish to customise the auto packing calculation you can do so programmatically using a PHP hook.

1. Use PHP hook to customise Item Packing calculation

You can provide your own packing estimation using the WordPress filter hook 'my_pack_items'.

It is recommended that you start by copying and renaming the function "auto_pack_items" from the plugin file "myfreightshipping/myfreight-ancillary.php".

Insert the code into the theme's "functions.php" file (Appearance → Theme Editor → Theme Functions):

/* Customise Shipping Packing Estimation */
add_filter( 'my_pack_items', 'custom_shipping_pack_items', 10, 3 );
function custom_shipping_pack_items( $shipping_items, $pricing, $packing_item ) {
// Insert your custom code here ...
return $custom_packed_shipping_items;
}

This transforms multiple product items into minimal packed shipping items. You should disable "Auto Packing Activation" in the Myfreight/Myparcel Shipping Settings to prevent conflict between packing functions.

The first parameter passed to the hook function ($shipping_items) is an array of line items, with each line item being an array containing details of the line item (item type, quantity, weight, length, width, height). This 2-dimensional array of line items should be modified (if appropriate) and returned by the function.

The second parameter passed to the hook function ($pricing) is a boolean flag indicating whether this packing is being done for cart/checkout pricing purposes rather than order booking purposes. This informs whether only minimal details need be returned for each line item (no reference or dangerous goods fields required).

The third parameter passed to the hook function ($packing_item) is a boolean flag indicating whether any line item products have a "Packing Unit" specified in their product Shipping tab. This parameter can usually be ignored.