Skip to content

Data Binding Tutorial

Learn how to connect charts and tables to external data sources (CSV and JSON files) for dynamic, maintainable presentations.

Overview

Data binding allows you to separate data from presentation logic. Instead of hardcoding values in your schema, you can reference external CSV or JSON files. This makes it easy to:

  • Update data without editing the schema
  • Reuse the same schema with different datasets
  • Maintain data in spreadsheets or databases
  • Version control data separately from presentation structure

Supported Data Sources

  • CSV files - Comma-separated values (.csv)
  • JSON files - JavaScript Object Notation (.json)

Chart Data Binding

CSV Data Source

Reference a CSV file for chart data:

slides:
  - layout: chart
    title: "Revenue Trend"
    chart:
      type: line
      data:
        source: data/quarterly.csv
        format: csv

CSV Format:

The CSV file should have a header row and data rows:

Quarter,Revenue
Q1,100
Q2,120
Q3,140
Q4,160

Column Mapping:

By default, SlideGen uses: - First column: Labels (x-axis) - Second column: Values (y-axis)

For custom column mapping:

chart:
  type: line
  data:
    source: data/quarterly.csv
    format: csv
    label_column: "Quarter"
    value_column: "Revenue"

JSON Data Source

Reference a JSON file for chart data:

slides:
  - layout: chart
    title: "Revenue Trend"
    chart:
      type: line
      data:
        source: data/quarterly.json
        format: json

JSON Format - Single Series:

{
  "labels": ["Q1", "Q2", "Q3", "Q4"],
  "values": [100, 120, 140, 160]
}

JSON Format - Multi-Series:

{
  "labels": ["Q1", "Q2", "Q3", "Q4"],
  "series": [
    {
      "name": "Product A",
      "values": [100, 120, 140, 160]
    },
    {
      "name": "Product B",
      "values": [80, 90, 110, 130]
    }
  ]
}

Multi-Series Chart:

chart:
  type: bar
  data:
    source: data/products.json
    format: json

Inline Data

You can also specify data directly in the schema (no external file):

chart:
  type: line
  data:
    labels: ["Q1", "Q2", "Q3", "Q4"]
    values: [100, 120, 140, 160]

Multi-Series Inline:

chart:
  type: bar
  data:
    labels: ["Q1", "Q2", "Q3", "Q4"]
    series:
      - name: "Product A"
        values: [100, 120, 140, 160]
      - name: "Product B"
        values: [80, 90, 110, 130]

Table Data Binding

CSV Data Source

Reference a CSV file for table data:

slides:
  - layout: table
    title: "Sales by Region"
    table:
      data:
        source: data/sales.csv
        format: csv
        has_header: true

CSV Format:

Region,Q1,Q2,Q3,Q4
North,100,120,140,160
South,80,90,110,130
East,90,100,120,140
West,70,80,90,100

Options:

  • has_header: true - First row is treated as header (default: true)
  • has_header: false - All rows are data rows

Inline Table Data

Specify table data directly in the schema:

table:
  data:
    - ["Region", "Q1", "Q2", "Q3", "Q4"]
    - ["North", "100", "120", "140", "160"]
    - ["South", "80", "90", "110", "130"]
  header_row: true

File Path Resolution

Data source paths are resolved relative to the schema file location.

Example Structure:

project/
├── deck.yaml
├── data/
│   ├── quarterly.csv
│   └── sales.json
└── output.pptx

In deck.yaml:

chart:
  data:
    source: data/quarterly.csv  # Relative to deck.yaml

Absolute Paths:

You can also use absolute paths:

chart:
  data:
    source: /absolute/path/to/data.csv

Best Practices

1. Organize Data Files

Keep data files in a dedicated directory:

project/
├── deck.yaml
├── data/
│   ├── financial/
│   │   ├── revenue.csv
│   │   └── expenses.csv
│   └── sales/
│       └── by-region.csv

2. Use Descriptive File Names

# Good
source: data/quarterly-revenue-2025.csv

# Avoid
source: data/data1.csv

3. Version Control Data

Include data files in version control (Git) to track changes:

git add data/quarterly.csv
git commit -m "Update Q4 revenue data"

4. Validate Data Before Building

Check that data files exist and are valid:

# Validate schema (checks data file existence)
slidegen validate deck.yaml

# Check CSV format
cat data/quarterly.csv

# Validate JSON
python -m json.tool data/quarterly.json

5. Use Consistent Formats

Standardize your data formats across files:

CSV: - Always include header row - Use consistent column names - Use consistent date formats

JSON: - Use consistent structure - Include labels and values arrays - Use descriptive property names

Common Patterns

Pattern 1: Quarterly Reports

Update data files monthly, regenerate presentations:

# deck.yaml
chart:
  data:
    source: data/quarterly-revenue.csv

Update data/quarterly-revenue.csv each quarter, rebuild presentation.

Pattern 2: Multi-Chart Presentation

Reuse the same data file for multiple charts:

slides:
  - layout: chart
    title: "Revenue"
    chart:
      data:
        source: data/financials.csv
        label_column: "Quarter"
        value_column: "Revenue"

  - layout: chart
    title: "Expenses"
    chart:
      data:
        source: data/financials.csv
        label_column: "Quarter"
        value_column: "Expenses"

Pattern 3: Automated Data Updates

Generate data files from scripts or databases:

# generate_data.py
import csv

data = [
    ["Quarter", "Revenue"],
    ["Q1", "100"],
    ["Q2", "120"],
    # ... fetch from database
]

with open("data/quarterly.csv", "w") as f:
    writer = csv.writer(f)
    writer.writerows(data)

Then build presentation:

python generate_data.py
slidegen build deck.yaml -o output.pptx

Troubleshooting

File Not Found

Error: FileNotFoundError: data/quarterly.csv

Solution: - Check file path is correct (relative to schema file) - Verify file exists: ls data/quarterly.csv - Use absolute path if needed

Invalid CSV Format

Error: ValueError: Invalid CSV format

Solution: - Check CSV has header row - Verify comma separation - Check for encoding issues (use UTF-8)

Invalid JSON Format

Error: ValueError: Invalid JSON format

Solution: - Validate JSON: python -m json.tool data.json - Check for syntax errors - Verify structure matches expected format

Column Not Found

Error: ValueError: Column 'Revenue' not found

Solution: - Check column name matches CSV header - Verify case sensitivity - Check for extra spaces in column names

Next Steps