Blog

When you configure  Shipping > Shipping Rate Computation Methods, be sure that Shipping.Director is the only "Is Active".
You can still configure the other methods you need.  When you want to 'call' another rate method, just put the name in the Rate Expression field  (no quotes)  E.g.

Option    Fed Ex    true    Shipping.Fedex

. 

The Shipping Director is an "evaluation engine".  Each row is evaluated based on "Order".  (Some old school VB developers may notice the numbering scheme in the example screen below. :)  The "Type" of each row is either a variable (String, Boolean, etc.), an Error, or a shipping Option.  For Variables, the "Expression" field should evaluate to the type of the declaration.  For Error and Option, the "Expression" field is a 'condition' that should evaluate to a boolean - if true, the additional expressions are evaluated (rate, surcharge, etc.), and if false, the next row is examined.  You can specify whether the rows continue to evaluate, or "Exit" when matched - ErrorExit, OptionExit.  Additionally, there is (not shown below) a global settingEvaluation Match Type: "Evaluate All" vs. "EvaluateFirstMatchOnly", whereby a plain Exit or Option will exit if EvaluateFirstMatchOnly is set.

Below are some sample expressions in context of the Configure screen.   (Note that NameExpression and DescriptionExpression must evaluate to strings - if you just have text, be sure to enclose it in double quotes.)

(Update: 12/20/2021 - This is a very old blog.  Some of the properties have changed.  Contact us at support@noptools.com for up-to-date information.)

The previous blog discussed expressions, and that the underlying attributes of the Shopping Cart can be referenced.  Below is a partial shopping cart hierarchy.  You use a dot (".") between attributes in the hierachy to reference children.  Some attributes are collections (lists), that can contain 0 or more other objects.  All expressions must yield a scalar value, so collections must have some Query Operator applied like All() [a boolean], or Sum() [a decimal].

Some query operators, like All(), will return a boolean.  For example, Any() will return true if any items in the collection meet the criteria.  For example - The customer has the Administrator role:

Customer.CustomerRoles.Any(Name = "Administrators")

Some query operators, like Where(), will return a subset which is still a collection, so a First() operator must then be applied and then probably followed with an attribute name.  This Where().First() is a common scenario.  For example,  check if customer has the role with Any() above, and then check if that  role is Active:

and Customer.CustomerRoles.Where(Name = "Administrators").First().Active  

 Customer                Customer
     Id                      1
     Username                user@optonline.net
     Email                   user@optonline.net
     AdminComment            NULL
     LanguageId              NULL
     CurrencyId              NULL
     TaxDisplayTypeId        0
     IsTaxExempt             False
     VatNumber               NULL
     VatNumberStatusId       0
     CheckoutAttributes      
     DiscountCouponCode      
     GiftCardCouponCodes     
     UseRewardPointsDuringCheckout    False
     TimeZoneId              NULL
     AffiliateId             NULL
     Active                  True
     IsSystemAccount         False
     SystemName              NULL
     CreatedOnUtc            9/3/2011 2:08:02 AM
     Affiliate               NULL
     Language                NULL
     Currency                NULL
     CustomerRoles           Collection[CustomerRole]
         Id                      1
         Name                    Administrators
         FreeShipping            False
         TaxExempt               False
         Active                  True
         IsSystemRole            True
         SystemName              Administrators

     CustomerAttributes      Collection[CustomerAttribute]
         Key                     FirstName
         Value                   John


         Key                     LastName
         Value                   Smith


         Key                     LastVisitedPage
         Value                   http://localhost:7872/


         Key                     LastShippingOption
         Value                   


         Key                     LastContinueShoppingPage
         Value                   http://localhost:7872/m/261/test           


         Key                     Gender
         Value                   


         Key                     DateOfBirth
         Value                   


         Key                     Company
         Value                           


 Items                   List[ShoppingCartItem]
         Id                      16
         ProductVariantId        59
         CustomerEnteredPrice    0.0000
         Quantity                1
         CreatedOnUtc            10/5/2011 3:12:37 AM
         UpdatedOnUtc            10/15/2011 1:52:19 AM
         ProductVariant          
             Id                      59
             ProductId               58
             Name                    Box Cutter
             Sku                     123456789
             Description             NULL
             AdminComment            NULL
             ManufacturerPartNumber    099999
             IsGiftCard              False
             GiftCardTypeId          0
             ...
             IsDownload              False
             ...
             IsFreeShipping          False
             AdditionalShippingCharge    0.0000
             IsTaxExempt             False
             TaxCategoryId           0
             ...
             CallForPrice            False
             Price                   52.9100
             ...
             Weight                  1.0000
             Length                  0.0000
             Width                   0.0000
             Height                  0.0000
             ...
             Product                 System.Data.Entity.DynamicProxies.Product
                 Id                      58
                 Name                    Box Cutter
                 ShortDescription        NULL
                 ...
                 ProductCategories       Collection[ProductCategory]
                     Id                      14
                     ProductId               58
                     CategoryId              72
                     IsFeaturedProduct       False
                     DisplayOrder            1
                     Category                Category
                         Id                      72
                         Name                    Box Cutter Knife, Blades
                         Description             NULL
                         ...


                 ProductManufacturers    Collection[ProductManufacturer]
                     Id                      14
                     ProductId               58
                     ManufacturerId          5
                     IsFeaturedProduct       False
                     DisplayOrder            1
                     Manufacturer            Manufacturer
                         Id                      5
                         Name                    ABC Industries
                         Description             NULL
                         ...



 ShippingAddress         Address
     FirstName               NULL
     LastName                NULL
     Email                   NULL
     Company                 NULL
     CountryId               1
     StateProvinceId         40
     City                    NULL
     Address1                NULL
     Address2                NULL
     ZipPostalCode           10021
     PhoneNumber             NULL
     FaxNumber               NULL
     CreatedOnUtc            1/1/0001 12:00:00 AM
     Country                 Country
        Country : 1
     StateProvince           StateProvince
        StateProvince : 40
     Id                      0

 CountryFrom             NULL
 StateProvinceFrom       NULL
 ZipPostalCodeFrom       

Expressions are created by referencing variables that you define, or the underlying attributes of the Shopping Cart.  Expressions are built using variables and properties of the shipping request (e.g. Customer, Items collection, etc.).   Simple expressions just use typical operators like "+", "-", "and", "or", etc.  Queries use a variant of Linq syntax (no lambda symbol "=>" required).  Queries are applied to collections to "extract" the items in the collection that meet the query criteria.

When variable names are used in expressions, they must be enclosed in square brackets - e.g. [ZipCode3].  Variables can be boolean, string, decimal, integer, etc.  Query expressions and Attributes are referenced without enclosing brackets.  Most attributes are "objects" that themselves contain other attributes.  Some attributes are collections (lists), that can contain 0 or more other objects.  Developers having a familiarity with the nopCommerce shopping cart object and linq syntax certainly have an advantage when creating expressions, but the syntax is not that hard to grasp given some examples, and future blogs will discuss the cart,, and provide more examples.  Here are some examples that may commonly be used:

(Update: 12/12/2012 - see this for more about Variable and Expression Data Types )

(Update: 12/20/2021 - Customer.CustomerRoles won't work in 4.x and above.   Use Customer.GetCustomerRoles() to get the full collection, or to check a specific role, use helper property  Customer.IsInRole("role system name") )