Calculation Field & Cross-Post Aggregation

Prefer video? Watch the Field Forge tutorials 8 short guides covering every feature Watch

Overview

The calculation field type (PRO) is a read-only numeric field whose value is computed either from a formula referencing sibling top-level fields, or by summing a numeric sub-field across all rows of a sibling repeater. The value is recomputed on every read via the fieldforge/load_value filter and is also stored into wp_fieldforge_values on save_post (priority 20), so plain SQL queries, REST responses, and GraphQL can return the pre-computed number without additional processing.

Cross-post aggregation (summing a field across all posts of a given type) is split by tier: the shortcode and PHP helper are free; the REST endpoint and GraphQL query are PRO.

—

Field Definition Keys

Register or retrieve a calculation field using the standard field-group array. Keys specific to the calculation type:

Key	Type	Values / Default	Description
`type`	string	`'calculation'`	Field type identifier
`formula`	string	`''`	Math expression with `{field_name}` tokens. Used when `sum_source` is `'self'`.
`sum_source`	string	`'self'`	`'repeater'`	`'self'` evaluates the formula; `'repeater'` sums a sub-field across rows.
`sum_repeater`	string	`''`	Name of the sibling repeater field. Required when `sum_source = 'repeater'`.
`sum_field`	string	`''`	Name of the numeric sub-field to sum. Stored in `wp_fieldforge_values` as `::`.
`output_format`	string	`'number'`	`'number'`	`'currency'`	`'percentage'`
`decimal_places`	int	`2`	Number of decimal places in the formatted output.
`currency_symbol`	string	`'$'`	Symbol string for `output_format = 'currency'`.
`symbol_position`	string	`'prefix'`	`'prefix'` (symbol before value) or `'suffix'` (symbol after value).
`thousands_sep`	string	`','`	Character used to separate thousands in the formatted number.
`decimal_sep`	string	`'.'`	Character used as the decimal point in the formatted number.

Example: formula-based field definition

fieldforge_add_local_field_group( [
    'key'    => 'group_order',
    'title'  => 'Order',
    'fields' => [
        [ 'key' => 'field_price', 'label' => 'Unit Price', 'name' => 'price', 'type' => 'number' ],
        [ 'key' => 'field_qty',   'label' => 'Quantity',   'name' => 'qty',   'type' => 'number' ],
        [
            'key'            => 'field_total',
            'label'          => 'Total',
            'name'           => 'order_total',
            'type'           => 'calculation',
            'sum_source'     => 'self',
            'formula'        => '{price} * {qty}',
            'output_format'  => 'currency',
            'decimal_places' => 2,
            'currency_symbol' => '$',
            'symbol_position' => 'prefix',
            'thousands_sep'  => ',',
            'decimal_sep'    => '.',
        ],
    ],
    'location' => [ [ [ 'param' => 'post_type', 'operator' => '==', 'value' => 'order' ] ] ],
] );

Example: repeater line-item total

[
    'key'          => 'field_grand_total',
    'label'        => 'Grand Total',
    'name'         => 'grand_total',
    'type'         => 'calculation',
    'sum_source'   => 'repeater',
    'sum_repeater' => 'line_items',      // sibling repeater name
    'sum_field'    => 'row_total',       // numeric sub-field name
    'output_format' => 'currency',
    'currency_symbol' => '$',
    'decimal_places'  => 2,
],

—

Reading a Calculation Field Value

get_field() returns the raw numeric value (a float/int) — never the formatted string.

$total = get_field( 'order_total', $post_id );
// Returns: 149.97 (float)

// Display formatted:
echo esc_html( get_field( 'order_total', $post_id ) ); // "149.97"

To apply the output formatting defined in the field settings, use:

$total    = get_field( 'order_total', $post_id );           // raw float
$settings = get_field_object( 'order_total', $post_id );    // field definition array
$formatted = fieldforge_format_calc_value( $total, $settings );
// Returns: '$149.97'
echo esc_html( $formatted );

fieldforge_format_calc_value( $value, $settings )

Parameter	Type	Description
`$value`	`float`	int	null	Raw numeric value returned by `get_field()`.
`$settings`	`array`	Field definition array (from `get_field_object()` or your own array with the keys listed above).

Returns string. If $value is null or non-numeric, returns '0' (or formatted '$0.00' etc.).

Security note: Field Forge never executes formula strings with eval() or any PHP dynamic evaluation. The shunting-yard parser accepts only digits, decimal points, and the operators + - * / ( ). Any other character causes the formula result to be 0. The posted raw total from the metabox hidden input is also never trusted — the server recomputes and overwrites on save.

—

PHP Aggregation Helper (Free)

fieldforge_aggregate_field(
    string $field,
    string $post_type = 'post',
    string $status    = 'publish',
    string $op        = 'sum'
) : float|int

Reads wp_fieldforge_values directly and returns an aggregate. A parent_id = 0 guard on the query prevents repeater sub-field rows from being counted more than once.

Parameter	Values	Description
`$field`	field name string	The field `name` (slug), not the key.
`$post_type`	any post type slug	Default: `'post'`.
`$status`	`'publish'`, `'any'`, etc.	Default: `'publish'`.
`$op`	`'sum'`	`'avg'`	`'min'`	`'max'`	`'count'`	Aggregation operation.

// Total donations across all published campaign posts
$total = fieldforge_aggregate_field( 'donation', 'campaign', 'publish', 'sum' );
echo '$' . number_format( $total, 2 );

// Average product rating
$avg = fieldforge_aggregate_field( 'star_rating', 'product', 'publish', 'avg' );

// Number of entries
$count = fieldforge_aggregate_field( 'donation', 'campaign', 'publish', 'count' );

—

Shortcode (Free)

Place in any post, page, or widget area.

Attributes:

Attribute	Required	Default	Description
`field`	Yes	—	Field name to aggregate.
`post_type`	No	`'post'`	Post type slug.
`status`	No	`'publish'`	Post status filter.
`op`	No	`'sum'`	`sum`	`avg`	`min`	`max`	`count`
`format`	No	`'number'`	`'number'`	`'currency'`	`'percentage'`
`symbol`	No	`'$'`	Currency or percentage symbol.
`decimals`	No	`'2'`	Number of decimal places.

Examples:

0.00

—

REST `/aggregate` Endpoint (PRO)

Requires: rest_api_fields Pro capability. Default permission: editor-tier read (WP capability edit_posts). Request:

GET /wp-json/fieldforge/v1/aggregate?field=donation&post_type=campaign&op=sum&format=currency&symbol=$&decimals=2

Query parameter	Required	Description
`field`	Yes	Field name. Missing → `400`.
`post_type`	No	Default `'post'`.
`status`	No	Default `'publish'`.
`op`	No	`sum`	`avg`	`min`	`max`	`count`. Default `'sum'`.
`format`	No	`'number'`	`'currency'`	`'percentage'`. Default `'number'`.
`decimals`	No	Default `2`.
`symbol`	No	Default `'$'`.

Response (200):

{
  "field":     "donation",
  "post_type": "campaign",
  "status":    "publish",
  "op":        "sum",
  "value":     4250.00,
  "formatted": "$4,250.00"
}

Error responses: 400 — missing field parameter ('A field name is required.'). 401 — unauthenticated request (default; login required). 403 — authenticated but insufficient capability. Permission filter:

// Allow subscribers to read the aggregate endpoint (example)
add_filter( 'fieldforge/rest/aggregate_permission', function( $cap ) {
    return 'read'; // WP capability string
} );

The filter receives the current required capability string and must return a capability string.

—

GraphQL `fieldForgeAggregate` (PRO)

Requires: graphql Pro capability and WPGraphQL active. Query:

query GetDonationTotal {
  fieldForgeAggregate(
    fieldName: "donation"
    postType:  "campaign"
    status:    "publish"
  ) {
    fieldName
    postType
    sum
    avg
    min
    max
    count
  }
}

Response:

{
  "data": {
    "fieldForgeAggregate": {
      "fieldName": "donation",
      "postType":  "campaign",
      "sum":   4250.00,
      "avg":   354.17,
      "min":   10.00,
      "max":   1000.00,
      "count": 12
    }
  }
}

All five aggregate values (sum, avg, min, max, count) are always returned in a single query — select only the fields you need.

—

50. Calculation Field & Cross-Post Aggregation