JavaScript Embedded AnalyticsEditable Fields

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:

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 {
  AgFieldDefinition,
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  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 initialState: 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 studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
};

let studioApi: AgStudioApi;

const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
fetch("https://www.ag-grid.com/studio/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data) =>
    studioApi!.setProperty("data", {
      sources: [{ id: "medals", name: "Medals", data, fields }],
    }),
  );

<div style="display: flex; flex-direction: column; height: 100%">
    <div id="myStudio" class="my-studio-container"></div>
</div>

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.

For a list of functions, see Function Expressions.

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:

• name
• description
• format - a format string (only available for built-in formats, see Formatting)
• expression - only for user created expressions

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) - true for a Measure, false for a Calculated Column.
• format - the format type, defaulting to integerFormat.