Blocks Module API
Visual components for building dashboards.
BaseBlock
Location: dashboard_lego.blocks.base
Abstract base class for all dashboard blocks.
For detailed API documentation, see api-blocks.
TypedChartBlock
Location: dashboard_lego.blocks.typed_chart
Status: ✅ RECOMMENDED & UNIFIED (v0.15+)
Unified chart block using a plot registry with optional embedded controls.
Key Features:
✅ Unified API: One block for both static and interactive charts
✅ Reusable Plots: Central plot registry promotes code reuse
✅ Declarative: Define charts with parameters, not imperative code
✅ Block-Level Transformations:
transform_fnallows for powerful, localized data manipulation✅ Robust: Works correctly in navigation sections and with embedded controls
Constructor:
def __init__(
self,
block_id: str,
datasource: DataSource,
plot_type: str, # Name of the plot function from the registry
plot_params: Dict[str, Any] = None, # Params with {{placeholders}} for controls
plot_kwargs: Dict[str, Any] = None, # Static kwargs for the plot function
title: Optional[str] = None, # Static card title (no placeholders)
plot_title: Optional[str] = None, # Dynamic plot title (supports {{placeholders}})
controls: Optional[Dict[str, Control]] = None, # Optional embedded controls
subscribes_to: Union[str, List[str], None] = None,
transform_fn: Optional[Callable[[pd.DataFrame], pd.DataFrame]] = None, # NEW in v0.15
**kwargs
)
Title vs Plot Title (v0.15+):
Dashboard Lego separates static card titles from dynamic plot titles:
``title``: Static card header (no placeholder support)
``plot_title``: Dynamic plot title (supports
{{placeholders}})
Example:
chart = TypedChartBlock(
block_id="sales_chart",
datasource=datasource,
plot_type="scatter",
plot_params={"x": "date", "y": "sales", "color": "{{metric_selector}}"},
title="Sales Analysis", # Static card title
plot_title="Sales by {{metric_selector}}", # Dynamic plot title with placeholder
subscribes_to=["metric_selector"]
)
Block-Level Data Transformations (v0.15):
The transform_fn parameter allows blocks to apply custom data transformations (aggregation, pivoting, filtering) after global filters but before plotting.
Example:
top_products_chart = TypedChartBlock(
block_id="top_products",
datasource=datasource,
plot_type='bar',
plot_params={'x': 'Product', 'y': 'total_revenue'},
title="Top 10 Products by Revenue",
subscribes_to=['filters-category'],
transform_fn=lambda df: (
df.groupby('Product')['Revenue']
.sum()
.reset_index(name='total_revenue')
.sort_values('total_revenue', ascending=False)
.head(10)
)
)
Metrics Factory Pattern
Location: dashboard_lego.blocks.metrics_factory
Status: ✅ RECOMMENDED (v0.15+)
Factory function to create individual metric blocks for flexible layout.
Why Factory Pattern?
✅ Composable: Mix metrics with other blocks naturally
✅ Layout Compliant: Proper equal-height rows via flexbox
✅ Compact: No empty space in metric cards
✅ Theme-Aware: Colors resolved via ThemeConfig
Factory Function:
def get_metric_row(
metrics_spec: Dict[str, Dict[str, Any]],
datasource: DataSource,
subscribes_to: Optional[Union[str, List[str]]] = None,
row_options: Optional[Dict[str, Any]] = None,
block_id_prefix: str = "metric",
) -> Tuple[List[SingleMetricBlock], Dict[str, Any]]
Metrics Spec Format:
metrics_spec = {
'metric_id': {
'column': str, # Column name to aggregate
'agg': str | Callable, # Aggregation function
'title': str, # Display title
'color': str, # Bootstrap theme color
'dtype': str, # Type conversion (optional)
'color_rules': dict # Conditional coloring (optional)
}
}
Example:
from dashboard_lego.blocks import get_metric_row
metrics, row_opts = get_metric_row(
metrics_spec={
'total_revenue': {
'column': 'Revenue',
'agg': 'sum',
'title': 'Total Revenue',
'color': 'success' # Bootstrap theme color
},
'avg_price': {
'column': 'Price',
'agg': 'mean',
'title': 'Average Price',
'color': 'info'
},
'units_sold': {
'column': 'Quantity',
'agg': 'sum',
'title': 'Units Sold',
'color': 'primary'
}
},
datasource=datasource,
subscribes_to=['filters-category']
)
# Use in page layout
page = DashboardPage(
title="Dashboard",
blocks=[
(metrics, row_opts), # Metrics row
[chart1, chart2] # Charts row
]
)
Conditional Coloring (Optional):
metrics_spec = {
'profit_margin': {
'column': 'Profit',
'agg': lambda df: df['Profit'].sum() / df['Revenue'].sum(),
'title': 'Profit Margin %',
'color_rules': {
'thresholds': [0.0, 0.15, 0.30],
'colors': ['danger', 'warning', 'success']
# < 0%: danger, 0-15%: warning, 15-30%: success
}
}
}
MetricsBlock (Deprecated)
Status: ⚠️ DEPRECATED - Use get_metric_row() for new applications.
Deprecated since version 0.15.0: Use get_metric_row() instead. MetricsBlock violates layout contracts
by returning dbc.Row internally.
The MetricsBlock is maintained for backward compatibility but returns
a composite Row component, preventing proper equal-height layout integration.
ControlPanelBlock
Location: dashboard_lego.blocks.control_panel
Standalone control panel for global filters/settings.
Control Defaults:
- Sliders: Full width ({"xs": 12, "md": 12}) with modern-slider CSS class
- Dropdowns: Narrow width ({"xs": 12, "md": 4}) with compact-dropdown CSS class
- Other controls: Auto width ({"xs": 12, "md": "auto"})
Available CSS Classes:
- modern-slider: Modern styling for sliders with proper width and colors (uses CSS, not inline styles)
- compact-dropdown: Compact styling for dropdowns to save space
Override defaults by specifying col_props and className in your control specifications.
Note: dcc.Slider doesn’t support style prop - use className for styling.
See api-blocks for detailed documentation.
TextBlock
Location: dashboard_lego.blocks.text
Display dynamic markdown or HTML text content.
See api-blocks for detailed documentation.
KPIBlock (Deprecated)
Status: ⚠️ DEPRECATED - Use MetricsBlock for new applications.
The KPIBlock relied on the datasource.get_kpis() method, which was removed in v0.15.0. The new MetricsBlock provides a more powerful and flexible declarative API.