Scripting

Why Use Scripting?

• Automate repetitive or complex transformations.
• Implement logic that goes beyond built-in Data Tools.
• Generate new calculated columns or metrics programmatically.
• Create and display charts directly from code.
• Prototype and iterate quickly without exporting your data.

JavaScript Scripting

Gridscript runs JavaScript inside a secure sandbox and exposes a simple API to interact with the dataset and the UI. Within your script, the following globals are available:

• gridData – A 2D array representing the current dataset.
• updateGridData(newData) – Updates the grid with modified data.
• addChart(options) – Creates and inserts a chart in the project UI.

Example: Modifying Grid Data

for (let i = 1; i < gridData.length; i++) {
  gridData[i][0] = "Row " + i;
}
updateGridData([...gridData]);

Example: Creating a Chart from Code

The addChart() function allows you to generate charts programmatically by passing a configuration object compatible with the AgCharts React ChartOptions interface. This gives you complete control over chart type, data, axes, titles, and series.

addChart({
  title: { text: "Sales by Region" },
  data: gridData.slice(1).map(row => ({
    region: row[0],
    sales: Number(row[1]),
  })),
  series: [{
    type: "bar",
    xKey: "region",
    yKey: "sales",
  }],
  axes: [
    { type: "category", position: "bottom", title: { text: "Region" } },
    { type: "number", position: "left", title: { text: "Sales ($)" } },
  ],
  legend: { enabled: true },
});

Using AgCharts Options

The addChart() function fully supports the AgCharts configuration model. You can customize everything from color themes to animation settings and event handling by passing a standard ChartOptions object.

➤ For a complete list of available options, refer to the official AgCharts ChartOptions documentation.

Supported Chart Types

addChart() supports all visualization types available in AgCharts, including:

• bar – Compare categorical values.
• line – Visualize trends and progressions.
• area – Show accumulated values over time.
• scatter – Highlight relationships between variables.
• bubble – Add a third variable represented by bubble size.
• pie / donut – Display proportions of a whole.

Python Scripting

Gridscript also supports Python. This allows you to run Python code directly in the browser, using the same grid_data structure. Unlike JavaScript, you don’t need to call updateGridData() — the environment automatically syncs your changes.

Example: Multiply the Second Column by 2

for row in grid_data:
    row[1] = float(row[1]) * 2

Python scripting is perfect for users familiar with data science workflows, offering an intuitive way to manipulate datasets using Pythonic syntax.

Error Handling

If your script throws an error, Gridscript will display a descriptive message in the editor panel. Errors don’t modify your grid, ensuring your data stays safe while you debug.

Saving & Reusing Scripts

Scripts are stored as part of your Project. You can re-run them, modify them inline, or export them together with your data in a.gspj file.