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 Using Data 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 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). |
editable is available on field definitions, expression fields, and Measures. Note fields the user creates in the UI are always fully editable.
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).
import {
createApp,
defineComponent,
onBeforeMount,
ref,
shallowRef,
} from "vue";
import { AgStudio } from "ag-studio-vue3";
import {
AgDataEngine,
AgDataSourcesDefinition,
AgFieldDefinition,
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 VueExample = defineComponent({
template: `
<div style="height: 100%">
<div style="display: flex; flex-direction: column; height: 100%">
<ag-studio
style="width: 100%; height: 100%;"
class="my-studio-container"
@api-ready="onApiReady"
:initialState="initialState"
:mode="mode"
:data="data"></ag-studio>
</div>
</div>
`,
components: {
"ag-studio": AgStudio,
},
setup(props) {
const studioApi = shallowRef<AgStudioApi | null>(null);
const initialState = ref<AgReportState>({
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 mode = ref<AgStudioMode>("edit");
const data = ref<AgDataSourcesDefinition | AgDataEngine>(null);
const onApiReady = (params: AgStudioApiReadyEvent) => {
studioApi.value = params.api;
const toStudioData = (data) => ({
sources: [{ id: "medals", name: "Medals", data, fields }],
});
fetch("https://www.ag-grid.com/studio/archive/3.0.0/example-assets/olympic-winners.json")
.then((resp) => resp.json())
.then((respData) => (data.value = toStudioData(respData)));
};
return {
studioApi,
initialState,
mode,
data,
onApiReady,
};
},
});
const app = createApp(VueExample);
app.mount("#app");
Editing Expressions Copy Link
The Expression input is only shown for Calculated Columns and Measures the user created themselves. 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.
| 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.
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.