UI Builder

UI Builder module for constructing complete user interface definitions.

This module provides the UiBuilder class, which serves as the central orchestrator for creating and managing all aspects of a user interface. It offers a fluent, builder-pattern API for constructing complex UIs through factory methods that create and register various components.

The builder pattern allows for declarative UI construction where components are added incrementally and then compiled into a final model definition via the build() method.

Classes:

• UiBuilder: Central builder class for UI construction

Example

>>> # Initialize builder
>>> builder = UiBuilder()
>>>
>>> # Add views
>>> products_table = Table("products")
>>> products_view = builder.add_table_view(
...     table=products_table,
...     display_name="Product Catalog"
... )
>>>
>>> sales_view = builder.add_chart_view(
...     chart_title="Sales Dashboard",
...     primary_series=sales_series,
...     secondary_series=region_series,
...     chart_type=ChartType.BAR,
...     table=sales_table
... )
>>>
>>> # Configure navigation
>>> builder.add_navigation_item(products_view)
>>> builder.add_navigation_item(sales_view)
>>>
>>> # Set default and build
>>> builder.set_default_view(products_view)
>>> ui_definition = builder.build()

class UiBuilder

Bases: Buildable

Central builder class for constructing complete user interface definitions.

UiBuilder serves as the main orchestrator for creating UI configurations. It provides an API for building complex user interfaces through a series of factory methods that create and register various UI components.

Once all components are configured, calling build() produces the final ui definition that can be used to render the complete UI.

set_validation_view(view)

Sets the view to be redirected to if optimisation is blocked.

Parameters:

view (BaseView) – The view to use for data validation.

add_context_variable(id, type, default_value=None, is_array=False)

Register a context variable that can be referenced within the view.

Parameters:

• id (str) – Unique identifier of the context variable.

• type (CVType) – Declared data type of the variable (e.g., INTEGER, DECIMAL, STRING, BOOLEAN).

• default_value (bool | int | float | str | Parameter | Calculation | None) – Optional default value used when no explicit value is provided.

• is_array (bool) – Whether the variable represents a list of values instead of a single scalar.

Raises:

ValueError when id already exists. –

Return type:

ContextVariable

Example

>>> builder = UiBuilder()
>>>
>>> # Add a simple integer context variable
>>> page_size_var = builder.add_context_variable(
...     id="page_size",
...     type=CVType.INTEGER,
...     default_value=25
... )
>>>
>>> # Add a boolean flag
>>> debug_mode = builder.add_context_variable(
...     id="debug_mode",
...     type=CVType.BOOLEAN,
...     default_value=False
... )
>>>
>>> # Add an array variable
>>> selected_ids = builder.add_context_variable(
...     id="selected_items",
...     type=CVType.INTEGER,
...     is_array=True
... )

get_context_variable(variable_id)

Retrieve a context variable by ID.

Raises:

KeyError – If no context variable with the given ID exists.

Returns:

ContextVariable

Example

>>> builder = UiBuilder()
>>> page_size = builder.add_context_variable(
...     "page_size",
...     CVType.INTEGER,
...     default_value=25
... )
>>>
>>> # Retrieve the context variable later
>>> retrieved_var = builder.get_context_variable("page_size")
>>> print(retrieved_var.id)  # Output: page_size
>>>
>>> # Use pre-configured variables
>>> true_var = builder.get_context_variable("TRUE")
>>> false_var = builder.get_context_variable("FALSE")

add_location_view(table, latitude, longitude)

Create and register a location-based map view.

A location view displays individual point locations on a map using latitude and longitude coordinates from the data table. Each row in the table represents a single location marker on the map.

Parameters:

• table (Table) – The data table containing location information.

• latitude (Field) – Field in the table containing latitude coordinates (numeric).

• longitude (Field) – Field in the table containing longitude coordinates (numeric).

Returns:

The created location map view builder instance, allowing further configuration such as markers, popups, and styling.

Return type:

MapView

Example

>>> map_view = builder.add_location_view(
...     table=locations_table,
...     latitude=lat_field,
...     longitude=lng_field,
... )

add_route_view(table, latitude, longitude)

Create and register a route-based map view.

A route view displays connected paths or routes on a map by connecting sequential points from the data table. The rows are ordered and connected to form a continuous path, useful for visualising delivery routes, travel paths, or sequential journeys.

Parameters:

• table (Table) – The data table containing route waypoint information.

• latitude (Field) – Field in the table containing latitude coordinates for waypoints.

• longitude (Field) – Field in the table containing longitude coordinates for waypoints.

Returns:

The created route map view builder instance, allowing further configuration such as route styling, markers, and waypoint display.

Return type:

MapView

Example

>>> route_view = builder.add_route_view(
...     table=delivery_table,
...     latitude=lat_field,
...     longitude=lng_field,
... )

add_grid_view(layout, display_name=None, hidden=False)

Create and register a CSS grid-based layout view.

A grid view uses CSS Grid Layout to arrange child components in a two-dimensional grid structure with precise control over rows, columns, and alignment. This is ideal for creating structured, responsive layouts.

Parameters:

• layout (GridLayout) – The grid layout configuration defining the grid structure, including template columns, rows, and cell assignments.

• display_name (str | None) – Optional display label for the view. Default is None.

• hidden (bool) – Whether the view should initially be hidden. Default is False.

Returns:

The created grid view builder instance for further configuration.

Return type:

GridView

Example

>>> from daitum_ui.layout import GridLayout
>>>
>>> grid_layout = GridLayout(
...     columns=["1fr", "2fr", "1fr"],
...     rows=["auto", "1fr"],
...     areas=[["header", "header", "header"], ["nav", "main", "aside"]]
... )
>>>
>>> grid_view = builder.add_grid_view(
...     layout=grid_layout,
...     display_name="Dashboard Layout"
... )

add_flex_view(display_name=None, hidden=False)

Create and register a CSS flexbox-based layout view.

A flex view uses CSS Flexbox Layout to arrange child components in a one-dimensional flow (either horizontal or vertical) with flexible sizing and alignment. This is ideal for creating responsive, flowing layouts.

Parameters:

• display_name (str | None) – Optional display label for the view. Default is None.

• hidden (bool) – Whether the view should initially be hidden. Default is False.

Returns:

The created flex view builder instance for further configuration.

Return type:

FlexView

Example

>>> toolbar_view = builder.add_flex_view(display_name="Toolbar")
>>> toolbar_view.set_flex_direction(FlexDirection.ROW).set_gap("10px")

add_table_view(table, display_name=None, hidden=False)

Create and register a tabular data view.

A table view displays data in a traditional row-and-column spreadsheet-like format with support for sorting, filtering, and interactive controls. This is one of the most common view types for displaying structured data.

Parameters:

• table (Table) – The data table to display.

• display_name (str | None) – Optional display label for the view in navigation. Default is None.

• hidden (bool) – Whether the view should initially be hidden. Default is False.

Returns:

The created table view builder instance for further configuration, such as adding columns, configuring actions, and styling.

Return type:

TableView

Example

>>> products_table = Table("products")
>>> products_view = builder.add_table_view(
...     table=products_table,
...     display_name="Product Catalog"
... )

add_tree_view(table, display_name=None, hidden=False)

Create and register a hierarchical tree table view.

A tree view displays data in a hierarchical structure with expandable/ collapsible nodes, similar to a file system browser. Each row can have child rows, creating a parent-child relationship that can be nested multiple levels deep.

Parameters:

• table (Table) – The data table containing hierarchical data. The table should have a parent reference field to define relationships.

• display_name (str | None) – Optional display label for the view in navigation. Default is None.

• hidden (bool) – Whether the view should initially be hidden. Default is False.

Returns:

The created tree view builder instance for further configuration, including setting the parent field and configuring columns.

Return type:

TreeView

Example

>>> tasks_table = Table("tasks")
>>>
>>> tree_view = builder.add_tree_view(
...     table=tasks_table,
...     display_name="Task Hierarchy"
... )

add_fixed_value_view(display_name=None, hidden=False)

Creates and registers a FixedValueView configuration for this element.

Parameters:

• display_name (str | None) – The name displayed in the UI.

• hidden (bool) – Whether the element should be initially hidden.

Returns:

The created view builder instance.

Return type:

FixedValueView

Example

>>> constants_view = builder.add_fixed_value_view(
...     display_name="System Constants"
... )

add_named_value_view(display_name=None, hidden=False, orientation=Orientation.HORIZONTAL)

Create and register a named value display view.

A named value view displays a collection of label-value pairs in a structured format. This is useful for showing key metrics, summary statistics, or configuration values in a clean, organized way.

Parameters:

• display_name (str | None) – Optional display label for the view in navigation. Default is None.

• hidden (bool) – Whether the view should initially be hidden. Default is False.

• orientation (Orientation) – Layout orientation for the name-value pairs. HORIZONTAL arranges labels and values side-by-side, while VERTICAL stacks them. Default is Orientation.HORIZONTAL.

Returns:

The created named value view builder instance for adding name-value pairs and configuring styling.

Return type:

NamedValueView

Example

>>> # Create a horizontal stats display
>>> stats_view = builder.add_named_value_view(
...     display_name="Summary Statistics",
...     orientation=Orientation.HORIZONTAL
... )

add_chart_view(primary_series, chart_type, table, display_name=None)

Create and register a standard ChartView.

Parameters:

• primary_series (ChartSeries) – Primary data series definition.

• chart_type (ChartType) – Type of chart to render (e.g., BAR, LINE).

• table (Table) – Table from which the chart draws its data.

• display_name (str | None) – Optional display label for the view.

Returns:

The created chart view builder instance.

Return type:

ChartView

Example

>>> chart_view = builder.add_chart_view(
...     primary_series=primary,
...     chart_type=ChartType.BAR,
...     table=sales_table,
...     display_name="Sales Chart"
... )

add_combination_chart_view(primary_series, chart_type, table, display_name=None)

Create and register a CombinationChartView.

Parameters:

• primary_series (ChartSeries) – Primary data series definition.

• chart_type (ChartType) – Base chart type applied to the view.

• table (Table) – Table providing the data for the chart.

• display_name (str | None) – Optional display label for the view.

Returns:

The created combination chart view builder instance.

Return type:

CombinationChartView

Example

>>> combo_chart = builder.add_combination_chart_view(
...     primary_series=revenue_series,
...     chart_type=ChartType.BAR,
...     table=metrics_table,
...     display_name="Performance Dashboard"
... )

add_roster_view(source_table, display_name=None, hidden=False)

Create and register a RosterView for this view builder.

Parameters:

• source_table (Table) – The data table that supplies row and shift information for the roster.

• display_name (str | None) – An optional human-readable name for the roster view.

• hidden (bool) – Whether the roster view should be initially hidden in the UI.

Return type:

RosterView

Returns:

RosterView

The constructed roster view builder instance, allowing additional configuration to be chained fluently.

Example

>>> roster_view = builder.add_roster_view(
...     source_table=shifts_table,
...     display_name="Employee Schedule"
... )

add_card_view(card_template, table=None, display_name=None)

Creates and adds a CardView definition to this view builder.

Parameters:

• card_template (Card) – The card layout template applied to each rendered row.

• table (Table | None) – Optional data table that provides rows for the card view.

• display_name (str | None) – Optional display name for the card view.

Returns:

The newly created card view definition.

Return type:

CardView

Example

>>> card_view = builder.add_card_view(
...     card_template=product_card,
...     table=products_table,
...     display_name="Product Gallery"
... )

add_tree_grid_gantt_view(table, gantt_task_definition, display_name=None, hidden=False, use_filter=None)

Create and register a TreeGridGanttView with hierarchical task organization.

A tree-grid Gantt view combines a hierarchical tree structure with a Gantt chart timeline, allowing tasks to be organized with parent-child relationships and displayed alongside their schedule visualization.

Parameters:

• table (Table) – The data table containing task records.

• gantt_task_definition (TreeGridGanttTaskDefinition) – TreeGridGanttTaskDefinition with tree-grid specific configuration including parent field and name field mappings.

• display_name (str | None) – Optional display label for the view in the navigation.

• hidden (bool) – Whether the view should initially be hidden in the UI.

• use_filter (FilterComponent | None) – The identifier (filter name) of a ViewFilterDef to apply when querying data for this view.

Returns:

The created tree-grid Gantt view builder instance,

allowing further configuration such as x-axis behavior, drag-drop settings, and tooltip properties.

Return type:

TreeGridGanttView

Example

>>> # Create a hierarchical project Gantt chart
>>> project_tasks = Table("project_tasks")
>>> task_def = TreeGridGanttTaskDefinition(
...     name_field=Field("task_name", DataType.STRING),
...     start_field=Field("start_date", DataType.DATE),
...     end_field=Field("end_date", DataType.DATE),
...     parent_field=Field("parent_task_id", DataType.INTEGER)
... )
>>>
>>> gantt_view = builder.add_tree_grid_gantt_view(
...     table=project_tasks,
...     gantt_task_definition=task_def,
...     display_name="Project Timeline"
... )

add_category_gantt_view(table, gantt_task_definition, display_name=None)

Create and register a CategoryGanttView with categorical task organization.

A category Gantt view organizes tasks into categories along the y-axis rather than using a hierarchical tree structure. Each category row can contain multiple tasks displayed on the timeline.

Parameters:

• table (Table) – The data table containing task records.

• gantt_task_definition (CategoryGanttTaskDefinition) – GanttTaskDefinition defining how fields map to task properties.

• display_name (str | None) – Optional display label for the view in the navigation.

Returns:

The created category Gantt view builder instance,

allowing further configuration such as x-axis behavior, drag-drop settings, and tooltip properties.

Return type:

CategoryGanttView

Example

>>> gantt_view = builder.add_category_gantt_view(
...     table=assignments_table,
...     gantt_task_definition=task_def,
...     display_name="Resource Allocation"
... )

add_form_view(display_name=None, hidden=False, total_rows=None, table=None, match_row=None)

Creates and adds a FormView definition to this view builder.

Parameters:

• display_name (str | None) – Optional display name for the view.

• hidden (bool) – Whether the form view should initially be hidden.

• total_rows (int | None) – Optional fixed number of rows for the form layout.

• table (Table | None) – Optional data table backing the form.

• match_row (MatchRowFilterMode | None) – Determines how row-matching is applied when binding data.

Returns:

The newly created form view definition.

Return type:

FormView

Example

>>> # Create a data entry form
>>> customer_table = Table("customers")
>>> form_view = builder.add_form_view(
...     display_name="Customer Information",
...     total_rows=4,
...     table=customer_table,
...     match_row=MatchRowFilterMode.FIRST_ROW
... )
>>>
>>> # Add form fields
>>> form_view.add_column("100px")

add_tabbed_view(display_name=None, hidden=False, use_full_width_tabs=False, headless_context_variable=None, tab_padding=None)

Creates and adds a TabbedView definition to this view builder.

Parameters:

• display_name (str | None) – Optional display name for the tabbed view.

• hidden (bool) – Whether the tabbed view should initially be hidden.

• use_full_width_tabs (bool) – If True, tabs stretch across the full width of the container.

• headless_context_variable (ContextVariable | None) – Context variable controlling which tab is active when headless mode is enabled.

• tab_padding (str | None) – Optional padding applied around the tab headers.

Returns:

The newly created tabbed view definition.

Return type:

TabbedView

Example

>>> # Create a tabbed view with multiple tabs
>>> tabbed_view = builder.add_tabbed_view(
...     display_name="Dashboard Tabs",
...     use_full_width_tabs=True,
...     tab_padding="10px"
... )
>>>
>>> # Add tabs (child views)
>>> overview_table = builder.add_table_view(...)
>>> details_chart = builder.add_chart_view(...)
>>> tabbed_view.add_tab("Overview", overview_table)
>>> tabbed_view.add_tab("Details", details_chart)

add_navigation_item(view, background_color=None, active_color=None, font_color=None)

Create and register a single-view navigation item.

Parameters:

• view (BaseView) – The view that this navigation item should open directly.

• background_color (str | None) – Optional hex RGB string for the item’s default background colour.

• active_color (str | None) – Optional hex RGB string for the highlight colour when the item is active.

• font_color (str | None) – Optional hex RGB string specifying the text colour of the navigation label.

Return type:

SingleViewNavItem

Returns:

SingleViewNavItem

A builder allowing further configuration, such as attaching hidden conditions or adjusting colours.

Example

>>> # Create views and add to navigation
>>> products_view = builder.add_table_view(
...     table=products_table,
...     display_name="Products"
... )
>>> orders_view = builder.add_table_view(
...     table=orders_table,
...     display_name="Orders"
... )
>>>
>>> # Add navigation items with custom colors
>>> builder.add_navigation_item(
...     view=products_view,
...     background_color="#F0F0F0",
...     active_color="#007BFF",
...     font_color="#333333"
... )
>>> builder.add_navigation_item(view=orders_view)

add_navigation_group(name, auto_collapse=True, hidden=False)

Create and register a navigation group - an expandable tab containing multiple related views.

Parameters:

• name (str) – The label displayed for the group in the navigation panel. Must be unique across all navigation items.

• auto_collapse (bool) – If True (default), the group collapses automatically when the user navigates away to a different group or view.

• hidden (bool) – Whether the entire group should initially be hidden in the UI.

Return type:

GroupViewNavItem

Returns:

GroupViewNavItem

A navigation group builder that can be used to add multiple views and configure visibility conditions.

Example

>>> reports_group = builder.add_navigation_group(name="Reports")
>>> reports_group.add_view(sales_report)

get_views()

Retrieve the list of all registered view builders.

This method returns a list of all view builder instances that have been added to this UiBuilder through the various add_*_view() factory methods. The views are returned in the order they were added, except that the default view (if set) will be first after build() is called.

Returns:

A list of all view builder instances registered with this UiBuilder. This includes table views, chart views, form views, and all other view types that have been added.

Return type:

list[BaseView]

Example

>>> builder = UiBuilder()
>>> table_view = builder.add_table_view(products_table)
>>> chart_view = builder.add_chart_view(...)
>>>
>>> # Get all views
>>> all_views = builder.get_views()
>>> print(f"Total views: {len(all_views)}")  # Output: Total views: 2
>>>
>>> # Iterate through views
>>> for view in builder.get_views():
...     print(view.display_name)

add_modal(view, height='auto', width='auto', title=None)

Creates and registers a new modal dialog associated with the given view.

Parameters:

• view (BaseView) – The BaseView to be displayed inside the modal.

• height (str) – A CSS height value for the modal. Defaults to “auto”.

• width (str) – A CSS width value for the modal. Defaults to “auto”.

• title (str | ContextVariable | None) – Optional static title text for the modal dialog.

Returns:

The configured modal builder instance.

Return type:

Modal

Example

>>> # Create a form view to display in a modal
>>> edit_form = builder.add_form_view(
...     display_name="Edit Customer",
...     table=customers_table
... )
>>>
>>> # Create modal with custom size
>>> modal = builder.add_modal(
...     view=edit_form,
...     height="600px",
...     width="800px",
...     title="Customer Details"
... )
>>>
>>> # Use context variable for dynamic title
>>> title_var = builder.add_context_variable("modal_title", CVType.STRING)
>>> modal2 = builder.add_modal(
...     view=another_view,
...     title=title_var
... )

set_menu_configurations(hide_optimisation=False, hide_import=False, hide_bulk_import=False, hide_import_into_sheets=False)

Configure the visibility of menu actions available within the view.

Parameters:

• hide_optimisation (bool) – If True, hides the optimisation-related actions from the menu. Defaults to False so optimisation features are available unless explicitly disabled.

• hide_import (bool) – If True, hides the standard data import menu options. Defaults to False.

• hide_bulk_import (bool) – If True, hides bulk-import functionality in the menu. Defaults to False.

• hide_import_into_sheets (bool) – If True, hides the option to import data directly into sheets. Defaults to False.

Return type:

MenuConfigurations

Returns:

MenuConfigurations

The configuration object created. This allows callers to chain further customisation on the returned configuration instance if required.

Example

>>> # Hide all import-related menu options
>>> builder.set_menu_configurations(
...     hide_import=True,
...     hide_bulk_import=True,
...     hide_import_into_sheets=True
... )
>>>
>>> # Hide only optimisation features
>>> builder.set_menu_configurations(
...     hide_optimisation=True
... )

add_filter(filter_name, source_table)

Creates and registers a filter view for this model.

Parameters:

• filter_name (str) – The unique identifier for the filter.

• source_table (Table) – The table from which the filter values are sourced.

Returns:

The newly created filter view builder.

Return type:

FilterComponent

Example

>>> # Create a filter for a products table
>>> products_table = Table("products")
>>> product_filter = builder.add_filter(
...     filter_name="product_filter",
...     source_table=products_table
... )
>>>
>>> # Add filter options
>>> product_filter.add_filter_option(
...     field=Field("category", DataType.STRING),
...     display_name="Category"
... )
>>> product_filter.add_filter_option(
...     field=Field("price", DataType.DECIMAL),
...     display_name="Price"
... )
>>>
>>> # Use the filter in a table view
>>> table_view = builder.add_table_view(
...     table=products_table,
...     use_filter=product_filter
... )

add_toggle_view(display_name, first_view, second_view, toggle_label)

Create a grid view that toggles between two child views via a slider.

A boolean context variable drives visibility: the first view is shown when the variable is False and the second when it is True. A labelled slider is rendered in the top-right corner to let the user switch between them.

Parameters:

• display_name (str) – Display label for the outer grid view.

• first_view (BaseView) – The view rendered when the toggle is off (default state).

• second_view (BaseView) – The view rendered when the toggle is on.

• toggle_label (str) – Bold text label displayed next to the toggle slider.

Returns:

The outer grid view containing both child views and the toggle control.

Return type:

GridView

Example

>>> table_view = builder.add_table_view(table=my_table, display_name="Table")
>>> chart_view = builder.add_chart_view(
...     chart_title="Chart",
...     primary_series=series,
...     chart_type=ChartType.BAR,
...     table=my_table,
... )
>>> toggle_view = builder.add_toggle_view(
...     display_name="Results",
...     first_view=table_view,
...     second_view=chart_view,
...     toggle_label="Chart View",
... )

set_default_view(view)

Sets the default view for this model.

The default view is prioritised during the build process and will be ordered first among all views when the model definition is built.

Parameters:

view (BaseView) – The view instance to be marked as the default view.

Example

>>> # Create multiple views
>>> products_view = builder.add_table_view(
...     table=products_table,
...     display_name="Products"
... )
>>> orders_view = builder.add_table_view(
...     table=orders_table,
...     display_name="Orders"
... )
>>>
>>> # Set the products view as default
>>> builder.set_default_view(products_view)
>>>
>>> # When the UI loads, products_view will be displayed first

build()

Builds the final ui definition.

This method ensures views are correctly ordered (with the default view first) before delegating to the base build implementation.

Returns:

The fully built ui definition.

Return type:

dict

Example

>>> # Build a complete UI definition
>>> builder = UiBuilder()
>>>
>>> # Add views
>>> products_view = builder.add_table_view(
...     table=products_table,
...     display_name="Products"
... )
>>> sales_chart = builder.add_chart_view(
...     chart_title="Sales",
...     primary_series=series,
...     secondary_series=series2,
...     chart_type=ChartType.BAR,
...     table=sales_table
... )
>>>
>>> # Configure navigation
>>> builder.add_navigation_item(products_view)
>>> builder.add_navigation_item(sales_chart)
>>>
>>> # Set default view
>>> builder.set_default_view(products_view)
>>>
>>> # Build and get the final UI definition
>>> ui_definition = builder.build()
>>> # ui_definition is a dict that can be serialized and used to render the UI

write_to_file(model_directory)

Serialises the UI definition into ui-definition.json under the given directory.

Parameters:

model_directory (str | PathLike[str]) – Directory to write the UI definition into. Created if missing.

Return type:

None