# Automatic calculations dependencies

## Rationale

Calculated and initial values expressed with formulas can depend on the value of other form controls. In turn, those form controls can be calculated from yet other form controls. Such controls may appear further down in the form, or, in fact, in any place.

It is therefore important to compute calculated and initial values in an order based on the *dependencies* of that value, not just in the order in which the controls appear in the form. This is very similar to what happens in a spreadsheet.

Form Runner supports dependencies of calculated and initial values when the associated formulas refer to other controls via *variables* (such as `$units`, where `units` is the *name* of a control on the form).

## Availability

\[SINCE Orbeon Forms 2018.1]

Orbeon Forms features a user interface option to enable and disable automatic calculations dependencies in the "Form Settings" dialog's "Formulas" tab.:

* Use property: use the `oxf.xforms.analysis.calculate` property
* Always or Never: enable or disable automatic calculation dependencies, no matter how the property is configured.

In addition, for *new form definitions*, the "Automatic Calculations Dependencies" option is enabled by default starting with Orbeon Forms 2018.1.

*NOTE: Existing form definitions which do not have the `xxf:analysis.calculate="true"` attribute set in the form definition source are not automatically upgraded to enable automatic calculations dependencies. You must enable dependencies explicitly in the "Form Settings" dialog.*

![Form Options](https://4129616727-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LEkBiSDvlXs3VWiO0Zu%2Fuploads%2Fgit-blob-253f0794393035ee996e94ab83d1c1e52ad475e8%2Fformulas.png?alt=media)

*NOTE: Prior to Orbeon Forms 2022.1.1, this setting was under the "Form Settings" dialog's "Form Options" tab.*

\[SINCE Orbeon Forms 4.10]

The feature was available for the first time with Orbeon Forms 4.10, but without a user interface. With such older versions of Orbeon Forms, you enable the feature by adding the `xxf:analysis.calculate="true"` attribute on the first model of the form, via "Edit Source".

## Renaming of controls and formulas

\[SINCE Orbeon Forms 2019.1]

See [Renaming of controls and formulas](https://doc.orbeon.com/form-builder/formulas#renaming-of-controls-and-formulas).

## Examples

Consider the following grid, where the Total Total appear on each line item row:

![Grid with calculations](https://4129616727-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LEkBiSDvlXs3VWiO0Zu%2Fuploads%2Fgit-blob-a5c0fe2dcaad984a4ba27a0c01a8b5c53ba11c88%2Fcalculations-dependencies-grid.png?alt=media)

Each Row Total is expressed with the following calculated value formula:

```xpath
$units * $unit-price
```

![Row totals](https://4129616727-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LEkBiSDvlXs3VWiO0Zu%2Fuploads%2Fgit-blob-3b111e7076b72f60fdf9e57ca542733ec62ee85f%2Fcalculations-dependencies-row-total.png?alt=media)

And the Total Units and Total Price are expressed with the following calculated value formula:

```xpath
sum($units)
```

and:

```xpath
sum($row-total)
```

![Total price](https://4129616727-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LEkBiSDvlXs3VWiO0Zu%2Fuploads%2Fgit-blob-66d4d74b928502475b1e48ade5595fdee0350afb%2Fcalculations-dependencies-global-total.png?alt=media)

Automatic calculations dependencies ensure that the totals update correctly as the user modifies the "Units" and "Unit Price" fields. This is the case whether the totals are positioned after or before the fields they depend on in the form.

*NOTE: It is important to note that using variable is key for the dependencies to work. Using other expressions referring to form data, such as `/form/my-section/my-control`, or `//my-control`, will not work for the purpose of dependencies.*

## See also

* Blog post: [Automatic calculation dependencies](https://blog.orbeon.com/2018/10/automatic-calculation-dependencies.html)
* [Formulas](https://doc.orbeon.com/form-builder/formulas)
* [Control settings](https://doc.orbeon.com/form-builder/form-editor/control-settings)