Quick Start Guide

This guide will help you create your first dashboard using Dashboard Lego.

Creating Your First Dashboard

Let’s create a simple sales dashboard step by step.

Step 1: Define a Data Builder

v0.15+ uses composition instead of inheritance. Create a DataBuilder:

import pandas as pd
from dashboard_lego.core import DataBuilder, DataSource

class SalesDataBuilder(DataBuilder):
    def __init__(self, file_path):
        super().__init__()
        self.file_path = file_path

    def build(self, params):
        """Load CSV and optionally add calculated fields."""
        df = pd.read_csv(self.file_path)
        # Add any calculated columns here if needed
        return df

# Create datasource using composition (no inheritance!)
datasource = DataSource(
    data_builder=SalesDataBuilder("sample_data.csv")
)

Step 2: Create Dashboard Blocks

Create blocks using v0.15+ API:

import plotly.express as px
from dashboard_lego.blocks import get_metric_row, TypedChartBlock

# get_metric_row() factory creates metric blocks (v0.15+)
metrics, row_opts = get_metric_row(
    metrics_spec={
        "total_sales": {
            "column": "Sales",
            "agg": "sum",
            "title": "Total Sales",
            "color": "success"
        },
        "total_units": {
            "column": "UnitsSold",
            "agg": "sum",
            "title": "Total Units Sold",
            "color": "info"
        }
    },
    datasource=datasource,
    subscribes_to="dummy_state"
)

# TypedChartBlock with plot registry (v0.15+)
chart_block = TypedChartBlock(
    block_id="sales_chart",
    datasource=datasource,
    plot_type="bar",  # Built-in plot type
    plot_params={"x": "Fruit", "y": "Sales"},
    title="Fruit Sales",                    # Static card title
    plot_title="Sales by Fruit",            # Dynamic plot title
    subscribes_to="dummy_state",
    # Optional: transform data at block level (v0.15+)
    transform_fn=lambda df: df.groupby("Fruit")["Sales"].sum().reset_index()
)

Note

v0.15+ uses get_metric_row() factory function and TypedChartBlock which replace the legacy get_kpis() method and StaticChartBlock. See Core Concepts for more on block-level transformations.

Interactive Charts with Placeholders

For interactive charts with dynamic titles and parameters, use placeholders:

# Interactive chart with placeholders
interactive_chart = TypedChartBlock(
    block_id="interactive_sales",
    datasource=datasource,
    plot_type="scatter",
    plot_params={
        "x": "Date",
        "y": "Sales",
        "color": "{{metric_selector}}",  # Placeholder for dynamic color
        "size": "{{size_selector}}"      # Placeholder for dynamic size
    },
    title="Sales Analysis",                           # Static card title
    plot_title="Sales by {{metric_selector}}",      # Dynamic plot title with placeholder
    subscribes_to=["metric_selector", "size_selector"]
)

See placeholders for complete placeholder documentation.

Step 3: Create Dashboard Page

Assemble your blocks into a dashboard page:

from dashboard_lego.core.page import DashboardPage
from dashboard_lego.presets.layouts import one_column
import dash_bootstrap_components as dbc

# Create dashboard page using layout presets
dashboard_page = DashboardPage(
    title="Simple Sales Dashboard",
    blocks=[
        (metrics, row_opts),  # Metrics row with proper layout
        [chart_block]          # Chart block
    ],
    theme=dbc.themes.LUX
)

Step 4: Run the Application

Set up and run your Dash application:

import dash

# Create Dash app
app = dash.Dash(__name__, external_stylesheets=[dashboard_page.theme])
app.layout = dashboard_page.build_layout()

# Register callbacks (handled automatically)
dashboard_page.register_callbacks(app)

# Run the app
if __name__ == "__main__":
    app.run_server(debug=True)

Complete Example

Here’s the complete code for your first dashboard:

Next Steps

Now that you’ve created your first dashboard, you might want to:

Add Interactivity: Explore interactive blocks in the API reference (Blocks Module).
Use Presets: See preset components in (Presets Module).
Custom Layouts: Learn layout helpers in (Presets Module).
Create Custom Blocks: Learn how to extend Dashboard Lego with your own components

Running the Example

To run this example:

Save the code to a file (e.g., my_dashboard.py)
Create a sample data file with columns: Fruit, Sales, UnitsSold
Run: python my_dashboard.py
Open your browser to http://localhost:8050

Troubleshooting

Common issues and solutions:

Import Error: Make sure Dashboard Lego is installed:

pip install dashboard-lego

Data Loading Error: Check that your data file exists and has the expected columns.

Chart Not Displaying: Verify that your data source is properly initialized with datasource.init_data().