Basic usage

Calculated fields adds a new setting “Formula” to the the ACF field editor. Formulas supports referring to other fields in the same Field group using the field name. If a formula is added to a sub field inside a repeater or group field, the name refers to another sub field in the same repeater or subgroup.

A sub field inside a repeater field can also refer to a parent field using the “parent.”” prefix.

A formula can contain the basic mathematical operations: plus (+), minus (-), multiply (*), division (/) and power of (^). Formulas can also contains functions like sin, cos, arcsin, log, ln, sqrt, abs. Parentheses are supported.

If an expression can’t be evaluated due to invalid syntax or referring to undefined field names, it will silently return zero.

Examples of valid expressions (note, no equal sign at the beginning):

• fieldA * 2
• fieldA * fieldB
• abs(fieldA) * (2 + sqrt(fieldB))
• amount * parent.price

CONDITIONAL OPERATORS #

An expression can also contain a conditional expression that will return either 0 or 1. The supported operators are:

• Equals (==) – Returns 1 when two values are equal, 0 otherwise
• Not equals (!=) – Returns 1 when two values are not equal, 0 otherwise
• Greater than (>) – Returns 1 when the first operand is greater than the second, 0 otherwise
• Greater than or equal (>=) – Returns 1 when the first operand is greater than or equal to the second, 0 otherwise
• Less than (<) – Returns 1 when the first operand is less than the second, 0 otherwise
• Less than or equal (<=) – Returns 1 when the first operand is less than or equal to the second, 0 otherwise

Examples of valid expressions using conditional operators:

• 10 == 10 (returns 1)
• 10 == 2 (returns 0)
• 10 > 2 (returns 1)
• 10 < 2 (returns 0)
• 10 <= 10 (returns 1)

ROUNDING FUNCTIONS #

Round a decimal value to the nearest integer. Supported functions are:

• round() – Uses standard mathematical rounding rules to round to nearest integer
• ceil() – Rounds the value to the next higher integer
• floor() – Rounds the value to the next lower integer

Examples of valid expressions using rounding functions:

• round(10.2) (returns 10)
• round(10.9) (returns 11)
• round(10.888888 * 10) / 10 (returns 10.9)
• ceil(10.2) (returns 11)
• floor(10.2) (returns 10)

Note that the round() function only takes one parameter and always round to an integer. If you need to round to a higher precision, multiply and divide as shown in third example above.

GROUP FIELDS (NEW FROM 1.2.4) #

Fields defined as part of a group, subfields, can be addressed using the group name as a prefix. Inside the group, a field defined on the parent level can be addressed using the “parent” prefix. See examples below:

Valid formula to use the value of field “foobar” defined inside the group “group2”:
* group2.foobar + 10

Valid formula in a field inside a group (assuming the parent has a field named count):
* parent.count * 22

ARRAY FUNCTIONS FOR REPEATER FIELDS #

If repeater fields are used, a calculated field in the parent field group can summarize a specific repeater sub fields using the aggregation functions sum, count, average, min or max. For example, the expression: “Sum(orderlines.amount)”” will return the sum of all the “amount” fields in the repeater field “orderlines”.

The available array functions are:

• sum()
• average()
• count()
• min()
• max()

Note that anything after the dot (.) in the aggregate expression is an expression in itself. It’s perfectly OK to write a formula like: “Sum(orderlines.price * amount)”. This expression will walk over all lines in the “orderlines” repeater field, perform the calculation “price * amount” and return the sum of all lines.

Note that when working with aggregate functions, parentheses can not be used. If you need to aggregate a more complex calculation, you should add an extra field in the repeater group and let the aggregate function work on this extra field.

DATA TYPE AND CALCULATION ORDER #

Calculated fields works with the assumption that all fields are defined as numeric in the ACF editor. Using a text field in a formula WILL PRODUCE UNPREDICTABLE RESULTS.

Calculations are made as the custom field is stored to the database. To minimize the impact of performance, Calculated fields rely on field order. A formula field can only refer to fields ordered BEFORE itself. A formula field that refers to a field ordered after it WILL PRODUCE UNPREDICTABLE RESULTS.