DataGrid

A feature‑rich data grid powered by AG Grid Community. It can display structured data from static JSON or dynamic data sources such as database tables or REST APIs. The grid supports virtual scrolling, column resizing and filtering, CSV export, inline editing, CRUD actions, and custom JavaScript handlers for row clicks.

Use Cases

• Display database records with pagination, sorting, and search
• Build editable data grids with inline cell editing
• Create CRUD interfaces with Add/Edit/Delete buttons
• Show API response data as a sortable, searchable table
• Create master‑detail views with row click navigation
• Display static reference data (e.g., pricing tiers, feature comparisons)
• Build interactive data tables with custom JavaScript actions on row clicks (navigation, alerts, data source operations)

Properties

dataSource

Data source configuration – determines where table data comes from (static JSON or dynamic data source). Type: object.

type

Source type – 'static' for hardcoded JSON data, 'datasource' for database tables or REST APIs. Type: string. Options: static, datasource. Default: static. VisualImpact: Static sources show hardcoded data. Datasource loads records dynamically at runtime from configured source. Recommendations: demo-data – Use 'static' for placeholder data during page design; dynamic-data – Use 'datasource' for real database tables or API endpoints; master-detail – Use 'datasource' when building record browsing/editing interfaces.

staticData

JSON string containing array of records (only used when type='static'). Must be valid JSON array. Type: string. VisualImpact: Invalid JSON will result in empty table. Sanitization: Must be valid JSON. Invalid JSON will result in empty table.

dataSourceId

ID of the configured data source (only used when type='datasource'). References a data source created in the system. Type: string.

dataSourceType

Type of data source (only used when type='datasource'). 'table' for database tables, 'api' for REST API endpoints. Type: string. Options: table, api.

pageSize

Number of records to load from data source (only used when type='datasource'). Type: number. Default: 100. Recommendations: small-datasets – 50‑100 records for tables with few fields; large-datasets – 25‑50 records for tables with many fields or slow APIs; performance – Lower page size improves load time but may require pagination.

detectedColumns

Auto‑detected columns from data source (populated automatically by system when data source is selected). Used to auto‑fill columns configuration. Type: array of objects.

• key – Field name from data source. Type: string.
• label – Human‑readable column header (auto‑generated from field name). Type: string.

columns

Column definitions specifying which fields to display and how to label them. Type: array. Required: true. Min items: 1. Max items: 20. Recommendations: auto-detect – Let system auto‑populate columns from data source for faster setup; column-count – 4‑8 columns for desktop, 3‑5 for mobile‑first designs; column-order – Place identifying fields (name, title) first, IDs last; width-usage – Set width for ID/date columns (e.g., '80px'), leave text columns auto‑width.

• key – Field name from the data source (must match property name in data records). Type: string. Required: true.
• label – Column header text displayed in table header. Type: string. Required: true.
• width – CSS width value for column (optional, default: auto‑width based on content). Type: string. Optional.

striped

Alternating row background colors for improved readability. Type: boolean. Default: true. VisualImpact: True – Odd rows light gray (#f9fafb), even rows white. False – All rows white. Recommendations: readability – Use true for tables with 5+ rows; minimal-design – Use false for clean, minimal aesthetic.

hover

Highlight rows on mouse hover. Type: boolean. Default: true. VisualImpact: True – Rows highlight gray (#f3f4f6) on hover. False – No hover effect. Recommendations: interactive-tables – Use true when rows are clickable (with onRowClick); static-display – Use false for read‑only reference tables.

bordered

Show cell borders around all table cells. Type: boolean. Default: false. VisualImpact: True – 1px gray borders around all cells. False – Only header bottom border and row separators. Recommendations: dense-data – Use true for tables with many columns (helps distinguish cells); modern-design – Use false for cleaner, more modern appearance.

enablePagination

Enable server‑side pagination with page navigation controls and page size selector. Type: boolean. Default: false. VisualImpact: True – Shows pagination controls at bottom with First/Previous/Next/Last buttons and page size dropdown. Data loads page by page from server. Recommendations: large-datasets – Use true for tables with 50+ records to improve performance; small-datasets – Use false for tables with <50 records – loads all data at once; public-pages – Works on both public and authenticated pages using session‑based auth.

enableSorting

Enable server‑side column sorting – users can click column headers to sort data ascending/descending. Type: boolean. Default: false. VisualImpact: True – Column headers show sort indicator (↑↓) and become clickable. Data re‑fetches from server when sorted. Recommendations: data-exploration – Use true when users need to analyze/find data by sorting; fixed-order – Use false when data should always appear in specific order (e.g., chronological); performance – Server‑side sorting handles large datasets efficiently.

enableSearch

Enable server‑side search with debounced search box – searches across all fields in data source. Type: boolean. Default: false. VisualImpact: True – Shows search input box above table. Data filters as user types (500 ms debounce). Recommendations: large-datasets – Use true for tables with 20+ records to help users find data; small-datasets – Use false for small reference tables where all data fits on screen; performance – Server‑side search with debouncing prevents excessive API calls.

enableInlineEditing

Enable inline cell editing – users can click cells to edit values directly in table (auto‑saves to database). Type: boolean. Default: false. VisualImpact: True – Cells show hover effect and become editable on click. Input type matches field type (text, number, date, boolean dropdown, etc.). Shows 'Saving...' spinner during save. Recommendations: data-entry – Use true for quick data updates without opening dialogs; read-only – Use false for display‑only tables; field-types – Supports all field types: text, number, boolean, date, datetime, email, phone, url; auto-save – Changes save immediately on blur/Enter – no save button needed.

enableCrudActions

Enable Create/Update/Delete actions – adds 'Add New' button and row‑level Edit/Delete buttons with modal dialogs. Type: boolean. Default: false. VisualImpact: True – Shows 'Add New' button above table. Adds 'Actions' column with Edit (pencil) and Delete (trash) buttons for each row. Opens dialogs for add/edit operations. Recommendations: full-crud – Use true for admin interfaces where users manage records; read-only – Use false for display‑only tables; validation – Dialogs validate required fields before saving; confirmation – Delete shows confirmation prompt before removing record.

enableCsvExport

Enable CSV export – adds 'Export CSV' button to download table data as CSV file. Type: boolean. Default: false. VisualImpact: True – Shows 'Export CSV' button in toolbar above table. Downloads current view data as CSV file when clicked. Recommendations: reporting – Use true for data tables where users need to export data for analysis; simple-display – Use false for basic display tables where export isn’t needed.

enableColumnResize

Enable column resizing – users can drag column borders to resize column widths. Type: boolean. Default: true. VisualImpact: True – Column borders show resize cursor on hover. Users can drag to resize columns. Recommendations: data-exploration – Use true (default) for tables where users analyze data; fixed-layout – Use false for tables with fixed column widths.

enableColumnFilters

Enable per‑column filters – adds filter icons to column headers for filtering individual columns. Type: boolean. Default: false. VisualImpact: True – Column headers show filter icon. Users can apply filters to individual columns (text contains, equals, etc.). Recommendations: data-analysis – Use true for tables where users need to filter by specific columns; simple-search – Use false and rely on enableSearch for global search across all columns.

defaultPageSize

Default number of rows per page when pagination is enabled. Type: number. Default: 10. Recommendations: few-columns – Use 25‑50 for tables with 3‑5 columns; many-columns – Use 10‑25 for tables with 6+ columns; mobile-first – Use 10‑15 for mobile‑optimized tables.

pageSizeOptions

Available page size options in dropdown when pagination is enabled. Type: array of numbers. Default: [10, 25, 50, 100].

sortableColumns

Array of column keys that can be sorted (if empty/null, all columns are sortable when enableSorting=true). Type: array of strings. Recommendations: all-columns – Omit this property to make all columns sortable; selective – Use to restrict sorting to specific columns (e.g., exclude ID columns).

editableColumns

Array of column keys that can be edited inline (if empty/null, all non‑primary‑key columns are editable when enableInlineEditing=true). Type: array of strings. Recommendations: all-columns – Omit this property to make all columns editable (except primary key); selective – Use to restrict editing to specific columns (e.g., exclude calculated fields).

onRowClick

JavaScript code executed when user clicks a table row. Script has access to clicked row data, row index, and all page data sources. Type: string. VisualImpact: When set, rows show pointer cursor on hover and become clickable. Script executes on row click. Recommendations: simple-navigation – Use context.navigate() for navigating to different pages; data-source-integration – Use context.[dataSourceId].navigateToRecord() to load records into page data sources for master‑detail patterns; conditional-logic – Use if/else to perform different actions based on row data; error-handling – Errors automatically shown to user via alert, logged to console.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Type: string. SecurityNote: Parsed by cssParser utility. Tenants only affect their own pages (multi‑tenant isolation enforced).

Best Practices

• ALWAYS configure dataSource when displaying dynamic data (database tables or API responses)
• ALWAYS set onRowClick when building interactive tables (execute JavaScript on row click)
• Use context.row to access clicked row data in onRowClick scripts
• Use context.navigate('\/page?id=' + context.row.id) to navigate to other pages with row data
• Use await context.dataSourceId.navigateToRecord(context.row.id) to load records into page data sources
• Use auto‑detected columns from data source for faster setup (columns auto‑populate from first record)
• Set striped=true and hover=true for better table readability
• Keep column count reasonable (4‑8 columns) for mobile responsiveness
• Use static data source for placeholder/demo tables during design

Common Mistakes

Not setting onRowClick when users expect clickable rows

Why it's a problem: Without onRowClick, rows aren’t interactive even though they may look clickable.

Fix: Add onRowClick script to execute custom action: context.navigate('\/details?id=' + context.row.id)

Accessing non-existent row fields causing undefined errors

Why it's a problem: Script references context.row.fieldName that doesn’t exist in the data.

Fix: Check data structure first. Use context.console.log(context.row) to see available fields.

Forgetting await for async operations in onRowClick

Why it's a problem: Page data source methods (navigateToRecord, save, delete) are async and need await.

Fix: Use await: await context.customers.navigateToRecord(context.row.id)

Using onRowClick with wrong data source ID causing ‘not found’ errors

Why it's a problem: Script references context.dataSourceId but that page data source doesn’t exist on the page.

Fix: Check root.pageDataSources array for available data source IDs. Use exact ID from there.

Hardcoding column definitions instead of using auto-detected columns

Why it's a problem: Manual column configuration is time‑consuming and error‑prone. Auto‑detection reads columns from data source.

Fix: When dataSource is configured, system auto‑populates detectedColumns. Let columns auto‑fill from this.

Creating too many columns (10+ ) causing mobile layout issues

Why it's a problem: Tables with many columns require horizontal scrolling on mobile, poor UX.

Fix: Limit to 4‑8 columns. Show most important fields only. Consider detail view for additional fields.

Using dataSource.type='static' with hardcoded data in production apps

Why it's a problem: Static data won’t update. Users expect dynamic data from databases/APIs.

Fix: Use dataSource.type='datasource' with configured data source for production apps. Use 'static' only for demos/placeholders.

Invalid JSON in staticData causing empty table

Why it's a problem: staticData must be valid JSON array. Syntax errors result in parsing failure.

Fix: Validate JSON before saving. Use JSON.stringify() to generate valid JSON: [{\"field\": \"value\"}]

Setting both onRowClick AND enableInlineEditing=true

Why it's a problem: Conflicting behaviors: inline editing requires clicking cells, but onRowClick fires on any row click. User can’t edit cells without triggering navigation.

Fix: Choose ONE mode: (1) For navigation to detail pages: set onRowClick + enableInlineEditing=false, (2) For editable grids: set enableInlineEditing=true + enableCrudActions=true + NO onRowClick