# The [gv_math] Shortcode

In order to use the [gv_math] shortcode, you must have the Math extension installed (available in the All Access license or for purchase separately).

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`

)`filter`

- Used to target a specific field value. Only works with`scope="view"`

or`scope="form"`

. Read more about filters.`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

`id`

- The ID of the form, entry, or View (if`scope`

is defined). Default: undefined`scope`

- 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, 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**

## 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. 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`

)