Using Math by GravityView: the [gv_math] Shortcode

[gv_math] shortcode

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 to raw - 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 the formula parameter. More details below
• debug - Show or hide error messages. Pass true or 1 to enable. (Default: false)
• default_value - If a value is not valid use the default value. Pass true or 1 to enable, or skip to skip the invalid value. (Default: skip)
• notices - Display notices to end users if there are warnings or errors associated with the formula. Pass true or 1 to enable. (Default: false)
  • gravityview/math/accuracy_message shortcode available to override default warning notice. (Default: * Results may not be accurate.)
  • gravityview/math/no_results_message shortcode available to override default Error 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

• scope - If not defined, the shortcode performs pure math.
  • (undefined) - Pure math calculations (default)
  • form - Use the sum of all the form values
  • entry - Use the values of a single entry
  • visible - Use the values of only visible entries for the current GravityView View
  • View - Use the values of all valid entries for the current GravityView View (not currently functional)
• id - The ID of the form, entry, or View (if scope is defined). Default: undefined

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, the formula 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 the form 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

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. Use 50 + 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 to 28, for example)
• 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 the formula 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 the decimal parameter is not defined, the shortcode automatically limits precision to 16 decimal places. This 16 limit can be overridden using the gravityview/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 more
• acos() - Returns the arccosine (in radians) of a number Learn more
• asin() - Returns the arcsine (in radians) of a number Learn more
• atan() - Returns the arctangent (in radians) of a number Learn more
• avg( num1, num2, etc ) - Returns the mean of all the items passed to the function. Example: avg( 3, 9, 27 ) returns 13 ( The sum of the numbers, 39, divided by the item count 3)
• ceil() - Returns the smallest integer greater than or equal to a given number. Learn more Example: ceil( 10.284742 ) returns 11
• cos() - Returns the cosine of a number Learn more
• count() - Returns the number of items passed to the function Learn more Example: count( 1, 2, 3, 4 ) returns 4
• deg2rad() - Returns the number of radians converted from the number in degrees Learn more
• exp() - Returns e^x, where x is the argument, and e is Euler's constant, the base of the natural logarithms. Learn more
• floor() - Returns the largest integer less than or equal to a given number Learn more
• log( number, e ) - Returns the natural logarithm (base e) of a number Learn more
• max( num1, num2, etc ) - Returns the largest of zero or more numbers Learn more
• min( num1, num2, etc ) - Returns the smallest of zero or more numbers Learn more
• pow( base, exponent ) - Returns the base to the exponent power, that is, base^exponent Learn more
• rad2deg() - Returns the number of degrees converted from a radian number Learn more
• round( 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 more
• sin() - Returns the sine of a number Learn more
• sqrt() - Returns the square root of a number Learn more
• sum( 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} equals 51

[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)