Skip to content

Board Imports & Dynamic Layouts

Build modular dashboards by importing other board files, referencing specific sections, or dynamically generating layouts with foreach.

Importing Files

Include the entire content of another board file by referencing its filename (without extension). This is useful for splitting large dashboards into smaller, manageable files.

# File: main_dashboard.yml
title: "Company Overview"
rows:
  - _header_section       # Imports content from _header_section.yml
  - _sales_kpis           # Imports content from _sales_kpis.yml
  - _marketing_kpis       # Imports content from _marketing_kpis.yml

Partial Files

Files starting with _ are commonly used for components that aren't meant to be viewed alone:

faces/
├── main_dashboard.yml      # Main entry point
├── _header_section.yml     # Partial: header
├── _sales_kpis.yml         # Partial: sales KPIs
├── _marketing_kpis.yml     # Partial: marketing KPIs
└── _footer.yml             # Partial: footer

Named Section References

Reference specific parts of another board file by giving nested boards an explicit id.

Step 1: Define a Named Board

Add an id to any layout section you want to reuse:

# File: sales_dashboard.yml
rows:
  - id: kpi_section  # Give this section an ID
    title: "Key Performance Indicators"
    cols:
      - revenue_kpi
      - orders_kpi

  - id: trends_section
    title: "Trends"
    rows:
      - revenue_trend
      - orders_trend

Step 2: Reference the Named Board

Reference that section from any other file using filename.id:

# File: executive_summary.yml
rows:
  - sales_dashboard.kpi_section      # Only the KPI section
  - marketing_dashboard.kpi_section  # From another file

Use Cases

Shared Headers/Footers

# _header.yml
content: |
  # Company Dashboard
  Last updated: {{ now }}
style:
  background: "#1e40af"
  color: white

# any_dashboard.yml
rows:
  - _header
  - main_content
  - _footer

Reusable KPI Rows

# _standard_kpis.yml
cols:
  - revenue_kpi
  - orders_kpi
  - growth_kpi

# sales.yml
rows:
  - _standard_kpis
  - sales_specific_content

# marketing.yml
rows:
  - _standard_kpis
  - marketing_specific_content

Component Library

# components/_metric_card.yml
id: metric_card
style:
  background: "#f3f4f6"
  padding: "1rem"
cols:
  - content: "{{ title }}"
  - content: "{{ value }}"

The foreach Construct

Generate layout items dynamically by iterating over data. This is powerful for auto-generating charts, profiling data, or creating repetitive sections programmatically.

Basic Syntax

rows:
  - foreach:
      query:
        data:
          - name: "Revenue"
            value: 100
          - name: "Orders"
            value: 250
      as: item
      items:
        - title: "{{ item.name }}"
          content: "Value: {{ item.value }}"

Required fields:

Field Description
query Data source with inline data array
as Variable name for each iteration (accessed via dot notation)
items List of layout items to generate per iteration

How It Works

  1. The foreach iterates over each row in query.data
  2. Each row is bound to the variable name specified in as
  3. The items template is rendered for each row, with Jinja templating
  4. All generated items are inserted into the parent layout

Examples

Generating Cards from Data

title: "KPI Dashboard"
rows:
  - foreach:
      query:
        data:
          - metric: "Total Revenue"
            value: "$1.2M"
            trend: "+15%"
          - metric: "Active Users"
            value: "45,231"
            trend: "+8%"
          - metric: "Conversion Rate"
            value: "3.2%"
            trend: "-2%"
      as: kpi
      items:
        - title: "{{ kpi.metric }}"
          content: |
            **{{ kpi.value }}**

            {{ kpi.trend }}

Dynamic Board Imports with foreach

Combine foreach with board imports to generate different visualizations based on data types:

# partials/numeric.yml
title: "{{ col.name }} Distribution"
charts:
  histogram_example:
    query: ...
    type: bar
    x: {{ col.name }}
    y: count
rows:
  - histogram_example

# partials/date.yml
title: "{{ col.name }} Timeline"
charts:
  timeline:
    query: ...
    type: line
    x: {{ col.name }}
    y: count
rows:
  - timeline

# main_dashboard.yml
title: "Auto-Generated Charts"
rows:
  - foreach:
      query:
        data:
          - name: "revenue"
            type: "numeric"
          - name: "created_at"
            type: "date"
          - name: "order_total"
            type: "numeric"
      as: col
      items:
        - partials/{{ col.type }}.yml

This generates: - A histogram for revenue (using partials/numeric.yml) - A timeline for created_at (using partials/date.yml) - A histogram for order_total (using partials/numeric.yml)

Variable Inheritance

foreach loop variables merge with parent variables. Imported partials can access both:

# partials/chart.yml
title: "{{ model }}.{{ col.column }}"  # model from parent, col from foreach
content: "Database: {{ connection }}"

# dashboard.yml
title: "Data Explorer"
variables:
  model:
    input: text
    default: "orders"
  connection:
    input: text
    default: "postgres://localhost/db"
rows:
  - foreach:
      query:
        data:
          - column: "total"
          - column: "quantity"
      as: col
      items:
        - partials/chart.yml

Results in boards with titles: - orders.total - orders.quantity

Both have access to the connection variable from the parent scope.

Use Cases

Use Case Description
Data Profiling Auto-generate charts for each column in a table
Multi-Metric Dashboards Create consistent KPI cards from a metrics list
Type-Specific Visualizations Route columns to different partials based on data type
Parameterized Reports Generate sections for each region, product, or time period

Best Practices

File Organization

faces/
├── main.yml                # Entry points
├── sales.yml
├── marketing.yml
│
├── _components/            # Shared components
│   ├── _header.yml
│   ├── _footer.yml
│   └── _kpi_row.yml
│
├── partials/               # foreach-compatible partials
│   ├── numeric.yml         # Numeric column visualization
│   ├── date.yml            # Date column visualization
│   └── categorical.yml     # Categorical visualization
│
└── _queries/               # Shared queries
    └── _common_queries.yml

Naming Conventions

  • Use _ prefix for partials that aren't standalone files
  • Use descriptive names: _sales_kpis.yml not _kpis.yml
  • Group related partials in folders
  • For foreach partials, name by what they visualize: numeric.yml, date.yml

When to Use foreach

Use foreach when: - Generating similar layouts from a list of items - Building data profiling or auto-documentation tools - Creating type-specific visualizations based on metadata - You need programmatic control over layout generation

When to Extract to Partials

Extract to a partial when: - Content is used in 2+ places - Section is large and complex - You want to test a section in isolation - You're using foreach with type-specific templates