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)
source: examples_db
title: "Sales Overview"

queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales_by_date:
    sql: |
      SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date

charts:
  revenue:
    query: sales_by_category
    type: bar
    x: category
    y: revenue
  orders:
    query: sales_by_date
    type: line
    x: date
    y: units_sold
  trend:
    query: sales_by_date
    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
text: 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 shorthand (e.g., "3px solid #667eea")
  # border:                # Or nested block for radius + color + width separately
  #   radius: number       #   Border radius in px (e.g., 12)
  #   color: string        #   Border color
  #   width: number        #   Border width in px
  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:
        color: "#667eea"           # Border color
        width: 2                   # Border width (px)
        radius: 12                 # Rounded corners (px)
      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 or mapping	CSS border shorthand, or nested block with color, width, radius	"2px solid #667eea" or {color: "#667eea", width: 2, radius: 12}
color	string	Text color (affects titles and content)	"#667eea", "#333", "red"

Styling Examples

Colored Border with Rounded Corners:

rows:
  - title: "Main Container"
    style:
      border:
        color: "#667eea"
        width: 3
        radius: 12
      color: "#667eea"
    cols:
      - text: "This section has a colored border and rounded corners."

Background with Border:

rows:
  - title: "Highlighted Section"
    style:
      background: "#fff3cd"
      border:
        color: "#ffc107"
        width: 1
        radius: 8
    rows:
      - chart1
      - chart2

Nested Styling:

rows:
  - title: "Outer Container"
    style:
      border:
        color: "#764ba2"
        width: 2
        radius: 8
    cols:
      - title: "Inner Section"
        style:
          border:
            color: "#9c27b0"
            width: 1
            radius: 6
          color: "#9c27b0"
        text: "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.

---

Related

• 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