DataGrid

Feature-rich data grid component powered by AG Grid Community. Displays structured data from static sources or dynamic data sources (database tables or REST APIs). Supports virtual scrolling for large datasets, column resizing/filtering, CSV export, inline editing, CRUD operations, and custom JavaScript event 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

binding

Query binding for loading grid data dynamically from a data query (preferred over dataSource). Type: object.

• query (string): Query name to bind to.
• field (string): Field name (optional).
• isReadOnly (boolean): Default: true.

dataSource

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

type (string): Source type - 'static' for hardcoded JSON data, 'datasource' for database tables or REST APIs. Options: static, datasource. Default: static. Visual Impact: 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 (string): JSON string containing array of records (only used when type='static'). Must be valid JSON array. Visual Impact: Must be valid JSON. Invalid JSON will result in empty table. Examples: [{"name":"John","email":"john@example.com"},{"name":"Jane","email":"jane@example.com"}], [{"id":1,"product":"Widget","price":29.99},{"id":2,"product":"Gadget","price":49.99}].

dataSourceId (string): ID of the configured data source (only used when type='datasource'). References a data source created in the system. Examples: customers-table, products-api, inventory-db.

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

pageSize (number): Number of records to load from data source (only used when type='datasource'). 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 (array): Auto-detected columns from data source (populated automatically by system when data source is selected). Used to auto-fill columns configuration. Items are objects with:

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

columns

Column definitions specifying which fields to display and how to label them. Type: array. Required: true. 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. Minimum items: 1, Maximum items: 20.

Each item (object) has:

• key (string, required): Field name from the data source (must match property name in data records). Examples: id, name, email, createdDate, totalAmount.
• label (string, required): Column header text displayed in table header. Examples: ID, Customer Name, Email Address, Created, Total.
• width (string, optional): CSS width value for column (optional, default: auto-width based on content). Examples: 100px, 20%, 150px, auto.
• format (string, optional): Special column formatting. 'currency' formats numbers as money, 'status' renders colored status badges. Options: currency, status.

striped

Alternating row background colors for improved readability. Type: boolean. Default: true. Visual Impact: 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. Visual Impact: 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. Visual Impact: 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. Visual Impact: 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. Visual Impact: 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. Visual Impact: True: Shows search input box above table. Data filters as user types (500ms 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. Visual Impact: 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. Visual Impact: 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. Visual Impact: 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. Visual Impact: 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. Visual Impact: 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. Default: [10, 25, 50, 100]. Examples: [10, 25, 50, 100], [5, 10, 20], [25, 50, 100, 250]. Items are numbers.

sortableColumns

Array of column keys that can be sorted (if empty/null, all columns are sortable when enableSorting=true). Type: array. Examples: ["name","createdDate","total"], ["firstName","lastName","email"]. Recommendations: all-columns: Omit this property to make all columns sortable; selective: Use to restrict sorting to specific columns (e.g., exclude ID columns). Items are strings.

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. Examples: ["name","email","phone"], ["quantity","price","status"]. 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). Items are strings.

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. Visual Impact: 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.

defaultNewRowValues

Default values for new rows created via CRUD 'Add' button. Keys are column field names, values are default strings. Supports template variables like {{queryName.fieldName}} that resolve at runtime. Type: object. Examples: {"status":"Active","priority":"Normal"}, {"contact_id":"{{contactQ.id}}","created_by":"{{userQ.name}}"}

customCss

Custom CSS styles for advanced styling. Parsed as CSS property-value pairs. Type: string. Examples: "background-color: #f8f9fa; padding: 20px; border-radius: 8px;", "box-shadow: 0 2px 8px rgba(0,0,0,0.1); margin-bottom: 24px;", "border: 2px solid #e9ecef; font-size: 13px;". Security Note: 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