# Formula Editor

Canonical page: https://www.adaptabletools.com/docs/ui-formula-editor

- Two related surfaces for Calculated Column formulas:
  - **Formula Trace** - Excel-style popup anchored to a cell
  - **Compact Expression Editor** - a shortened, moveable Expression Editor
- Used to inspect how a value is derived and to edit the Expression without opening the full Wizard

The Formula Editor is the Calculated Column counterpart to the full [Expression Editor](https://www.adaptabletools.com/docs/ui-expression-editor/index.md).

It has two parts that work together:

- the **Formula Trace** popup - shows the formula for the current cell, with referenced Columns colour-matched to Grid highlights
- the **Compact Expression Editor** - a small, moveable and resizable editor opened from that popup

See [Using Calculated Columns](https://www.adaptabletools.com/docs/handbook-calculated-column-referencing/index.md) for the Wizard, Formula Trace options and a fuller walkthrough

## Formula Trace

Formula Trace is an Excel-style popup anchored to a Calculated Column cell.

Open it by:

- **Double-clicking** the cell
- Selecting **Show Formula** in the cell's [Context Menu](https://www.adaptabletools.com/docs/ui-context-menu/index.md)
- Calling `calculatedColumnApi.showFormulaTrace(columnId, primaryKeyValue)`

The popup shows the Column's [Expression](https://www.adaptabletools.com/docs/adaptable-ql-expression/index.md) with every referenced Column in its own colour. AdapTable highlights the same data in the Grid:

- **Standard** Calculated Columns - referenced **cells** in the row are outlined and tinted
- **Aggregated** (and other multi-row) Calculated Columns - referenced Column **headers** are highlighted

For Standard Calculated Columns the popup also shows each referenced Column's name above its actual cell value for that row, followed by the computed result

## Compact Expression Editor

The Formula Trace popup contains an **Edit** button which opens the Compact Expression Editor.

This is a shortened version of the full Expression Editor: moveable, resizable, and available without opening the Calculated Column Wizard.

It provides:

- the **Functions** dropdown listing available [Expression Functions](https://www.adaptabletools.com/docs/adaptable-ql-expression-functions/index.md)
- live **validation** — the Compact Editor shows `Valid Expression` or the error as you type
- **colour-coded** Column references (matching the Formula Trace highlights)
- **autocomplete**, **hover help**, **Quick Fixes** and **formatting** (`Shift+Alt+F`) - just as in the full [Expression Editor](https://www.adaptabletools.com/docs/ui-expression-editor/index.md#editor-features)

Edits are applied **live** as you type - the Calculated Column re-evaluates immediately.

An invalid Expression will show `#INVALID` in the cells until it is corrected

Validation is the same engine as the full [Expression Editor](https://www.adaptabletools.com/docs/ui-expression-editor/index.md). The difference is that an invalid formula is applied immediately, so the Grid shows `#INVALID` until it is fixed.

The Compact Editor also provides:

- **Revert** - restores the Expression to how it was when the Editor was opened
- **Open Full Editor** - closes the Compact Editor and opens the full Calculated Column Wizard

The Compact Expression Editor is available for all 6 Calculated Column types: `Standard`, `Aggregated`, `Cumulative`, `Quantile`, `Window` and `Observable`

**Example: AdapTableQL Formula Editor**

Formula Trace popup and Compact Expression Editor

- This demo contains a Standard Calculated Column (`Total PRs`) that adds `Open PRs` and `Closed PRs`
- After a short delay it opens Formula Trace for the first `Total PRs` cell

- Wait for the Formula Trace popup, or double-click any `Total PRs` cell
- Note how the referenced cells are highlighted in matching colours
- Click **Edit** in the popup to open the Compact Expression Editor and change the formula - the Column updates live

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Formula Editor',
  initialState: {
    Dashboard: {
      ModuleButtons: ['CalculatedColumn'],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Layout', 'CalculatedColumn'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'open_pr_count',
            'closed_pr_count',
            'total_pr_count',
            'language',
            'github_stars',
            'github_watchers',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
    CalculatedColumn: {
      CalculatedColumns: [
        {
          FriendlyName: 'Total PRs',
          ColumnId: 'total_pr_count',
          Expression: '[open_pr_count] + [closed_pr_count]',
          CalculatedColumnSettings: {
            DataType: 'number',
            Filterable: true,
          },
        },
      ],
    },
  },
};
```

**`src/onAdaptableReady.ts`**

```ts
import {AdaptableReadyInfo} from '@adaptabletools/adaptable';

export const onAdaptableReady = ({adaptableApi}: AdaptableReadyInfo) => {
  setTimeout(() => {
    const firstRowNode = adaptableApi.gridApi.getFirstRowNode();
    if (!firstRowNode) {
      return;
    }
    const primaryKeyValue =
      adaptableApi.gridApi.getPrimaryKeyValueForRowNode(firstRowNode);
    adaptableApi.calculatedColumnApi.showFormulaTrace(
      'total_pr_count',
      primaryKeyValue
    );
  }, 1500);
};
```

- Double-click and the **Show Formula** Context Menu item can each be turned off - see [Configuring Formula Trace](https://www.adaptabletools.com/docs/handbook-calculated-column-tracing-formula/index.md)
- A Calculated Column can also show its formula as a cell tooltip - see [Cell Tooltip](https://www.adaptabletools.com/docs/handbook-calculated-column-tracing-formula/index.md#cell-tooltip)