Expression Builder User Guide

Contents

  1. Introduction
  2. EAV
    1. Value Types
    2. Entity Attributes
      1. Cart Attributes
      2. Cart Item Attributes
      3. Product Attributes
  3. Expressions
    1. Expression Functions

Introduction

Expression Builder - Screen 1

Magento has an impressive built-in functions list which allows to manage various resources / entities (e.g. catalog categories, products, shipping rates, taxes, customers, orders, etc). But despite its functions variety the ability to create new rules and to change existing rules is limited. For example, Magento makes it possible to create shipping rates that depend on cart weight, cart price, cart items quantity or customer address. But the necessity to extend the existing business logic with the new parameters entails coding that can't be done by an average user. What if we need to consider the currency, the customer group or another parameter / attribute? Expression Builder can help us in this case. Expression Builder allows to set a dynamic value that depends on entity attributes and values related between each other with functions. In our example the shipping price is an expression which value can depend on any cart, cart item and product attribute.

EAV

For better scalability and compatibility Expression Builder implements its own EAV (entity-attribute-value) system as far as Magento EAV system doesn't match the Expression Builder requirements. The EAV system stores an entity copy to estimate with a given expression. There are 3 entity types currently: cart, cart item and product. Each entity type has its own attributes that has some value type.

Value Types

The full list of value types is illustrated below.

Value Types
Value TypeDescription
booleantrue or false.
integerInteger number that varies from -2147483648 to 2147483647. Integer is compatible with decimal and amount types.
integer arrayArray of integer numbers.
decimalDecimal number that varies from -99999999.9999 to 99999999.9999. Decimal is compatible with amount type.
decimal arrayArray of decimal numbers.
stringString which maximum length is limited to 255 characters. String is compatible with text type.
string arrayArray of strings.
textText which size is not more than 16 MB (mediumtext).
datetimeDatetime e.g. '2017-03-07 14:05:00'.
dateDate e.g. '2017-03-07'.
timeTime e.g. '14:05:00'.
datetime unitDatetime unit. Accepted values: year, month, week, day, hour, minute.
amountPrice amount that is fully compatible with decimal type.
amount arrayArray of amounts.
currencyCurrency code.
ipIP address. IP address is compatible with string type.
websiteWebsite identifier.
website arrayArray of website identifiers.
storeStore identifier.
customer groupCustomer group identifier.
countryCountry ISO ALPHA-2 code.
state/provinceRegion identifier.
product tax classProduct tax class identifier.
product visibilityProduct visibility identifier.
product attribute setProduct attribute set identifier.
product typeProduct type identifier.
categoryCatalog category identifier.
category arrayArray of catalog category identifiers.
cartCart entity.
cart itemCart item entity.
cart item arrayArray of cart items.
catalog productProduct entity.

As you can see a value can be simple / basic (value that is not entity or array), entity or array.

Entity Attributes

The full list of entity attributes is described below.

Cart Attributes

Cart Attributes
AttributeValue TypeDescription
websitewebsite
storestore
customer groupcustomer group
base currencycurrency
currencycurrency
origin countrycountry
origin state/provincestate/province
origin citystring
origin zip/postal codestring
origin street addressstring
countrycountry
state/provincestate/province
citystring
zip/postal codestring
street addressstring
customer emailstring
customer namestring
customer date of birthdate
customer companystring
customer ipip
coupon codestring
free shippingbooleanEither free shipping is enabled or not.
weightdecimalWeight of items.
free shipping weightdecimalWeight of free items.
base subtotalamount
subtotalamount
base virtual amountamountVirtual items subtotal amount in base currency.
virtual amountamountVirtual items subtotal amount.
base discount amountamount
discount amountamount
base tax amountamount
tax amountamount
created atdatetimeDatetime when cart entity is created.
item quantity 2decimalItems quantity.
free shipping item quantity 2decimalFree items quantity.
itemscart item arrayCart item entities array.

Cart Item Attributes

Cart Item Attributes
AttributeValue TypeDescription
quantitydecimalProducts quantity.
free shipping quantitydecimalFree products quantity.
weightdecimalWeight of products.
free shipping weightdecimalWeight of free products.
base subtotaldecimal
subtotaldecimal
base virtual amountdecimal
virtual amountdecimal
base discount amountdecimal
discount amountdecimal
base tax amountdecimal
tax amountdecimal
cartcart
productcatalog productProduct entity.

Product Attributes

Catalog Product Attributes
AttributeValue TypeDescription
attribute setproduct attribute set
category idscategory array
country of manufacturecountry
descriptiontext
allow gift messageboolean
allow gift wrappingboolean
price for gift wrappingamount
is in stockboolean
enable recurring profileboolean
meta descriptiontext
meta keywordstext
meta titlestring
minimal priceamount
namestring
set product as new from datedate
set product as new to datedate
open amount max valueamount
open amount min valueamount
priceamount
quantitydecimal
short descriptiontext
skustring
special price from datedate
special priceamount
special price to datedate
tax classproduct tax class
visibilityproduct visibility
websiteswebsite array
weightdecimal

Custom product attributes can be created by adding Magento product attributes. In admin menu Catalog → Attributes → Manage Attributes.

Expressions

At this stage, we can describe the expression creation process.

Expression Builder - Screen 2

The first step is select expression type: null, value, attribute, function.

Expression Builder - Screen 3

The second step is select the value type among the available. The value type can be specified for the expression initially. See the full list of value types above. This step is present if other than nul expression type is selected.

The expression type null returns null value as a result.

Expression Builder - Screen 4

The expression type value allows to set a simple value. The corresponding input element is displayed as the third step depending on the value type selected.

Expression Builder - Screen 5

The expression type attribute returns attribute value of estimated entity. The allowed attributes list is dispalyed as the third step depending on the value type previousely selected. See the full list of entity attributes above.

Expression Builder - Screen 6

The expression type function makes it possible to create compound, multi-level expressions. Each expression can include values, attributes and nested expressions. The list of available functions list returning selected value type is displayed in case of function expression type enabled. The full functions list see below.

Expression Builder - Screen 7

Once the function is selected the constructor requires function arguments to be entered. Each function argument is an expression itself. The arguments number can be fixed or dynamic.

Expression Functions

Expression Functions
FunctionValue TypesDescription
%arg1 = %arg2
  • return : boolean
  • arg1 : boolean, integer, decimal, string, text, datetime, date, time, datetime unit, amount, currency, ip, website, store, customer group, country, state/province, product tax class, product visibility, product attribute set, product type, category
  • arg2 : boolean, integer, decimal, string, text, datetime, date, time, datetime unit, amount, currency, ip, website, store, customer group, country, state/province, product tax class, product visibility, product attribute set, product type, category
Return true if %arg1 is equal to %arg2.
%arg1 != %arg2
  • return : boolean
  • arg1 : boolean, integer, decimal, string, text, datetime, date, time, datetime unit, amount, currency, ip, website, store, customer group, country, state/province, product tax class, product visibility, product attribute set, product type, category
  • arg2 : boolean, integer, decimal, string, text, datetime, date, time, datetime unit, amount, currency, ip, website, store, customer group, country, state/province, product tax class, product visibility, product attribute set, product type, category
Return true if %arg1 is not equal to %arg2.
%arg1 > %arg2
  • return : boolean
  • arg1 : integer, decimal, datetime, date, time, amount
  • arg2 : integer, decimal, datetime, date, time, amount
Return true if %arg1 is greater than %arg2.
%arg1 >= %arg2
  • return : boolean
  • arg1 : integer, decimal, datetime, date, time, amount
  • arg2 : integer, decimal, datetime, date, time, amount
Return true if %arg1 is greater or equal to %arg2.
%arg1 < %arg2
  • return : boolean
  • arg1 : integer, decimal, datetime, date, time, amount
  • arg2 : integer, decimal, datetime, date, time, amount
Return true if %arg1 is less than %arg2.
%arg1 <= %arg2
  • return : boolean
  • arg1 : integer, decimal, datetime, date, time, amount
  • arg2 : integer, decimal, datetime, date, time, amount
Return true if %arg1 is less or equal to %arg2.
%arg is null
  • return : boolean
  • arg : boolean, integer, decimal, string, text, datetime, date, time, datetime unit, amount, currency, ip, website, store, customer group, country, state/province, product tax class, product visibility, product attribute set, product type, category
Check if %arg is null.
%arg is not null
  • return : boolean
  • arg : boolean, integer, decimal, string, text, datetime, date, time, datetime unit, amount, currency, ip, website, store, customer group, country, state/province, product tax class, product visibility, product attribute set, product type, category
Check if %arg is not null.
%arg between %min and %max
  • return : boolean
  • arg : integer, decimal, datetime, date, time, amount
  • min : integer, decimal, datetime, date, time, amount
  • max : integer, decimal, datetime, date, time, amount
Check whether %arg is within a range of %min and %max.
%arg not between %min and %max
  • return : boolean
  • arg : integer, decimal, datetime, date, time, amount
  • min : integer, decimal, datetime, date, time, amount
  • max : integer, decimal, datetime, date, time, amount
Check whether %arg is not within a range of %min and %max.
%arg1 and %arg2
  • return : boolean
  • arg1 : boolean
  • arg2 : boolean
Return true if all arguments are equal to true.
%arg1 or %arg2
  • return : boolean
  • arg1 : boolean
  • arg2 : boolean
Return true if any argument equals to true.
not %arg
  • return : boolean
  • arg : boolean
Return true if %arg equals to false.
if %cond then %true else %false
  • return : boolean, integer, decimal, string, text, datetime, date, time, datetime unit, amount, currency, ip, website, store, customer group, country, state/province, product tax class, product visibility, product attribute set, product type, category
  • cond : boolean
  • true : boolean, integer, decimal, string, text, datetime, date, time, datetime unit, amount, currency, ip, website, store, customer group, country, state/province, product tax class, product visibility, product attribute set, product type, category
  • false : boolean, integer, decimal, string, text, datetime, date, time, datetime unit, amount, currency, ip, website, store, customer group, country, state/province, product tax class, product visibility, product attribute set, product type, category
If %cond is true returns %yes otherwise returns %no.
%arg like %pattern
  • return : boolean
  • arg : string, text
  • pattern : string
Check if %arg matches %pattern.
%arg not like %pattern
  • return : boolean
  • arg : string, text
  • pattern : string
Check if %arg does not match %pattern.
%arg match regexp %pattern
  • return : boolean
  • arg : string, text
  • pattern : string
Check if %arg matches regular expression %pattern.
%arg not match regexp %pattern
  • return : boolean
  • arg : string, text
  • pattern : string
Check if %arg does not match regular expression %pattern.
concatenate %arg1 and %arg2
  • return : string, text
  • arg1 : string, text
  • arg2 : string, text
Return string that results from concatenating arguments.
trim %arg
  • return : string, text
  • arg : string, text
Remove %arg leading and trailing spaces.
lowercase %arg
  • return : string, text
  • arg : string, text
Return %arg in lowercase.
uppercase %arg
  • return : string, text
  • arg : string, text
Return %arg in uppercase.
length %arg
  • return : integer
  • arg : string, text
Return number of characters in %arg.
substring %arg from %pos length %len
  • return : string, text
  • arg : string, text
  • pos : integer
  • len : integer
Return %len characters of %arg starting from %pos.
replace %arg from %from to %to
  • return : string, text
  • arg : string, text
  • from : string
  • to : string
Replace occurrences of %from to %to in %arg.
insert %arg from %pos length %len substring %substr
  • return : string, text
  • arg : string, text
  • pos : integer
  • len : integer
  • substr : string
Insert %substr into %arg at %pos position up to %len characters length.
in string %arg substring %substr
  • return : integer
  • arg : string, text
  • substr : string
Return position of first occurrence of %substr in %arg.
%arg1 + %arg2
  • return : integer, decimal, amount
  • arg1 : integer, decimal, amount
  • arg2 : integer, decimal, amount
Add arguments to %arg1.
%arg1 - %arg2
  • return : integer, decimal, amount
  • arg1 : integer, decimal, amount
  • arg2 : integer, decimal, amount
Deduct %arg2 from %arg1.
%arg1 * %arg2
  • return : integer, decimal, amount
  • arg1 : integer, decimal, amount
  • arg2 : integer, decimal, amount
Multiply arguments.
%arg1 / %arg2
  • return : decimal, amount
  • arg1 : integer, decimal, amount
  • arg2 : integer, decimal, amount
Divide %arg1 by %arg2.
%arg1 integer divide %arg2
  • return : integer
  • arg1 : integer
  • arg2 : integer
Return integer part of %arg1 divided by %arg2.
%arg1 % %arg2
  • return : integer
  • arg1 : integer
  • arg2 : integer
Return remainder of %arg1 divided by %arg2.
ceil %arg
  • return : integer
  • arg : decimal, amount
Return smallest integer value not less than %arg.
floor %arg
  • return : integer
  • arg : decimal, amount
Return largest integer value not greater than %arg.
round %arg
  • return : integer
  • arg : decimal, amount
Round %arg to integer.
power %arg by %power
  • return : integer, decimal, amount
  • arg : integer, decimal, amount
  • power : integer
Return %arg raised to power of %power.
extract %unit from %arg
  • return : integer
  • unit : datetime unit
  • arg : datetime, date, time
Extract %unit datetime unit of %arg.
increase date %arg by %inc %unit
  • return : datetime, date
  • arg : datetime, date
  • inc : integer
  • unit : datetime unit
Increase %arg by %inc of %unit datetime unit.
current datetime
  • return : datetime
Return the current datetime.
date of %arg
  • return : date
  • arg : datetime
Return the date part of %arg datetime.
time of %arg
  • return : time
  • arg : datetime
Return the time part of %arg datetime.
date difference %arg1 and %arg2
  • return : integer
  • arg1 : datetime, date
  • arg2 : datetime, date
Return the difference between %arg1 and %arg2 in days.
week day %arg
  • return : integer
  • arg : datetime, date
Return the weekday index for %arg (0 = Monday, 1 = Tuesday , ... and so on).
%arg in %array
  • return : boolean
  • array : integer array, decimal array, string array, amount array, website array, category array
  • arg : integer, decimal, string, amount, website, category
Check if %array contains %arg.
%arg not in %array
  • return : boolean
  • array : integer array, decimal array, string array, amount array, website array, category array
  • arg : integer, decimal, string, amount, website, category
Check if %array does not contain %arg.
sum(%array)
  • return : integer, decimal, amount
  • array : integer array, decimal array, amount array
Return the sum of %array array elements.
min(%array)
  • return : integer, decimal, amount
  • array : integer array, decimal array, amount array
Return the minimal %array array element.
max(%array)
  • return : integer, decimal, amount
  • array : integer array, decimal array, amount array
Return the maximal %array array element.
avg(%array)
  • return : integer, decimal, amount
  • array : integer array, decimal array, amount array
Return the maximal %array array element.
count(%array)
  • return : integer
  • array : integer array, decimal array, string array, amount array, website array, category array
Return the average value of %array array elements.