Boards¶

Boards are the fundamental building blocks of Dataface. They are containers that define what to render (charts, text), how to render it (layout type), and where to place it. Since boards can contain other boards, you can nest them infinitely to create complex, structured layouts.

Basic Board Structure¶

A board defines layout and content. The layout is determined by the presence of type-specific keys (e.g., rows, cols, grid, tabs).

# A simple board with rows (vertical stack)
title: "Sales Overview"

charts:
  revenue:
    query: _doc_examples.yaml#sales
    type: bar
    x: category
    y: revenue
  orders:
    query: _doc_examples.yaml#sales
    type: line
    x: date
    y: units_sold
  trend:
    query: _doc_examples.yaml#sales
    type: line
    x: date
    y: revenue

rows:
  - title: "KPIs"
    cols: # Horizontal stack
      - revenue
      - orders

  - title: "Trends"
    rows: # Nested vertical stack
      - trend

▶

Core Concepts¶

Layout Types¶

Boards support four layout types that determine how children are arranged:

Layout	Key	Description
Rows	`rows:`	Vertical stack (default)
Cols	`cols:`	Horizontal side-by-side
Grid	`grid:`	Flexible grid with positioning
Tabs	`tabs:`	Tabbed interface

See Layouts for detailed examples of each type.

Recursive Structure¶

Boards can contain charts OR other boards. This recursive structure means you can nest and vary layouts infinitely to create complex designs.

title: "Company Dashboard"
rows:
  - title: "Sales"
    cols:
      - title: "Q1"
        rows: ...
      - title: "Q2"
        rows: ...

  - title: "Marketing"
    rows: ...

Field Reference¶

# Board fields
title: string              # Optional display title
description: string        # Optional help text

# Layout (choose one)
rows: [items]              # Vertical stack
cols: [items]              # Horizontal stack
grid:                      # Grid layout
  columns: number
  items: [grid_items]
tabs:                      # Tabbed interface
  items: [tab_items]

# Content
content: string            # Markdown content block
charts:                    # Chart definitions
  <chart_id>: {...}
queries:                   # Query definitions
  <query_id>: {...}
variables:                 # Variable definitions
  <var_id>: {...}

# Styling
style:
  background: string       # Background color (hex, rgb, or named color)
  border: string           # CSS border (e.g., "3px solid #667eea")
  border_radius: string    # Border radius (e.g., "12px", "8px")
  color: string            # Text color (hex, rgb, or named color)

Board Styling¶

Boards support styling properties that control their visual appearance. Styles are applied to nested boards to create visual hierarchy and organization.

Style Properties¶

rows:
  - title: "Styled Section"
    style:
      background: "#f5f5f5"        # Background color
      border: "2px solid #667eea"   # Border (width style color)
      border_radius: "12px"         # Rounded corners
      color: "#667eea"              # Text color
    cols:
      - chart1
      - chart2

Available Style Properties¶

Property	Type	Description	Example
`background`	string	Background color (hex, rgb, or named color)	`"#f5f5f5"`, `"rgb(255, 0, 0)"`, `"white"`
`border`	string	CSS border specification	`"2px solid #667eea"`, `"1px dashed #ccc"`
`border_radius`	string	Border radius for rounded corners	`"12px"`, `"8px"`, `"4px"`
`color`	string	Text color (affects titles and content)	`"#667eea"`, `"#333"`, `"red"`

Styling Examples¶

Colored Border with Rounded Corners:

rows:
  - title: "Main Container"
    style:
      border: "3px solid #667eea"
      border_radius: "12px"
      color: "#667eea"
    cols:
      - content: "This section has a colored border and rounded corners."

Background with Border:

rows:
  - title: "Highlighted Section"
    style:
      background: "#fff3cd"
      border: "1px solid #ffc107"
      border_radius: "8px"
    rows:
      - chart1
      - chart2

Nested Styling:

rows:
  - title: "Outer Container"
    style:
      border: "2px solid #764ba2"
      border_radius: "8px"
    cols:
      - title: "Inner Section"
        style:
          border: "1px solid #9c27b0"
          border_radius: "6px"
          color: "#9c27b0"
        content: "Nested boards can have their own styles."

Style Inheritance¶

Styles are not inherited by child boards. Each board defines its own styling independently. This allows for precise control over the visual appearance of each section.

Layouts - Rows, cols, grid, and tabs
Content - Markdown and mixed content
Sizing - Width and height control
Imports - Reusability and file imports
Examples - Advanced layout patterns
Charts - Chart configuration
Styling - Themes and colors