Blog posts tagged with 'Variables'

When writing expressions, it is typically necessary to access the objects within the "context" of the calculation (for both Shipping Rates and Payment Methods).  The context includes the Customer and the Shopping Cart (Items) among other objects.  For example, if you need to know how many items are in the cart, the expression might look like:  Items.Count().   Items is a collection, and "Count()" is a a built in method (Linq) that counts the number of items in a collection.  NopCommerce objects have properties - e.g. a (shopping cart) Item has a Product property and a Quantity property.  So, Items.Count() is not really an accurate count of the # of products in the cart.  To do that, you need to sum the Quantity: Items.Sum(Quantity).   Without going into details about writing Linq expressions, suffice it to say that to use them in SD & PD it's necessary to access properties of nopCommerce objects, and we sometimes need helper methods that are more specific to nopCommerce objects (see this blog about Shopping Cart Object and Query Operators , but note it's based on the older nopCommerce versions that had product variants).  So, here's a list of helper methods (and also includes String helper methods). To use them, follow the nopCommerce object with a "." followed by the method name - e.g. Customer.IsInRole("Member").  In the future, I'll come back and fill in the Description column with more info/examples.

Class / Extension	Return	Description
String
SubstringAfter(value [,includeDelimiter = false])	String
SubstringBefore(value [,includeDelimiter = false])	String
SubstringBetween(value [,includeDelimiter = false])	String
SubstringRemove(value     [,stringComparison = StringComparison.InvariantCulture])	String
SubstringRemoveIgnoreCase(value)	String
ToTitleCase()	String
ToOnlyAlphaAndDigits()	String
Split(string [,separator])	String
IsNumeric()	Boolean
IsInteger()	Boolean
SelectSingleNode(xpath)	XmlNode
Customer
IsInRole(roleSystemName) (or  IsInCustomerRole(roleSystemName)  )	Boolean	E.g. Customer.IsInRole("Free Shipping")  Be sure to assign the Role's "System name" field. If you need to do a wildcard match, use e.g.  Customer.CustomerRoles.Any(SystemName.Contains("Discount")) (UPDATE: The  CustomerRoles collection  no longer works as of SD for 4.30 -
GetAttribute(attributeName)	String
GetAttributeValues(attributeName [valueSeparator])	String	attribute value, or if list/checkboxes, then separated list of selected values for attribute (nopC 3.30+)
HasAttributeValue(attributeName) HasAttributeValue(attributeName, valueName) HasAttributeValue(attributeName, valueId)	Boolean	True if has attribute [and value]
HasDiscountCouponCode("couponcode")	Boolean	True if customer used coupon code. (Case is ignored,)
AppliedDiscountCouponCodes()	string[]	You can use .Contains(), .Any(), etc. to test the array Example: Customer.AppliedDiscountCouponCodes().Any()
GetOrders()	Orders collection
GetRewardPointsBalancePoints()	Integer
GetRewardPointsBalanceAmount()	Decimal
Product
HasCategory(categoryName)	Boolean	Example: Product.HasCategory("Free Shipping")
HasCategory(categoryId)	Boolean	Example: Product.HasCategory(5)
HasCategoryMatch(categoryNameRegex)	Boolean	Example: Product.HasCategoryMatch("Brushes")     (has a category that has the word "Brushes" in its name)
HasParentCategory(categoryName)	Boolean
HasParentCategory(categoryId)	Boolean
HasParentCategoryMatch(categoryNameRegex)	Boolean
HasManufacturer(manufacturerName)	Boolean
HasManufacturer(manufacturerId)	Boolean
ShoppingCartItem
GetWeight()	Decimal	Shopping Cart Item Weight (Includes attribute weight if any.) (The weight is for single item; multiply by Quantity if required)
GetAttributeValues(attributeName [, valueSeparator = ", "])	String	returns string of separated values for given attributeName
HasAttributeValue(attributeName [, valueName])	Boolean	if no valueName param passed, then any for given attributeName
HasAttributeValue(valueId)	Boolean
GetVendor()	Vendor
GetVendorAddresses()	Address collection
GetShippingOriginAddress()	Address	If the product has a warehouse assigned, then this returns that warehouse's address, otherwise it returns the shipping origin address in Shipping Settings. example: surcharge if any cart items are being shipped from Zip Code 12345  Decimal  Surcharge    Items.Any(GetShippingOriginAddress().ZipPostalCode = "12345") ? 2 : 0
GetWarehouse()	Warehouse
GetSubTotalWithDiscounts()	Decimal
GetSubTotalWithoutDiscounts()	Decimal
HasSku(sku)	Boolean	Will also test against product attribute combinations SKU
Address
ToSenderString([defaultIfNone])	String	*
GetState()	StateProvince	In Shipping Director you can just use State to get the two character state abbreviation. In Payment Director you can use ShippingAddress.GetState().Abbreviation
GetCountry()	Country	In Shipping Director you can just use Country to get the two character country code. In Payment Director you can use ShippingAddress.GetCountry().TwoLetterIsoCode
ZipPostalCode	string	In Shipping Director you can just use Zip to get the postal zip code. In Payment Director you can use ShippingAddress.ZipPostalCode
GetAttributeValues()	string	Since attributes can be defined as checkboxes that can multi-select this function can return a comma separated value If your field is a Text Box expecting a numeric value, you can parse it Example: Decimal.Parse(ShippingAddress.GetAttributeValues("MinShippingAmount"))
Warehouse
ToSenderString([defaultIfNone])	String	**
GetAddress()	String	Check that a product has a warehouse before using this.  It's safer to use an Item's GetShippingOrigiAddress() (see above)
(Root)
GetLocaleStringResourceByName(resourceName)	String

*SenderStringFormat - Address

{Company}:Address={Address1};City={City};StateProvince={StateProvince};ZipCode={ZipPostalCode};Country={Country.TwoLetterIsoCode};

*SenderStringFormat - Warehouse

{Warehouse.Name}:Address={Address1};City={City};StateProvince={StateProvince};ZipCode={ZipPostalCode};Country={Country.TwoLetterIsoCode};

Be sure your expression is of the correct type whether assigned to a variable, or used in one of the Expression fields of a record.  Here are the types for the various Expression Fields:

Record/ExpressionName	Data Type	Description
Option and OptionExit
Expression	Boolean	When evaluates to true, the Option is presented to customer
Rate Expression	Decimal	The calculated Rate + Surcharge appears to customer as the rate
Surcharge Expression	Decimal
Name Expression	String	If present, will override the record Name displayed to customer
Description Expression	String	If present, the description appears under the Name/Rate line
Error and ErrorExit
Expression	Boolean	When evaluates to true, the Error message is presented to customer
Description Expression	String	Required.  The description appears under the Name/Rate line
Packing		See the Packing blogs
Expression	Boolean	When evaluates to true, the packing is performed
Packing Method	literal	E.g. Packing.FirstFitSingleBox  .
Requires Own Package Expression	Boolean	Evaluated for each item
Sender Expression	Boolean	Evaluated for each item
Exclude Item Expression	Boolean	Evaluated for each item
Reference		See the Reference Type blog
Expression	literal	A reference is a type of variable that is really just a shortcut.
Notes
Booleans	You can use literals 'true' and 'false'.   (lowercase, no quotes)
Strings	Be sure to put literals in double quotes. To put a double quote in your literal, use two double quotes. If using String.Format(), beware of localization.
Decimals, Doubles, Singles	Literals must include a decimal point "." regardless of localization If using e.g. Decimal.Parse(), beware of localization.
DateTimes	Construct literals using DateTime() - e.g. DateTime(2010,8,9).  If using DateTime.Parse(dateString), beware of localization parsing.
Rate and Surcharge Expression	Numeric only.  Do not include any leading currency symbol.

Here's a list of all built-in variables.  Note that they all start with a "$".  As with user defined variables, the must be enclosed in brackets when used - e.g. [$TotalWeight].

     

Shopping Cart Properties - Set by system at start of rate calculation
$TotalWeight Decimal   uses ShippingService.GetShoppingCartTotalWeight()

$SubTotalWithoutDiscounts Decimal    (uses orderTotalCalcService.GetShoppingCartSubTotal() )

$SubTotalWithDiscounts Decimal

$SubTotalWithoutDiscountsInclTax Decimal

$SubTotalWithDiscountsInclTax Decimal

$ProductTotalWithoutDiscounts Decimal    (uses PriceCalculationService.GetSubTotal() )
$ProductTotalWithDiscounts Decimal

$IsFreeShipping Decimal   uses OrderTotalCalcService.IsFreeShipping()

Shipping Director Record - Set by system for each row (used in debugging and error messages)
$Id Integer   SD record's Id field
$Order Integer   SD record's Order Field
$Name String   SD records's Name field
$Expression String   Set before each expression evaluated (Expression, RateExpression, SurchargeExpression, etc.)

Option Processing - Set by system when the record type is Option, OptionExit, OptionReplace (OptionReplace available only in SD ver 1.05 and above)
$Name String 
$Description String
$Rate Decimal (e.g. surcharge expression can use $Rate)
The Option record's Expressions can reference $Name & $Description & $Rate variables.  Thus, you can adjust the data returned by external shipping rate methods.  (Reminder – an external shipping rate method is called in the Option’s Rate Expression – e.g. Shipping.Fedex).
External shipping rate methods can return multiple options/rates.  If the $Name of an external shipping rate option is set to "", then that option is removed.
Example: To show an option name of just "Ground" and "Priority" rather than "FedEx Ground" and "FedEx Priority", use [$Name].Replace("FedEx ", "") in the NameExpression to remove the word "FedEx " from the option name.

 

Shipping Option Request properties (These are passed to other shipping rate calculation methods to override the other methods' configuration page.  Not supported by all shipping rate methods.)
$ZipPostalCodeFrom String
$StateProvinceFrom String
$CountryFromTwoLetterIsoCode String

Set by system after other shipping rate calculation method is called
$ShippingOptionsCount Integer

SD sets this after using an external shipping plugin (or SQL) with the total # of shipping rate options it returned.  It's not typically used, but if you are doing something where you think no options will match, then you should check it and say something like "call for rate".

Packaging
$Sender string ""   Set by system when a package is rated manually (not external shipper rate).  Can then be used in Option's Rate, Surchage, Name, Description expressions
$PackageCount Integer 0   Set by system after packaging.  Although defaults to 0, if no Packaging is done, the system actually creates 1 package with all shopping cart items just before rate calculation.

Packaging using PackingFirstFitSingleBox
$PackageBoxWeight Decimal
$PackageBoxMaxWeight Decimal
$PackageBoxHeight Decimal
$PackageBoxLength Decimal
$PackageBoxWidth Decimal
$PackageItemAddWeight Decimal
$PackageItemAddDimension Decimal
$PackageShrinkPercent Integer 0 - Used by PackingFirstFitSingleBox - If $PackageShrinkPercent > 0, and the volume actually packed is less than this % of the given box volume, then this will shrink the final box to its actual packed content volume, rather than the given box volume.  ("less than this %" => The idea is if the box is "almost full", then use the box dimensions)

Packaging's SenderExpression can evaluate to a string that can contain Ship From Location information.  The string is of the form:
"State=...; ZipCode=...; Country=...;"
This allows different Ship From address for each Sender (see Shipping Option Request properties above):

$PackageBox variable (shorthand for setting many package attributes in one line)
 e.g. $PackageBox   "MaxWeight:40,Height:15,Width:15,Length:15"
 Here's how each shorthand attribute corresponds to the built in variable:
    MaxWeight    => $PackageBoxMaxWeight
    Height       => $PackageBoxHeight
    Width        => $PackageBoxWidth
    Length       => $PackageBoxLength
    Weight       => $PackageBoxWeight
    AddWeight    => $PackageItemAddWeight
    AddDimension => $PackageItemAddDimension
    ShrinkPercent=> $PackageShrinkPercent

Rate Request Type - When Packaging, can be set by user to indicate the way that rate requests are made to other rate calculation methods when Packaging
$ShippingRateRequest String
    "OneRequestForAllPackages"
    "OneRequestPerPackage"
    "OneRequestPerSender"

E.g. "OneRequestPerPackage" => Get FedEx rates separately for each package

if $ShippingRateRequest is not set by user, then the system will default depending on if the Packing SenderExpression used:
    if no SenderExpression then "OneRequestForAllPackages" else  "OneRequestPerSender"

Debugging

$Debug boolean false   When true, detailed messages are written to the system log.

(Note:   Because log messages are not HTML formatted, they can be hard to read in the browser.  So, when viewing a System Log record, click View to see the log detail page.  Then, right click the page and "View Source".  Scroll down (a bit more than half way) until you see the plain text messages.)

Flow Control  (SD ver 1.05 and up)
$Goto Integer 0 Set to a Order/Line number. Can be conditional and dynamic. Set to 0 to skip.  E.g. Use ternary if/then/else operator $Goto condition ? 100 : 0 ==> "If condition then Goto 100 (else goto next line)"

Special Functions
Special functions must be assigned to a String variable and must be the first word in the variable’s Expression field.  The expression cannot be complex: E.g. it can be like GetLocaleString("...") or GetLocaleString([someotherstringvar]), but cannot include any operators.

GetLocaleString(<string>)   get a language specific message.
GetSetting(<string>)        get a setting