Skip to main content
Data Forms in Kodexa are defined using YAML configuration files. This declarative approach lets you build complex user interfaces without writing Vue component code.

​
Basic Structure

Every Data Form follows this structure: 
name: "Form Name"
description: "Description of the form's purpose"
cards:
  - type: cardType
    id: uniqueId
    properties:
      # Card-specific properties
    layout:
      x: 0
      y: 0
      w: 12
      h: 4
    children:  # Optional, for container cards
      - type: childCardType
        id: childId
        # ...

​
Top-Level Properties

​
name

  • Type: string
  • Required: Yes
  • Description: Human-readable name of the data form

​
description

  • Type: string
  • Required: No
  • Description: Detailed description of the form’s purpose and usage

​
cards

  • Type: array
  • Required: Yes
  • Description: List of card configurations that make up the form

​
Card Configuration

Each card in the cards array has these core properties:

​
type

  • Type: string
  • Required: Yes
  • Description: The card component type in camelCase (e.g., label, dataStoreGrid, tabs)
  • Example: type: transposedGridRollup

​
id

  • Type: string
  • Required: Yes
  • Description: Unique identifier for the card within the form
  • Naming Convention: Use descriptive, kebab-case names (e.g., main-grid, revenue-section)

​
properties

  • Type: object
  • Required: No (but most cards require some properties)
  • Description: Card-specific configuration options
  • Example: 
    properties:
  title: "Customer Data"
  dataStoreRef: "customers"
  readonly: false

​
layout

  • Type: object
  • Required: Yes
  • Description: Grid positioning and size
  • Properties:
    • x: Column position (0-11)
    • y: Row position (0+)
    • w: Width in columns (1-12)
    • h: Height in rows (1+)

​
children

  • Type: array
  • Required: No
  • Description: Nested cards for container components (tabs, cardGroup, cardPanel)
  • Note: Only available on cards where supportsChildren: true

​
Grid Layout System

The layout uses a 12-column grid: 
┌─────────────────────────────────────┐
│ 0  1  2  3  4  5  6  7  8  9  10 11 │  ← Column indices
└─────────────────────────────────────┘

​
Column Width Examples

# Full width
w: 12  # Spans all columns

# Half width
w: 6   # Spans 6 columns (50%)

# Third width
w: 4   # Spans 4 columns (33%)

# Quarter width
w: 3   # Spans 3 columns (25%)

​
Positioning Examples

# Top-left corner
layout:
  x: 0
  y: 0
  w: 6
  h: 4

# Top-right corner
layout:
  x: 6
  y: 0
  w: 6
  h: 4

# Second row, centered
layout:
  x: 3
  y: 4
  w: 6
  h: 3

​
Common Patterns

​
Full-Width Header

- type: label
  id: page-header
  properties:
    label: "Page Title"
  layout:
    x: 0
    y: 0
    w: 12
    h: 1

​
Two-Column Layout

# Left column
- type: dataStoreGrid
  id: left-grid
  layout:
    x: 0
    y: 1
    w: 6
    h: 10

# Right column
- type: dataObjectsTree
  id: right-tree
  layout:
    x: 6
    y: 1
    w: 6
    h: 10

​
Three-Column Layout

- type: label
  id: col1
  layout:
    x: 0
    y: 0
    w: 4
    h: 5

- type: label
  id: col2
  layout:
    x: 4
    y: 0
    w: 4
    h: 5

- type: label
  id: col3
  layout:
    x: 8
    y: 0
    w: 4
    h: 5

​
Tabbed Container

- type: tabs
  id: main-tabs
  properties:
    tabsSticky: true
  layout:
    x: 0
    y: 0
    w: 12
    h: 10
  children:
    - type: dataStoreGrid
      id: tab1-content
      properties:
        title: "Overview"
        dataStoreRef: "main-data"
      layout:
        x: 0
        y: 0
        w: 12
        h: 9

    - type: exceptions
      id: tab2-content
      properties:
        title: "Issues"
        dataStoreRef: "main-data"
      layout:
        x: 0
        y: 0
        w: 12
        h: 9

​
Property Types

​
String Properties

properties:
  title: "My Title"
  dataStoreRef: "store-id"

​
Boolean Properties

properties:
  readonly: true
  tabsSticky: false

​
Number Properties

properties:
  maxRows: 100
  defaultWidth: 300

​
Array Properties

properties:
  allowedDestinations:
    - "BalanceSheet/Assets"
    - "BalanceSheet/Liabilities"

​
Object Properties

properties:
  movement:
    enabled: true
    showOnRows: child
    rule:
      allowedDestinations: same-prefix

​
Validation

​
Required Properties

Cards will fail to render if required properties are missing. Check each card’s documentation for required properties.
Example error:
Error: Card 'dataStoreGrid' requires property 'dataStoreRef'

​
Type Validation

Properties must match their expected types: 
# ❌ Wrong - boolean as string
properties:
  readonly: "true"

# ✅ Correct
properties:
  readonly: true

​
Best Practices

​
1. Use Descriptive IDs

# ❌ Not descriptive
id: grid1

# ✅ Descriptive
id: customer-invoices-grid

​
2. Document Complex Forms

name: "Financial Reporting Form"
description: |
  This form presents quarterly financial data including:
  - Balance sheet with rollup categories
  - Income statement by period
  - Exception tracking for data quality

- type: cardPanel
  id: revenue-section
  properties:
    title: "Revenue Analysis"
  children:
    - type: transposedGridRollup
      id: revenue-breakdown
      # ...
    - type: exceptions
      id: revenue-exceptions
      # ...

​
4. Consistent Sizing

Use consistent heights for rows to create visual alignment: 
# All cards in row have h: 4
- type: label
  layout: { x: 0, y: 0, w: 4, h: 4 }

- type: label
  layout: { x: 4, y: 0, w: 4, h: 4 }

- type: label
  layout: { x: 8, y: 0, w: 4, h: 4 }

​
5. Test Incrementally

Build forms incrementally:
  1. Start with a simple label card
  2. Add one functional card at a time
  3. Test after each addition
  4. Add complexity gradually

​
Troubleshooting

​
Card Not Rendering

Check:
  1. Card type is spelled correctly (camelCase)
  2. All required properties are present
  3. Layout coordinates are valid (x: 0-11, y: 0+)
  4. Width doesn’t exceed 12 columns

​
Layout Issues

Check:
  1. Cards don’t overlap (same x, y position)
  2. Cards don’t exceed grid width (x + w ≤ 12)
  3. Height is sufficient for content

​
Property Errors

Check:
  1. Property names match card documentation exactly
  2. Values match expected types
  3. Required properties are not null/undefined