The editable property on a field definition controls which of its properties a user may change. Fields a user creates themselves are always fully editable.
For the end-user view of this, see Calculations and Fields in Widgets in the User Guide.
Editing Fields Copy Link
Fields are fully editable by default. Use the editable property on a field definition to lock a field down or to restrict which properties the user can change:
const fields: AgFieldDefinition[] = [
{ id: 'country', format: 'textFormat' },
{ id: 'sport', format: 'textFormat', editable: false },
{ id: 'gold', format: 'integerFormat', editable: ['name', 'formatOptions'] },
{ id: 'silver', format: 'integerFormat', editable: ['name'] },
];Pass true (the default) to make every property editable, false to make the field read-only, or an array of AgFieldEditableKey values to allow a subset:
| Key | What the user can edit |
|---|---|
name | The display name shown wherever the field appears. |
description | The description shown in the Field Panel. |
formatOptions | Formatting options for the field's format type (see Formatting). |
These three keys are the full set. editable is available on field definitions, Expressions, and Measures. Fields the user creates in the UI are always fully editable.
formatOptions has no effect on a field with no format, or on a field that uses a custom format you registered yourself. The Field Panel shows format options only for the built-in formats (see Formatting).
In the example below, select any field in the Data Panel to switch the Edit Panel to its field view. Each field is configured differently:
- Country: fully editable (default).
- Sport: read-only (
editable: false). - Gold: name and format options editable (
editable: ['name', 'formatOptions']). - Silver: name only (
editable: ['name']). - Bronze: read-only (
editable: false).
"use client";
import React, {
useCallback,
useMemo,
useRef,
useState,
StrictMode,
} from "react";
import { createRoot } from "react-dom/client";
import { AgStudio, AgStudioRef } from "ag-studio-react";
import {
AgDataEngine,
AgDataSourcesDefinition,
AgFieldDefinition,
AgReportHistory,
AgReportState,
AgStudioApi,
AgStudioApiReadyEvent,
AgStudioMode,
AgStudioProperties,
enableStudioDevValidations,
} from "ag-studio";
if (process.env.NODE_ENV !== "production") {
// Enable extended validations only for development
enableStudioDevValidations();
}
const fields: AgFieldDefinition[] = [
{
id: "country",
format: "textFormat",
},
{
id: "sport",
format: "textFormat",
editable: false,
},
{
id: "gold",
format: "integerFormat",
editable: ["name", "formatOptions"],
},
{
id: "silver",
format: "integerFormat",
editable: ["name"],
},
{
id: "bronze",
format: "integerFormat",
editable: false,
},
];
const StudioExample = () => {
const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
const studioStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);
const [data, setData] = useState<AgDataSourcesDefinition | AgDataEngine>();
const initialState = useMemo<AgReportState | AgReportHistory>(() => {
return {
pages: [
{
id: "a",
widgets: {
"1": {
type: "grid",
dataMapping: {
cols: [
{ id: "medals.country" },
{ id: "medals.sport" },
{ id: "medals.gold", aggregation: "sum" },
{ id: "medals.silver", aggregation: "sum" },
{ id: "medals.bronze", aggregation: "sum" },
],
},
},
},
widgetLayout: {
"1": { xTrack: 0, yTrack: 0, xSpan: 24, ySpan: 16 },
},
},
],
selectedPageId: "a",
panels: {
filters: {
collapsed: true,
},
},
};
}, []);
const onApiReady = useCallback((params: AgStudioApiReadyEvent) => {
fetch("https://www.ag-grid.com/studio/example-assets/olympic-winners.json")
.then((resp) => resp.json())
.then((data: any[]) =>
setData({
sources: [{ id: "medals", name: "Medals", data, fields }],
}),
);
}, []);
return (
<div style={containerStyle}>
<div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
<AgStudio
style={studioStyle}
className="my-studio-container"
data={data}
initialState={initialState}
mode={"edit"}
onApiReady={onApiReady}
/>
</div>
</div>
);
};
const root = createRoot(document.getElementById("root")!);
root.render(
<StrictMode>
<StudioExample />
</StrictMode>,
);
Saved Edits and Locked Properties Copy Link
A user's edits are saved in the report state (see Schema State). If you later remove a property from editable, or set editable: false, a saved edit to that property is ignored and the field shows your value again. The saved edit is not deleted, so it applies again if you make the property editable later.
The saved edit is discarded if the user then saves a change to another property of the same field while the property is locked.
Editing Expressions Copy Link
Only Calculated Columns and Measures the user created themselves have an Expression input. A user can never edit the expression of a Calculated Column or Measure you define, whatever editable is set to. A source column has no expression.
User-Created Expressions Copy Link
A user can edit the name, description, expression and format of a Calculated Column or Measure they created.
The expression syntax is case-insensitive throughout: function names, booleans, and the table and field names in a reference all match regardless of case. The input offers autocomplete for functions and fields, bracket matching, and inline syntax errors. An invalid expression is still saved, but the field produces no values until it parses. A new field with no expression yet also produces no values, so a widget shows it as an empty column.
| Description | Syntax |
|---|---|
| Field references | Medals[Gold], [Total Medals], 'Completed Orders'[Date] |
| Strings | "string" (double quotes only) |
| Numbers | 123, 1.23, 1e3 |
| Booleans | TRUE, FALSE |
| Arithmetic operators | +, -, *, /, ^ |
| Brackets | 3 * (2 + 1) |
| Comparison operators | >, >=, <, <=, =, == (alias for =), <> (not equal) |
| Boolean operators | NOT x, &&, || |
| String concatenation | a & b |
| Function calls | ADD(a, b) |
| Comments | -- Single Line, // Single Line, /* Multi Line */ |
For a list of functions, see Function Expressions.
The Format input should be set to a value that relates the expression. For example, if the expression returns a number, the Format could be set to Integer or Decimal, but not Text. Widgets using fields with such mismatches may fail to display data.
In the example below, the Total Medals Calculated Column is set in initialState.schema, as if the user had created it. Select it in the Data Panel and click Edit to change its expression.
"use client";
import React, {
useCallback,
useMemo,
useRef,
useState,
StrictMode,
} from "react";
import { createRoot } from "react-dom/client";
import { AgStudio, AgStudioRef } from "ag-studio-react";
import {
AgDataEngine,
AgDataSourcesDefinition,
AgFieldDefinition,
AgReportHistory,
AgReportState,
AgStudioApi,
AgStudioApiReadyEvent,
AgStudioMode,
AgStudioProperties,
enableStudioDevValidations,
} from "ag-studio";
if (process.env.NODE_ENV !== "production") {
// Enable extended validations only for development
enableStudioDevValidations();
}
const fields: AgFieldDefinition[] = [
{ id: "country", format: "textFormat" },
{ id: "gold", format: "integerFormat" },
{ id: "silver", format: "integerFormat" },
{ id: "bronze", format: "integerFormat" },
];
const StudioExample = () => {
const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
const studioStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);
const [data, setData] = useState<AgDataSourcesDefinition | AgDataEngine>();
const initialState = useMemo<AgReportState | AgReportHistory>(() => {
return {
pages: [
{
id: "a",
widgets: {
"1": {
type: "grid",
dataMapping: {
cols: [
{ id: "medals.country" },
{ id: "expression-1", aggregation: "sum" },
],
},
},
},
widgetLayout: {
"1": { xTrack: 0, yTrack: 0, xSpan: 24, ySpan: 16 },
},
},
],
selectedPageId: "a",
panels: {
filters: {
collapsed: true,
},
},
schema: {
fields: {
"expression-1": {
name: "Total Medals",
expression: "[medals.gold] + [medals.silver] + [medals.bronze]",
},
},
expressions: [
{
id: "expression-1",
tableId: "medals",
isMeasure: false,
format: "integerFormat",
},
],
},
};
}, []);
const onApiReady = useCallback((params: AgStudioApiReadyEvent) => {
fetch("https://www.ag-grid.com/studio/example-assets/olympic-winners.json")
.then((resp) => resp.json())
.then((data: any[]) =>
setData({
sources: [{ id: "medals", name: "Medals", data, fields }],
}),
);
}, []);
return (
<div style={containerStyle}>
<div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
<AgStudio
style={studioStyle}
className="my-studio-container"
data={data}
initialState={initialState}
mode={"edit"}
onApiReady={onApiReady}
/>
</div>
</div>
);
};
const root = createRoot(document.getElementById("root")!);
root.render(
<StrictMode>
<StudioExample />
</StrictMode>,
);
Developer-Defined Expressions Copy Link
For a Calculated Column or Measure you define, editable controls only the name, description and format options. The user cannot change the expression, and no setting changes this.
The Field Panel shows a string expression read-only. It does not show an expression defined as an AgExpression object. To let users see an expression, define it as a string:
const expressions: AgExpressionFieldDefinition[] = [
// Not shown in the Field Panel
{
id: 'goldAndSilverObject',
name: 'Gold and Silver (Object)',
isMeasure: false,
expression: {
operator: 'add',
inputs: [{ id: 'medals.gold' }, { id: 'medals.silver' }],
},
},
// Shown read-only in the Field Panel
{
id: 'goldAndSilverString',
name: 'Gold and Silver (String)',
isMeasure: false,
expression: '[medals.gold] + [medals.silver]',
},
];A string expression refers to fields by their IDs, as in the Schema State below. Both definitions produce the same values.
In the example below, both Calculated Columns use editable: ['name', 'formatOptions']. Select each one in the Data Panel: only the string expression is shown. Click Edit: the name can be changed, but neither field has an Expression input.
"use client";
import React, {
useCallback,
useMemo,
useRef,
useState,
StrictMode,
} from "react";
import { createRoot } from "react-dom/client";
import { AgStudio, AgStudioRef } from "ag-studio-react";
import {
AgDataEngine,
AgDataSourcesDefinition,
AgExpressionFieldDefinition,
AgFieldDefinition,
AgReportHistory,
AgReportState,
AgStudioApi,
AgStudioApiReadyEvent,
AgStudioMode,
AgStudioProperties,
enableStudioDevValidations,
} from "ag-studio";
if (process.env.NODE_ENV !== "production") {
// Enable extended validations only for development
enableStudioDevValidations();
}
const fields: AgFieldDefinition[] = [
{ id: "country", format: "textFormat" },
{ id: "gold", format: "integerFormat" },
{ id: "silver", format: "integerFormat" },
];
const expressions: AgExpressionFieldDefinition[] = [
{
id: "goldAndSilverString",
name: "Gold and Silver (String)",
isMeasure: false,
format: "integerFormat",
expression: "[medals.gold] + [medals.silver]",
editable: ["name", "formatOptions"],
},
{
id: "goldAndSilverObject",
name: "Gold and Silver (Object)",
isMeasure: false,
format: "integerFormat",
expression: {
operator: "add",
inputs: [{ id: "medals.gold" }, { id: "medals.silver" }],
},
editable: ["name", "formatOptions"],
},
];
const StudioExample = () => {
const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
const studioStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);
const [data, setData] = useState<AgDataSourcesDefinition | AgDataEngine>();
const initialState = useMemo<AgReportState | AgReportHistory>(() => {
return {
pages: [
{
id: "a",
widgets: {
"1": {
type: "grid",
dataMapping: {
cols: [
{ id: "medals.country" },
{ id: "goldAndSilverString", aggregation: "sum" },
{ id: "goldAndSilverObject", aggregation: "sum" },
],
},
},
},
widgetLayout: {
"1": { xTrack: 0, yTrack: 0, xSpan: 24, ySpan: 16 },
},
},
],
selectedPageId: "a",
panels: {
filters: {
collapsed: true,
},
},
};
}, []);
const onApiReady = useCallback((params: AgStudioApiReadyEvent) => {
fetch("https://www.ag-grid.com/studio/example-assets/olympic-winners.json")
.then((resp) => resp.json())
.then((data: any[]) =>
setData({
sources: [{ id: "medals", name: "Medals", data, fields }],
expressions,
}),
);
}, []);
return (
<div style={containerStyle}>
<div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
<AgStudio
style={studioStyle}
className="my-studio-container"
data={data}
initialState={initialState}
mode={"edit"}
onApiReady={onApiReady}
/>
</div>
</div>
);
};
const root = createRoot(document.getElementById("root")!);
root.render(
<StrictMode>
<StudioExample />
</StrictMode>,
);
Users can never edit an expression you define, and the Field Panel does not show an expression defined as an AgExpression object. Define the expression as a string if users need to see it.
Schema State Copy Link
User edits and user-created fields are both persisted in the schema slice of the report state, as an AgSchemaState. Save and restore it with the rest of your report state - see State for the full state model.
const schema = {
fields: {
'medals.gold': {
name: 'Golds'
},
'expression-1': {
name: 'Total Medals',
expression: '[medals.gold] + [medals.silver] + [medals.bronze]',
},
},
expressions: [
{
isMeasure: false,
id: 'expression-1',
tableId: 'medals',
format: 'integerFormat'
}
],
};fields contains per-field overrides for both developer and user created fields. It is keyed by the ID of each field. Each entry may contain:
namedescriptionformat- a format string (only available for built-in formats, see Formatting)expression- only for user created expressions
Serialised expressions encode field references using their ID rather than their name. E.g. Medals[Gold] is serialized as [medals.gold]. The user will always see the former.
expressions declares the fields the user created. Each entry has:
id(required) - a unique ID (auto-generated when created via the UI)tableId(required) - the ID of the data source the field was added to.isMeasure(required) -truefor a Measure,falsefor a Calculated Column.format- the format type, defaulting tointegerFormat.