Expression Builder User Guide

Introduction
EAV
1. Value Types
2. Entity Attributes
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 Type	Description
boolean	true or false.
integer	Integer number that varies from -2147483648 to 2147483647. Integer is compatible with decimal and amount types.
integer array	Array of integer numbers.
decimal	Decimal number that varies from -99999999.9999 to 99999999.9999. Decimal is compatible with amount type.
decimal array	Array of decimal numbers.
string	String which maximum length is limited to 255 characters. String is compatible with text type.
string array	Array of strings.
text	Text which size is not more than 16 MB (mediumtext).
datetime	Datetime e.g. '2017-03-07 14:05:00'.
date	Date e.g. '2017-03-07'.
time	Time e.g. '14:05:00'.
datetime unit	Datetime unit. Accepted values: year, month, week, day, hour, minute.
amount	Price amount that is fully compatible with decimal type.
amount array	Array of amounts.
currency	Currency code.
ip	IP address. IP address is compatible with string type.
website	Website identifier.
website array	Array of website identifiers.
store	Store identifier.
customer group	Customer group identifier.
country	Country ISO ALPHA-2 code.
state/province	Region identifier.
product tax class	Product tax class identifier.
product visibility	Product visibility identifier.
product attribute set	Product attribute set identifier.
product type	Product type identifier.
category	Catalog category identifier.
category array	Array of catalog category identifiers.
cart	Cart entity.
cart item	Cart item entity.
cart item array	Array of cart items.
catalog product	Product 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
Attribute	Value Type	Description
website	website
store	store
customer group	customer group
base currency	currency
currency	currency
origin country	country
origin state/province	state/province
origin city	string
origin zip/postal code	string
origin street address	string
country	country
state/province	state/province
city	string
zip/postal code	string
street address	string
customer email	string
customer name	string
customer date of birth	date
customer company	string
customer ip	ip
coupon code	string
free shipping	boolean	Either free shipping is enabled or not.
weight	decimal	Weight of items.
free shipping weight	decimal	Weight of free items.
base subtotal	amount
subtotal	amount
base virtual amount	amount	Virtual items subtotal amount in base currency.
virtual amount	amount	Virtual items subtotal amount.
base discount amount	amount
discount amount	amount
base tax amount	amount
tax amount	amount
created at	datetime	Datetime when cart entity is created.
item quantity 2	decimal	Items quantity.
free shipping item quantity 2	decimal	Free items quantity.
items	cart item array	Cart item entities array.

Cart Item Attributes

Cart Item Attributes
Attribute	Value Type	Description
quantity	decimal	Products quantity.
free shipping quantity	decimal	Free products quantity.
weight	decimal	Weight of products.
free shipping weight	decimal	Weight of free products.
base subtotal	decimal
subtotal	decimal
base virtual amount	decimal
virtual amount	decimal
base discount amount	decimal
discount amount	decimal
base tax amount	decimal
tax amount	decimal
cart	cart
product	catalog product	Product entity.

Product Attributes

Catalog Product Attributes
Attribute	Value Type	Description
attribute set	product attribute set
category ids	category array
country of manufacture	country
description	text
allow gift message	boolean
allow gift wrapping	boolean
price for gift wrapping	amount
is in stock	boolean
enable recurring profile	boolean
meta description	text
meta keywords	text
meta title	string
minimal price	amount
name	string
set product as new from date	date
set product as new to date	date
open amount max value	amount
open amount min value	amount
price	amount
quantity	decimal
short description	text
sku	string
special price from date	date
special price	amount
special price to date	date
tax class	product tax class
visibility	product visibility
websites	website array
weight	decimal

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
Function	Value Types	Description
%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.

January 19, 2021 | View: 1256 | Categories: User Guides, Magento 2