Blog posts of '2013' 'March'

In evaluation mode, the Director plugins will allow 5 rate calculations from the front end store.   However, you can use the "Test" button in the Director configuration page as many times as you want; it's much easier to test from this page.  I suggest you "Test" as much as possible in the configuration page, and then do a final check when ready in the front end store. 

When you click on the Test button, you are presented with a dialog.  The default "0" means the currently logged in Customer (You, the admin :) .  You can enter a different Customer using Id, Username, or Email:

First, though, you must add items to cart for that user and go thru the checkout process to the point of selecting your shipping address*.  Then return to Director configuration page to test.  You can do this for the currently logged in user (you as admin), or as admin you can also "Impersonate" users and do same.  This allows you to set up many different test cases.

* Required for Shipping Director, for Payment Director, it depends on if you reference the shipping address, or cart items, or order totals in any Expressions.

The results of the test will appear in the upper left portion of the configuration page.   Green check marks are valid Options that the customer would see (rate amounts are not formatted for currency).  Red X's would be Errors (the messages that the customer would see, not the Fatal Errors that get logged in the System > Log).

Note!  Test calculation results will not take into account any nopCommerce core shipping "adjustments" - such as "Free shipping over X", "Free shipping if all items in cart are marked as Free Shipping", shipping discounts, etc.

In certain scenarios, you may want to look at Checkout Attributes to do some conditional processing.  For example, your shipping carrier might charge extra to ship to a residential address.  You could just add a Price adjustment to the Attribute Value, however there are some drawbacks to that:

1) The Price Adjustment shows up in the sub total area as an itemized item.  You may want it to just be included right in the shipping rate, and/or you may not want your customer to know what the surcharge is.

2) You can't apply it conditionally - e.g. don't want to include it for customers with certain roles.

3) You can't calculate the surcharge value (the price adjustment is fixed)

Older versions of Shipping Director required that you use  XML parsing via SelectSingleNode().  As of version 1.07 Shipping Director has the following built in variables (and Payment Director too):

$CheckoutAttributeValues

$CheckoutAttributeLocalizedValues

These are variables that contain the checkout attributes returned as a String of concatenated name:value pairs (colon separator).  Each pair is terminated with "|".

For our residential address example, we would set up a checkout attribute named "Shipping Address Type" using control type "radio button list", and we would add two Attribute Values: Residential Address and Commercial Address

Then, this could be used in the Option's Surcharge Expression:

   ([$CheckoutAttributeValues].Contains("Shipping Address Type:Residential Address") ? [Fedex Residential Surcharge] : 0)

(The decimal variable [Fedex Residential Surcharge] would be declared beforehand)

You use ErrorExit rather than OptionExit when you want to show an error message to the customer, and not allow them to continue the checkout process.   In nopCommerce 2.50, they introduced a hidden setting:  shippingsettings.returnvalidoptionsifthereareany; the default is 'true' which is to show successful options if any.   The setting was added so that when using multiple external shipping plugins\carriers, and one of the carriers returns with successful shipping methods, that it would still present them to the customer, rather than showing the failed carrier's error message.

If you check all your error conditions up front, then the default setting is OK.  If however, you check for errors in the middle of Option records, then you may want to change the setting to 'false' if using ErrorExit.

If you've set up your records as multiple OptionExit records expecting that the first matching one will be the only shipping method offerred to the customer, you might follow it with a final ErrorExit in case none of the conditions match:

OptionExit  <some condition> ...

OptionExit  <some condition> ...

ErrorExit     true ... "Error Message"

In this case either setting is OK.

For large $ orders, it may be desirable to enforce that the shipping address is the same as the billing address.  Use an ErrorExit to check it:

In the Expression, the term "ShippingAddress.Address1 != null" checks to see that we are not in "Estimate Shipping".  The Customer object is used by nopC to "save" the addresses selected during checkout.

P.S. The match above is done with the Address.Id .  That means it's the exact same address record.  If the customer may have entered two different address records with the same Street/City/Zip, then you can adjust the above to check the individual fields instead - e.g.

!(Customer.ShippingAddress.Address1 = Customer.BillingAddress.Address1 and Customer.ShippingAddress.ZipPostalCode = Customer.BillingAddress.ZipPostalCode)

Shipping Director introduced a Sort Expression in version 1.07.  The sort expression should evaluate to a string that represents an 'ordering clause'.  The ordering clause is one or more (comma separated) shipping option fields: Rate, Name, Description.  Each field can optionally be followed by ASC or DESC (the default is ASC = Ascending).   

Examples (Don't forget, it's a string Expression, so it's typically enclosed in double quotes):
"Rate ASC" 
"Name DESC" 

Example using ternary if-then-else  - If the cart weight <= 150, then sort by Rate, otherwise use the default sort. (The default is used when the expression results in blank string):
[$TotalWeight] <= 150 ? "Rate ASC" : "" 

In this example, we'd like to sort by Rate, but we want the "Pick up ..." option at the end, so sort by Name "prefix" then Rate:

"Name.SubstringBefore("" ""), Rate" 

FedEx Ground ($15.23) 
FedEx Express Saver ($51.51) 
FedEx Standard Overnight ($88.95) 
FedEx Priority Overnight ($108.35) 
Pick up at our warehouse ($0.00) 

UPDATE 2020-09-17  More example sort expressions:

Explicit sort of names (using ' ? : '  if-then-else operator):  

"Name = ""Ground"" ? 1 : Name = ""Priority"" ? 2 : Name = ""Special"" ? 3 : 4"