The [gv_math] Shortcode
In order to use the [gv_math] shortcode, you must have the Math extension installed (only available in the All Access license).
The [gv_math]
shortcode enables advanced math calculations and integrates with values populated by Gravity Forms and GravityView.
Available shortcode parameters
decimals
- The number of decimals to display. If undefined, displays the number of decimals returned by the math result.format
- Whether or not to format the number. If set toraw
- Display the number, unformatted. Otherwise, format the number using WordPress' number_format_i18n() function.formula
- Instead of defining the formula inside the shortcode you can define it using theformula
parameter. More details belowdebug
- Show or hide error messages. Passtrue
or1
to enable. (Default:false
)filter
- Used to target a specific field value. Only works withscope="view"
orscope="form"
. Read more about filters.default_value
- If a value is not valid use the default value. Passtrue
or1
to enable, orskip
to skip the invalid value. (Default:skip
)notices
- Display notices to end users if there are warnings or errors associated with the formula. Passtrue
or1
to enable. (Default:false
)gravityview/math/accuracy_message
shortcode available to override defaultwarning
notice. (Default:* Results may not be accurate.
)gravityview/math/no_results_message
shortcode available to override defaultError
notice. (Default:** No Results Currently Available.
)gravityview/math/admin_notice
shortcode available to override default Admin notice. (Default:You can only see this message because you are logged in and have permissions.
)
Parameters available when using Gravity Forms Merge Tags
id
- The ID of the form, entry, or View (ifscope
is defined). Default: undefinedscope
- If not defined, the shortcode performs pure math.(undefined)
- Pure math calculations (default)form
- Use the sum of all the form values for the specified form ID. Requires an ID parameter.entry
- Use the values of a single entry. Requires the ID parameter if used outside a Custom Content field, otherwise, not needed.visible
- Use the values of only visible entries for the current GravityView View. Must be used inside a Custom Content widget on a View. It doesn't work with DataTables.view
- Use the values of all valid entries for the specified View ID. Requires an ID parameter.
Math functions and constants are available in all scopes.
Using shortcode parameters
The decimals
parameter (Options: from 0
to 16
)
Specify the number of decimals you want to display.
[gv_math formula="PI" decimals="16" /]
=3.1415926535897931
[gv_math formula="PI" decimals="2" /]
=3.14
[gv_math formula="PI" decimals="0" /]
=3
Leave blank to use the number of decimals output by the equation.
[gv_math formula="5/2" /]
=2.5
[gv_math formula="5/2" decimals="2" /]
=2.50
There's a limit of 16 decimal places.
The format
parameter (Option: raw
)
[gv_math formula="PI * 1000000" /]
=3,141,592.6536
(number-formatted)[gv_math formula="PI * 1000000" format="raw" /]
=3141592.6536
(no thousands separators)
The formula
parameter
Note: if content is also being passed inside
[gv_math]
shortcode tags, theformula
parameter will be ignored.
You can define the mathematical formula using the formula
parameter instead of inside the [gv_math][/gv_math]
shortcode tags. Instead of [gv_math] {formula} [/gv_math]
, you can use [gv_math formula="{formula}" /]
).
Example:
[gv_math formula="10 * 10" /]
is the same as:
[gv_math] 10 * 10 [/gv_math]
Pure Math Calculation:
Pure math calculations don't require GravityView or Gravity Forms.
You can perform pure calculations. Anything inside the shortcode (or defined using the formula
shortcode parameter) is processed as a mathematical equation and is calculated. There should be no other text in the formula, just math!
Basic math example:
[gv_math] 2 * 300 [/gv_math]
Will return: 600
Example using the PI
constant and avg()
function:
You can use constants and formula together:
[gv_math] PI / avg(7, 8, 9) [/gv_math]
Will return: 75.398223686
Example showing the use of the decimals
parameter:
[gv_math decimals="2" formula="PI" /]
Will return: 3.14
Another example showing the use of the decimals
parameter:
[gv_math decimals="0"] PI [/gv_math]
Will return: 3
(mathematicians, please don't get mad)
[gv_math formula="pow( 5, 2 )" /]
Will return: 25
because the function is asking for 5^2
. See the Math Functions section for more other mathematical formulas available.
Calculations for a single Gravity Forms Entry
For this example, Entry #123 has a field named "Number" with a value of 40, and a field named "OtherNumber" with a value of 100
Display the value of a single numeric field:
[gv_math scope="entry" id="123"]{Number:5}[/gv_math]
Will return: 40
Perform math functions:
[gv_math scope="entry" id="123"] avg( 0, {Number:5} ) [/gv_math]
Will return: 20
because it is the average of 0
and 40
Use multiple field values: [gv_math scope="entry" id="123"] sum( 1, 5, 10, 20, {Number:5}, {OtherNumber:6} ) [/gv_math]
Will return: 176
because it is the sum of 1 + 5 + 10 + 20 + 40 + 100
.
Field calculations
There were [gv_math scope="entry" id="123" formula="{Number:5} + {OtherNumber:6}" /] Canada geese on the grass.
Will return: There were 140 Canada geese on the grass.
When using in a GravityView Custom Content field
If you want to perform calculations using the current entry, use scope="entry"
without defining the id
parameter. This works for the Custom Content Field, not Custom Content Widget.
Form scope: calculations based on all entries in a Gravity Forms form
Format: [gv_math scope="form" id="{form id}"]
When working in the "Form" scope, the results are all based on the field values for all form entries that are not in the trash.
There are also special modifiers you can use to the Gravity Forms merge tags to fetch different values:
:sum
The sum of all field values for the form (this is also the default behavior for theform
scope):max
The highest field value:min
The lowest field value:avg
The average of all field values:count
The number of entries processed
For the examples below, the form has 102 entries, with the Number field having values from -50 to +51
Get the sum of field values
The default behavior is to output a sum, so if you define :sum
in the merge tag, it will return the same result as if you didn't. {Number:5}
is the same as {Number:5:sum}
.
[gv_math scope="form" id="9"]{Number:5}[/gv_math]
Will return: 51
because the sum of all numbers between -50
and 50
is 51
.
Get the number of form entries
[gv_math scope="form" id="9"]{Number:5:count}[/gv_math]
Will return: 102
because there are 102 entries in the form and none are in the trash.
Get the average of field values
[gv_math scope="form" id="9"]{Number:5:avg}[/gv_math]
Will return: 0.5
because the average of all numbers between -50
and 50
is 0.5
.
Get the highest field value
[gv_math scope="form" id="9"]{Number:5:max}[/gv_math]
Will return: 51
because the highest value for a Number field in our example form is 51
.
Get the lowest field value
[gv_math scope="form" id="9"]{Number:5:min}[/gv_math]
Will return: -50
because the lowest value for a Number field in our example form is -50
.
Scope: Visible
Use scope="visible"
to use the visible entries as the value source. This works within a GravityView Custom Content Field or Custom Content Widget, as well as when placed on the same page as a [gravityview]
shortcode.
The results will be modified based on the entries displayed in the View, so this:
### Sales summary: * Total number of sales: [gv_math scope="visible" formula="{Sales:12:count}" format="raw" /] * Total revenue: $[gv_math scope="visible" formula="{Product:3} + {Another Product:4}" decimals="2" /] * Cost of goods sold: $[gv_math scope="visible" formula="{Commission:3} + {CPC:4}" decimals="2" /] * Profit: $[gv_math scope="visible" decimals="2"] ( {Product:3} + {Another Product:4} ) - ( {Commission:3} + {CPC:4} ) [/gv_math] [gravityview]
will become this:
### Sales summary: * Total number of sales: 1300 * Total revenue: $39,430 * Cost of goods sold: $8,173 * Profit: $31,257 [gravityview]
Note: The scope="visible"
functionality will not work with the GravityView DataTables Extension
Filters
The "view"
and "form"
scoped shortcodes support an additional filter
parameter. This will filter the entries in the scope by some specified values.
The parameter contents should be URL-encoded, and resemble the URL parameters that Gravity View uses for its Search Widget. The following attributes are supported:
filter_N
- the filter, where N is the ID of the field or entry attribute to filter by or a meta key
op_N
- the operation for a corresponding filter_N
, default: is
limit
- the number of entries, default is 0, process all the entries
Example: [gv_math scope="view" id="12" filter="filter_1=hello&op_1=isnot&limit=3"]
Filtering on the view scope will further limit the current view filters (including searches, etc. but excluding pagination).
Filtering on the form scope will override everything.
The filtering relationship between the added filter is an AND one. The sorting is done by ID for forms, by configured sort field/direction for views.
Some examples
Get the total salaries for all personnel in accounting:
[gv_math scope="form" id="12" filter="filter_4=Accounting"]{Salary:5:sum}[/gv_math]
Count the number of entries that voted "Yes" and the age is over 40:
[gv_math scope="form" id="12" filter="filter_15=Yes&op_15=is&filter_2=40&op_2=gt"]{Vote:15:count}[/gv_math]
Notes on shortcode use
- Decimals require a leading number:
50 + .5
is invalid because the decimal doesn't have a number in front of it. Use50 + 0.5
instead. - If using a Gravity Forms merge tag for a price, make sure the add
:price
to the end of the merge tag. This will convert the currency format (with currency symbol like $) to a number format:- Total fields:
{Total:32}
becomes{Total:32:price}
- Product fields:
{Product Name (Price):28.2}
becomes{Product Name (Price):28:price}
- note that you need to remove the.2
from the end of the field number (28.2
to28
, for example)
- Total fields:
- Nest away! You can nest parenthesis to your heart's delight. An equation like
( 1 + 2 ) + ( 3 / ( 4 * ( 5 + 6 ) ) )
will work just fine. - Extra spacing is not a problem - you can use extra spacing in the formula inside the
[gv_math]
tags; line breaks inside theformula
parameter aren't allowed. Example of extra spacing that still works:[gv_math] avg( ( 100 / 3747 ), ( 48672 * 2746 ) ) [/gv_math]
Mathematical precision
The precision of the math functions is not exact for numbers with many decimal digits. The math library uses PHP's
float
definition, which is has a precision of roughly 14 decimal places learn more about floats. Because of this issue of precision, if thedecimal
parameter is not defined, the shortcode automatically limits precision to 16 decimal places. This16
limit can be overridden using thegravityview/math/precision
filter.
// Turn off the limit altogether add_filter( 'gravityview/math/precision', '__return_false' ); // Or you can modify the precision limit (here, to 14) add_filter( 'gravityview/math/precision', function() { return 14; } );
Math Functions
You can use the following mathematical functions:
abs()
- Returns the absolute value of a number Learn moreacos()
- Returns the arccosine (in radians) of a number Learn moreasin()
- Returns the arcsine (in radians) of a number Learn moreatan()
- Returns the arctangent (in radians) of a number Learn moreavg( num1, num2, etc )
- Returns the mean of all the items passed to the function. Example:avg( 3, 9, 27 )
returns13
( The sum of the numbers,39
, divided by the item count3
)ceil()
- Returns the smallest integer greater than or equal to a given number. Learn more Example:ceil( 10.284742 )
returns11
cos()
- Returns the cosine of a number Learn morecount()
- Returns the number of items passed to the function Learn more Example:count( 1, 2, 3, 4 )
returns4
deg2rad()
- Returns the number of radians converted from the number in degrees Learn moreexp()
- Returns ex, where x is the argument, and e is Euler's constant, the base of the natural logarithms. Learn morefloor()
- Returns the largest integer less than or equal to a given number Learn morelog( number, e )
- Returns the natural logarithm (base e) of a number Learn moremax( num1, num2, etc )
- Returns the largest of zero or more numbers Learn moremin( num1, num2, etc )
- Returns the smallest of zero or more numbers Learn morepow( base, exponent )
- Returns the base to the exponent power, that is, baseexponent Learn morerad2deg()
- Returns the number of degrees converted from a radian number Learn moreround( number, precision )
- Returns the rounded value of val to specified precision (number of digits after the decimal point). precision can also be negative or zero (default) Learn moresin()
- Returns the sine of a number Learn moresqrt()
- Returns the square root of a number Learn moresum( num1, num2, etc )
- Returns the total resulting from the addition of the items passed to the function
Any function can have math inside of it.
Function examples:
Function: floor()
In this example, a Gravity Forms merge tag is used. This is optional. For this example,
{Number:5}
equals51
[gv_math scope="form" id="9" decimals="0"]floor( {Number:5} + 0.6 )[/gv_math]
Returns: 51
- the function is performing calculations on floor( 51.6 )
, so the next lowest integer to 51.6
is 51
.
[gv_math]floor( 51 + 0.6 )[/gv_math]
Returns: 51
- the function is performing calculations on floor( 51.6 )
, so the next lowest integer to 51.6
is 51
.
[gv_math decimals="4"] 51 + 0.6 [/gv_math]
Will return 51.6000
because the [gv_math]
shortcode has defined a decimals
parameter with a value of 2
, so that # of decimals is used to output the value. If the decimals
parameter had not been set, the value would have been 51.6
.
Function: ceil()
[gv_math] ceil( ( 51 * 2 ) + ( 15 / 2 ) ) [/gv_math]
Will return: 110
because the formula inside the function (( 51 * 2 ) + ( 15 / 2 )
) equals 109.5
. That value is then passed to the ceil()
function, which finds the next highest integer. The next highest integer is 110
.
Function: round()
[gv_math] round( 42.8 ) [/gv_math]
Will return 43
because .8
rounds up.
[gv_math] round( 120.1234, 2 ) [/gv_math]
Will return 120.12
because .1234
rounds down, and the "precision" was set to 2
(two decimal places).
Rounding precision
The "precision" value can be negative. When negative, the number is rounded to the number of digits to the left of the decimal:
- [and so on]
3
- Nearest.001
(thousandth)2
- Nearest.01
(hundredth)1
- Nearest.1
(tenth)0
or-1
- Nearest integer-2
- Nearest 10-3
- Nearest 100-3
- Nearest 1,000 (thousand)-4
- Nearest 10,000 (ten-thousand)- [and so on]
Precision example:
[gv_math] round( 120199, -3 ) [/gv_math]
Will return 120,000
because the "precision" is set to -3
, which rounds to the nearest thousand. 120199
rounds down to the nearest thousand, 120000
, then the output is formatted as 120,000
. To return the raw value (120000
), use [gv_math format="raw"]
instead.
Math Constants
The number values represented below are defined by PHP. We know the numbers below aren't all limited to 13 decimal places.
PI
- π constant (Defaults to 13 decimal places:3.1415926535898
)PI_2
- π constant / 2 (1.5707963267949
)PI_4
- π constant / 4 (0.78539816339745
)E
- e constant (2.718281828459
)SQRT_PI
- Square root of π (0.63661977236758
)SQRT_2
- Square root of 2 (1.4142135623731
)SQRT_3
- Square root of 3 (1.7320508075689
)LN_PI
- The natural logarithm of π (1.1447298858494
)