Quick Reference

Quick reference for common tasks and configurations.

Class Summary 

Data Pipeline (v0.15)

DataSource: Concrete data source with 2-stage pipeline → get_processed_data(params)
DataBuilder: Data building stage (load + process) → build(params)
DataTransformer: Data transformation stage → transform(data, params)

Data Sources 

CsvDataSource: Load CSV files → __init__(file_path, **kwargs)
ParquetDataSource: Load Parquet files → __init__(file_path, **kwargs)
SqlDataSource: Load from databases → __init__(connection, query)

Core Components 

DashboardPage: Main orchestrator → build_layout(), register_callbacks()
StateManager: State coordination → register_publisher(), bind_callbacks()
ThemeConfig: Theme configuration → light_theme(), dark_theme(), get_figure_layout()

Blocks 

BaseBlock: Abstract block → layout(), output_target()
get_metric_row(): Factory function for metrics → get_metric_row(metrics_spec)
TypedChartBlock: Chart with plot registry → __init__(plot_type, plot_params)
ControlPanelBlock: Control panel only → __init__(controls)
TextBlock: Text/markdown → __init__(content_generator)

Configuration Options 

Bootstrap Grid System 

Breakpoint	Screen Width	Column Width
`xs`	<576px	1-12
`sm`	≥576px	1-12
`md`	≥768px	1-12
`lg`	≥992px	1-12
`xl`	≥1200px	1-12

Default: If no width specified, columns auto-size equally

State Naming Convention 

Pattern	Example	Usage
`{block_id}-{control_name}`	`filters-category`	Control panel state
`dummy_state`	`dummy_state`	Static blocks (no pub)

Loading Types 

Type	Appearance
`"default"`	Spinner
`"graph"`	Graph-specific loader
`"cube"`	Cube animation
`"circle"`	Circle animation
`"dot"`	Dot animation

Common Patterns 

Minimal Dashboard 

import dash
import dash_bootstrap_components as dbc
import pandas as pd
from dashboard_lego.core import DashboardPage, DataSource, DataBuilder
from dashboard_lego.blocks import get_metric_row

class MyDataBuilder(DataBuilder):
    def build(self, params):
        return pd.read_csv("data.csv")

datasource = DataSource(data_builder=MyDataBuilder())

metrics, row_opts = get_metric_row(
    metrics_spec={
        "total": {
            "column": "id",
            "agg": "count",
            "title": "Total",
            "color": "primary"
        }
    },
    datasource=datasource,
    subscribes_to="dummy_state"
)

page = DashboardPage(title="Dashboard", blocks=[(metrics, row_opts)])

app = dash.Dash(__name__, external_stylesheets=[dbc.themes.BOOTSTRAP])
app.layout = page.build_layout()
page.register_callbacks(app)
app.run_server(debug=True)

Interactive Dashboard 

control_panel = ControlPanelBlock(
    block_id="controls",
    datasource=datasource,
    title="Filters",
    controls={"category": Control(...)}
)

chart = TypedChartBlock(
    block_id="chart",
    datasource=datasource,
    plot_type='bar',
    plot_params={'x': 'Product', 'y': 'Sales'},
    subscribes_to="controls-category"
)

page = DashboardPage(
    title="Interactive Dashboard",
    blocks=two_column_8_4(main=chart, side=control_panel)
)

Error Handling 

Exception	When Raised	Recommended Action
`DataLoadError`	Data loading fails	Check file path, permissions, format
`CacheError`	Cache operation fails	Check cache directory permissions
`ConfigurationError`	Invalid parameters	Verify constructor arguments
`BlockError`	Block operation fails	Check block_id uniqueness, datasource
`StateError`	State management fails	Check for duplicate outputs, circular dependencies

Performance Tips 

Use Disk Cache: Set cache_dir for persistent caching
Tune Cache TTL: Balance freshness vs performance
Lazy Loading: Use navigation for large dashboards
Data Filtering: Filter at datasource level, not in generators
Parquet Format: Use for large datasets (faster than CSV)
Block-Centric Callbacks: Built-in optimization (one callback per block)
Staged Pipeline: Use DataBuilder + DataTransformer for optimal caching