Blog posts tagged with 'ExcludeOption'

In a prior post, I presented an example where it was desired to Exclude Shipping Options from Carrier Plugins

Here’s a similar recent scenario I helped a client configure.  The client uses USPS and wanted to offer First Class Parcel, but not First Class Letter or First Class Postcards.   Out of the box, the USPS shipping plugin only has a checkbox for “First Class”.  USPS will return all applicable first class methods/rates that match the input dimensions (weight, height, etc.).  If you’re not using dimensions, or you have really small/light items (like physical gift cards), you could see the Letter & Postcards methods.  For example, if in the USPS plugin configuration page you check off First Class, Priority Mail Express, and Priority Mail, then you could get back all these options (if your cart is “light”):

USPS Priority Mail Express 1-Day™ ($25.25) 
USPS Priority Mail 2-Day™ ($6.00) 
USPS First-Class Mail® Parcel ($2.07) 
USPS First-Class Mail® Letter ($0.66) 
USPS First-Class Mail® Postcards ($0.33)

So, if you’re not using dimensions, or you have really small/light items and you don’t want to offer Letter & Postcards methods, then they can be excluded by Shipping Director using the [$Name] variable in the Option record’s Name Expression.

The client also wanted to exclude First Class Parcel if the cart contained certain items.   As per previous blogs, the recommendation is to create an unpublished Category for those products.  (Products can be in more than one category.)

And, to make this more interesting, let’s say that there are two stores.  The first store offers in-store pick up and the methods as described above.  The second store will only offer the “Priority Mail” methods.

First, on lines 10 & 20, it has the requisite checks for Address (because Estimate Shipping does not), and also includes on line 30 a check to reject PO Boxes.  On line 100 is the check if there are any items in the cart that should cause the Parcel method to be suppressed.  Line 110 is the in-store option, but the Expression is set to only allow it for store 1 ([$CurrentStoreId]=1).  Line 130 is the USPS option for store 1 (includes the Name filtering using the ternary if-then-else operator “ ? : “ ).  Finally, on line 150, is the USPS option for store 2 also using “ ? : “.  When an external shipping plugin (e.g. “Shipping.USPS”) is in the Rate Expression field, the Name Expression checks each method from the carrier, and if the expression evaluates to blank (“”) the method is suppressed.

Order	Type	Name	Expression	Rate Expression	Name Expression	Description Expression
10	ErrorExit	No State Entered	ShippingAddress.StateProvince = null			"Please enter Country, State, and Zip"
20	ErrorExit	No Zip Entered	ShippingAddress.ZipPostalCode = null			"Please enter Country, State, and Zip"
30	ErrorExit	No PO Boxes	ShippingAddress.Address1 != null and Regex.IsMatch(ShippingAddress.Address1, "(?i)\b(?:Post\ (?:Office\ )?|P[.\ ]?O\.?\ )?Box\b")			"Sorry, we can't ship to PO Boxes."
100	Boolean	SuppressParcel	Items.Any(Product.HasCategory("Suppress Parcel"))
110	Option	In-Store Pickup	[$CurrentStoreId]=1	0		"Customer will pick-up at our store in YourTown, NY"
130	Option	US Mail Store 1	[$CurrentStoreId]=1	Shipping.USPS	[$Name].Contains("Letter") or [$Name].Contains("Postcards") or ([$Name].Contains("Parcel") and [SuppressParcel]) ? "" : [$Name]
150	Option	US Mail Store 2	[$CurrentStoreId]=2	Shipping.USPS	[$Name].Contains("Priority Mail") ? [$Name] : ""

You can download the configuration import file by clicking on this link ShippingDirector (Exclude Letter and Postcards from USPS First Class).txt

NOTE:  This is an old blog.  nopCOmmerce no longer has ProductVariant.  Just use Product.  E.g.  (Product.Height * Product.Length * Product.Width)

In a previous blog, I showed how in SD you can calculate the shipping method name to show the customer using the Name Expression field on an Option record.  If the expression evaluates to a blank string, then SD will suppress the method.  Here's another example of how, for external shipping rate methods (carrier plugins like FedEx, USPS, etc.) which can return many options, it may be desirable to conditionally eliminate some options - or only show a single option.

In this example we'll offer the following USPS methods

USPS Priority Mail® Large Flat Rate Box
USPS Priority Mail® Medium Flat Rate Box
USPS Priority Mail® Small Flat Rate Box
USPS Priority Mail®

But we only want to show one - the best match based on the volume of items in the cart:

Order	Type	Name	Expression	Rate Expression	Name Expression
10	Reference	ItemVolume	(ProductVariant.Height * ProductVariant.Length * ProductVariant.Width)
20	Reference	CartVolume	Items.Sum([@ItemVolume] * Quantity)
30	Option	US Mail	true	Shipping.USPS	[$Name].Contains("Small") and [@CartVolume] <= 75 ? [$Name] : [$Name].Contains("Medium") and [@CartVolume] > 75 and [@CartVolume] <= 546 ? [$Name] : [$Name].Contains("Large") and [@CartVolume] > 546 and [@CartVolume] <= 792 ? [$Name] : [$Name] = "Priority Mail" and [@CartVolume] > 792 ? [$Name] : ""

Previously in this blog Exclude Shipping Methods by Specification Attribute we discussed checking a Product Specification Attribute.  The scenario was that if a product required assembly, that it could not be picked up in the store.

In this blog, we'll look at how to examine a Product Attribute.  (Product Attributes are actually Product Variant Attributes).    For example, let's say our "Assembled" attribute is something the customer chooses at the time of adding an item to a cart; they can choose a value of "Yes", or "No".   NopCommerce stores customer attribute choices in the shopping cart item's AttributeXml field.  However, we don't have to parse the XML - this field is a string, and we can just look for the correct <Value> tag in the string using the Contains() function.  Here's what a typical AttributeXml looks like for a product variant having only a single attribute  (I've added spacing and linefeeds for readability):

<Attributes>
     <ProductVariantAttribute ID="1">
         <ProductVariantAttributeValue><Value>1</Value></ProductVariantAttributeValue>
     </ProductVariantAttribute>
</Attributes>

It's that <ProductVariantAttributeValue><Value>1</Value> we are looking for - that number "1" in the value tag is the unique Id of the attribute value in the database table (just <Value>1</Value> would be enough, but I'll also include the parent tag to make it clear)

We'll use the same scenatio we did last time - Always offer Fedex, and only offer In-Store pickup if item does NOT require assembly (the leading "!" is the NOT operator).  Here we go...

Order	Type	Name	Expression	Rate Expression
100	String	Assembled Yes Tag	"<ProductVariantAttributeValue><Value>1</Value>"
200	Option	In-Store Pickup	!Items.Any( AttributesXml.Contains([Assembled Yes Tag]))	0
300	Option	FedEx	true	Shipping.Fedex

Yep, that's it!  You will, however, have to find the correct Value Id.  To do that, either check in the database - e.g:

-- Products (Variants) and their Attribute/Values
SELECT p.Name as ProductName, pv.Name as VariantName, 
       pa.Id as AttributeId, pa.Name as AttributeName,
       pvav.Id as ValueId, pvav.Name as ValueName
  FROM Product p
  join ProductVariant pv
    on pv.ProductId = p.Id
  join ProductVariant_ProductAttribute_Mapping m
    on m.ProductVariantId = pv.Id
  join ProductAttribute pa
    on pa.Id = m.ProductAttributeId
  join ProductVariantAttributeValue pvav
    on pvav.ProductVariantAttributeId = m.Id  
where pvav.Name = 'Small'    
order by p.Name, pv.Name, pa.Name, pvav.name

or, you can use Shipping Director to just dump out the AttributeXml to examine.  Set up this record:

Add new 'Shipping Director' record
Order	0
Active	checked
Type	ErrorExit
Name	AttributesXml
Expression	true
Description Expression	Items.First().AttributesXml

Then, put an item with desired selection in the cart and Estimate Shipping.

[Update 9/2014  - note that as of nopCommerce 3.0, there is no longer a ProductVariant, so just delete "ProductVariant." from any expression below]

You can have shipping calculations based on the product specification attributes of items in the cart.
As an example, let's exclude a shipping method if the "Assembled" specification attribute option is applied to any item in the cart:
We have configured a Specification Attribute "Assembly" having only a single option "Assembled", and we want to hide shipping option "In-Store Pickup" if any items in the cart have the "Assembled" specification attribute option.

Here how it looks if you're using an carrier rate calculation method like Fedex.  The first Option record is an "In-Store Pickup" defined in SD and will appear with $0 only if no products in the cart have "Assembled" attribute.
(We'll use a Reference as a shortcut to get the specification attributes to make it more readable):

Order	Type	Name	Expression	Rate Expression
100	Reference	Attributes	ProductVariant.Product.ProductSpecificationAttributes
200	Option	In-Store Pickup	!Items.Any([@Attributes].Any( SpecificationAttributeOption.Name = "Assembled"))	0
300	Option	FedEx	true	Shipping.Fedex

Here how it looks if you're using an internal rate calculation method like ByWeight, and defined a Shipping Method "In-Store Pickup" in Admin > Configuration > Shipping > Shipping Methods:

Order	Type	Name	Expression	Rate Expression	Name Expression
100	Reference	Attributes	ProductVariant.Product.ProductSpecificationAttributes
200	Option	Shipping By Weight	true	Shipping.ByWeight	[$Name] = "In-Store Pickup" and Items.Any([@Attributes].Any( SpecificationAttributeOption.Name = "Assembled")) ? "" : [$Name]

When Shipping Director processes the Option record, the Name Expression is computed for each shipping method option returned by the Shipping.Weight plugin (e.g. "In-Store Pickup", "Ground", "Air", etc.).

When a plugin returns multiple shipping options, calculating a specific Name Expression to blank will suppress that option. (the ternary opertator " ? : " acts like an if-then-else)

For the SpecificationAttributeOption in the above example, if you want to use the Id rather than the Name (e.g. your Name is localized, or it it might be changing in future), then be sure to check the SQL database table [SpecificationAttributeOption] to get the correct Id:
   ... .Any(SpecificationAttributeOption.Id = 1) ...

If you've localized your shipping methods names (i.e. created a language resource with Resource Name = "In-Store Pickup"), then be sure to use SD's GetLocaleString() function (must be assigned to a string variable) to get the localized name for use in the expression above:

Order	Type	Name	Expression
10	String	In-Store Pickup Text	GetLocaleString("In-Store Pickup")

Then in the Option record, reference the variable : ... $Name = [In-Store Pickup Text] and Items.Any(...

(P.S.  If you ever need to check the Attribute rather than an AttributeOption, then use SpecificationAttributeOption.SpecificationAttribute.Name .  For example, above we said we have a Specification Attribute "Assembly" having only a single option "Assembled".  But it could also have had two options: "Assembled" and "Not Assembled".  If we didn't care which option, but just that it had the "Assembly" Attribute, then we'd use SpecificationAttributeOption.SpecificationAttribute.Name = "Assembly".)

First, I recommend checking if a Country/State/Zip has been provided, because the “Estimate Shipping” will work even if they are not selected, and depending on rate calculation method (shipping plugin), you could get funny results, or an error. (Only US and Canada have states.)   For this, we use the ErrorExit record Type.  This will Exit if the Expression (condition) evaluates to true, and the customer will see the message calculated in the Description Expression.  Note, that this is a String Expression, so be sure to include quotes for a literal value.

Order	10
Type	ErrorExit
Name	Missing Country State Zip
Expression	ShippingAddress.Country = null or ShippingAddress.ZipPostalCode = null or ("US,CA".Contains(ShippingAddress.Country.TwoLetterIsoCode) and ShippingAddress.StateProvince = null)
Description Expression	"Please Enter Country, State, and Postal Code"

Then, let’s say we want to prevent shipping if the State is Alaska or Hawaii.  We would use the ErrorExit type here too:

Order	20
Type	ErrorExit
Name	No Shipping to Alaska and Hawaii
Expression	"AK,HI".Contains(ShippingAddress.StateProvince.Abbreviation)
Description Expression	"Sorry, we can’t ship to Alaska or Hawaii"

The condition Expression could have also been written as

Expression

ShippingAddress.StateProvince.Abbreviation = "HI" or ShippingAddress.StateProvince.Abbreviation = "AK"

But when using an “or”, be sure to use parenthesis if you have a more complex expression that includes “and”s too.

Alternately, you may just want to exclude just Ground shipping to Alaska and Hawaii.  For example, you want to use the Shipping.ByWeight rate calculation method, but don’t want to offer Ground to Alaska or Hawaii.  Then the above would instead be entered with an Option type:

Order	20
Type	Option
Name	Ship By Weight but no Ground for AK and HI
Expression	true
Rate Expression	Shipping.ByWeight
Name Expression	"AK,HI".Contains(ShippingAddress.StateProvince.Abbreviation) and [$Name].Contains("Ground") ? "" : [$Name]

For the Option type, the Expression field is a condition.  If it evaluates to true, then the option record is processed, otherwise it's skipped.  The Rate Expression can either be a decimal expression calculating the actual rate you want to charge, or the name of a shipping plugin.  The Name Expression calculates the shipping option Name shown to the customer.  However, if the Name Expression evaluates to blank (""), then Shipping Director will exclude the Option.  The [$Name] is a built-in variable that contains the Name of the shipping option as returned by the other rate caclulation plugin.  So, here we are saying "if the state is Alaska or Hawaii, then exlude the named option, else show the named option".  The If-Then-Else is achieved using the " ? : " ternary operator -  condition ? if-true : if-false.

(Updated 11/29/2013 for Shipping Director versions for nopCommerce 3.x) 

For external shipping rate methods (carrier plugins like FedEx, USPS, etc.), which can return many options, it may be desirable to conditionally eliminate some options.

In this example, we only offer USPS Media Mail if all items in the cart are books:

Order	Type	Name	Expression	Rate Expression	Name Expression
10	Boolean	CategoriesAllBooks	Items.All(Product.HasCategory("Books"))
100	Option	USPS	true	Shipping.USPS	[$Name].Contains("Media Mail") and ![CategoriesAllBooks] ? "" : [$Name]

Of course you're not limited to checking Categories.  For example, you could also eliminate an option based on there being any item in the cart with the Product Name Length greater than X.  E.g.

Items.Any(ProductVariant.Product.Name.Length > 12)

_________________________________________________________________________________________________  

Here's the old version for nopC 2.x having Product Variants, and prior to SD having HasCategory() function:

Order	Type	Name	Expression	Rate Expression	Name Expression
10	Reference	categories	ProductVariant.Product.ProductCategories
20	Boolean	categoriesAllBooks	Items.All([@categories].Any(Category.Name = "Books"))
100	Option	USPS	true	Shipping.USPS	[$Name].Contains("Media Mail") and ![categoriesAllBooks] ? "" : [$Name]