Model Event

Event system for defining user interactions and application behaviour.

This module provides the ModelEvent class, which represents sequences of actions that execute in response to user interactions (clicks, changes, etc.) or other triggers. Events enable complex workflows including data manipulation, navigation, modal dialogs, transactions, and more.

Main Components

Core Classes:

  • ModelEvent: Container for a sequence of actions to execute

  • EditorEvent: Wrapper connecting editor interactions to model events

Action Categories:

The ModelEvent class supports the following action types organised by purpose:

UI Navigation:

  • add_show_modal_action(): Display modal dialogs

  • add_close_modal_action(): Close modal dialogs

  • add_switch_view_action(): Navigate to different views

Data Operations:

  • add_set_table_value_action(): Set field values in table rows

  • add_set_name_value_action(): Update Parameters or Calculations

  • add_copy_values_action(): Copy values between rows

  • add_clear_values_action(): Clear field values in rows

Row Management:

  • add_insert_row_action(): Insert new blank rows

  • add_duplicate_row_action(): Duplicate existing rows

  • add_delete_row_action(): Delete rows from tables

State Management:

  • add_set_context_action(): Update context variable values

Transaction Control:

  • add_begin_transaction(): Start data transaction

  • add_commit_transaction(): Save transaction changes

  • add_rollback_transaction(): Discard transaction changes

External Operations:

  • add_run_report_action(): Execute reports

  • add_run_data_source_action(): Refresh data sources

Navigation:

  • add_model_editor_navigate_action(): Open the Daitum model editor

Event Execution Model

Action Sequences:

ModelEvent contains an ordered list of actions that execute sequentially. Actions are executed in the order they were added to the event.

Conditional Execution:

Every action supports optional conditional execution via the condition parameter. When provided, the action only executes if the condition context variable evaluates to true.

Transaction Safety:

Use transaction actions to group data operations into atomic units:

  • BEGIN starts a transaction

  • COMMIT saves all changes

  • ROLLBACK discards all changes

Transactions ensure data consistency when multiple operations must succeed or fail together.

Row Selection Modes

Row operations support multiple selection strategies via RowSelectionMode:

  • INDEX: Select row by numeric position

  • KEY: Select row by unique key field value

When using KEY mode, provide a key_field to identify the matching field.

Insert and Delete Modes

InsertMode (row insertion):

  • END_OF_TABLE: Insert at table end

  • START_OF_TABLE: Insert at table beginning

  • AFTER_TARGET: Insert after reference row

  • BEFORE_TARGET: Insert before reference row

DeleteMode (row deletion):

  • TARGET: Delete starting at target row

  • AFTER_TARGET: Delete starting after target row

  • BEFORE_TARGET: Delete starting before target row

Value Sources

Many actions accept values from multiple sources:

  • Value objects: Constant values (IntegerValue, StringValue, etc.)

  • ContextVariable: Dynamic values from context

  • int/str literals: Direct constant values for row indices

The action automatically determines the appropriate source type.

Examples

Simple button click event:

from daitum_ui.model_event import ModelEvent

# Create event that switches views
on_click_event = ModelEvent()
on_click_event.add_switch_view_action(view_id="detail_view")

Opening a modal dialog:

# Event to show edit modal with transaction
edit_event = ModelEvent()
edit_event.add_show_modal_action(
    modal_id="edit_form_modal",
    transactional=True  # Automatically begins transaction
)

Inserting a new row:

from daitum_ui._events import InsertMode

# Event to insert row at end of table
insert_event = ModelEvent()
insert_event.add_insert_row_action(
    target_table=customers_table,
    insertion_point=InsertMode.END_OF_TABLE,
    new_index=new_row_context_var  # Store new row index
)

Deleting a row:

from daitum_ui._events import RowSelectionMode

# Event to delete selected row
delete_event = ModelEvent()
delete_event.add_delete_row_action(
    target_table=products_table,
    row_count=1,
    select_mode=RowSelectionMode.INDEX,
    row=selected_row_context_var
)

Duplicating a row:

from daitum_ui._events import RowSelectionMode, InsertMode

# Event to duplicate current row
duplicate_event = ModelEvent()
duplicate_event.add_duplicate_row_action(
    target_table=orders_table,
    row=current_row_context_var,
    select_mode=RowSelectionMode.INDEX,
    insertion_point=InsertMode.AFTER_TARGET
)

Setting table field values:

from daitum_ui.data import StringValue

# Event to update customer name
update_name_event = ModelEvent()
update_name_event.add_set_table_value_action(
    value_source=StringValue("John Doe"),
    target_table=customers_table,
    target_field=customers_table.name_field,
    target_row=selected_row_context_var
)

Setting values from context variables:

# Copy value from input context variable to table
save_input_event = ModelEvent()
save_input_event.add_set_table_value_action(
    value_source=user_input_context_var,  # ContextVariable
    target_table=settings_table,
    target_field=settings_table.value_field,
    target_row=0
)

Updating context variables:

from daitum_ui.data import IntegerValue
from daitum_ui._events import ValueType

# Event to set selected row ID
select_row_event = ModelEvent()
select_row_event.add_set_context_action(
    variable=selected_row_id_context_var,
    value=IntegerValue(42),
    value_type=ValueType.CONSTANT
)

Copying values between rows:

# Event to copy fields from source to target row
copy_event = ModelEvent()
copy_event.add_copy_values_action(
    source=source_row_context_var,
    target=target_row_context_var,
    table=products_table,
    fields=[
        products_table.name_field,
        products_table.price_field,
        products_table.category_field
    ]
)

Clearing field values:

# Event to clear fields in a row
clear_event = ModelEvent()
clear_event.add_clear_values_action(
    source_row=current_row_context_var,
    table=orders_table,
    fields=[
        orders_table.notes_field,
        orders_table.discount_field
    ]
)

Transaction management:

# Event with explicit transaction control
save_event = ModelEvent()
save_event.add_begin_transaction()
save_event.add_set_table_value_action(...)
save_event.add_set_table_value_action(...)
save_event.add_commit_transaction()

# Event to cancel changes
cancel_event = ModelEvent()
cancel_event.add_rollback_transaction()
cancel_event.add_close_modal_action()

Conditional execution:

# Only execute action if condition is true
conditional_event = ModelEvent()
conditional_event.add_switch_view_action(
    view_id="admin_panel",
    condition=is_admin_context_var  # Only if user is admin
)

Complex multi-step workflow:

# Save form and navigate workflow
save_and_navigate_event = ModelEvent()

# 1. Begin transaction
save_and_navigate_event.add_begin_transaction()

# 2. Save form values
save_and_navigate_event.add_set_table_value_action(
    value_source=name_input_context_var,
    target_table=customers_table,
    target_field=customers_table.name_field,
    target_row=current_customer_context_var
)
save_and_navigate_event.add_set_table_value_action(
    value_source=email_input_context_var,
    target_table=customers_table,
    target_field=customers_table.email_field,
    target_row=current_customer_context_var
)

# 3. Commit transaction
save_and_navigate_event.add_commit_transaction()

# 4. Close modal
save_and_navigate_event.add_close_modal_action()

# 5. Refresh data
save_and_navigate_event.add_run_data_source_action("customer_list_source")

# 6. Navigate to list view
save_and_navigate_event.add_switch_view_action("customer_list_view")

Running reports:

# Event to generate and download report
report_event = ModelEvent()
report_event.add_run_report_action(report_name="monthly_sales_report")

Refreshing data sources:

# Event to reload data from server
refresh_event = ModelEvent()
refresh_event.add_run_data_source_action(data_source_name="product_inventory")

Editor events for UI interactions:

from daitum_ui.model_event import EditorEvent
from daitum_ui._events import EditorEventType

# Button click event
button_click = EditorEvent(
    type=EditorEventType.ON_CLICK,
    event=save_and_navigate_event
)

# Value change event
value_change = EditorEvent(
    type=EditorEventType.ON_CHANGE,
    event=update_calculation_event
)

Setting named values (Parameters/Calculations):

from daitum_ui.data import DecimalValue

# Update parameter value
update_param_event = ModelEvent()
update_param_event.add_set_name_value_action(
    value_source=DecimalValue(0.15),
    name_value_target=tax_rate_parameter
)

Row operations with key-based selection:

from daitum_ui._events import RowSelectionMode

# Delete row by unique key instead of index
delete_by_key_event = ModelEvent()
delete_by_key_event.add_delete_row_action(
    target_table=users_table,
    row_count=1,
    select_mode=RowSelectionMode.KEY,
    row=user_id_context_var,
    key_field=users_table.user_id_field
)

Value matching for copy operations:

# Copy values using field matching instead of index
copy_by_value_event = ModelEvent()
copy_by_value_event.add_copy_values_action(
    source=source_product_id_context_var,
    target=target_product_id_context_var,
    table=products_table,
    fields=[products_table.price_field],
    match_field=products_table.product_id_field  # Match by ID
)

Navigating to the model editor:

# Open a specific model in a new tab
navigate_event = ModelEvent()
navigate_event.add_model_editor_navigate_action(
    model_id=model_id_field,
    scenario_id=scenario_id_field,
    open_new_tab=True,
)
class ModelEvent[source]

Bases: Buildable

Represents a model-level event composed of a sequence of actions.

actions

A list of actions (event argument instances) to be executed as part of the model event.

Type:

List[EventArgs]

__init__()[source]

Initializes an empty ModelEvent with no actions.

add_show_modal_action(modal_id, transactional=True, condition=None)[source]

Adds an action to show a modal dialog.

Parameters:

  • modal_id (str) – The modal object to display.

  • transactional (bool) – If True, begins a transaction after showing the modal. Defaults to True.

  • condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

add_close_modal_action(condition=None)[source]

Adds an action to close any currently open modal.

Parameters:

condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

add_run_report_action(report_name, condition=None)[source]

Adds an action to run a specified report.

Parameters:

  • report_name (str) – Name of the report to execute.

  • condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

add_switch_view_action(view_id, condition=None)[source]

Adds an action to change the currently active view.

Parameters:

  • view_id (str) – The view object to switch to.

  • condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

add_begin_transaction(condition=None)[source]

Adds an action to begin a transaction.

Parameters:

condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

add_rollback_transaction(condition=None)[source]

Adds an action to roll back the current transaction.

Parameters:

condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

add_commit_transaction(condition=None)[source]

Adds an action to commit the current transaction.

Parameters:

condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

add_set_context_action(variable, value, value_type=ValueType.CONSTANT, condition=None)[source]

Adds an action to set a context variable’s value.

Parameters:

  • variable (ContextVariable) – The context variable to update.

  • value (Value) – The value to assign to the context variable.

  • value_type (ValueType) – Indicates the source or interpretation of the value. Defaults to CONSTANT.

  • condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

add_copy_values_action(source, target, table, fields, condition=None)[source]

Adds an action to copy values from one row to another within the same table.

Parameters:

  • source (ContextVariable) – Context variable identifying the source row.

  • target (ContextVariable) – Context variable identifying the target row.

  • table (Table) – The table containing both source and target rows.

  • fields (list[Field]) – List of fields whose values will be copied from source to target.

  • condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

Returns:

The created action. Set action.match_field and

action.match_by_value directly for value-based row matching.

Return type:

CopyValuesArgs

add_clear_values_action(source_row, table, fields, match_field=None, condition=None)[source]

Adds an action to clear field values in a specific row of a table.

Parameters:

  • source_row (ContextVariable) – Context variable identifying the row whose values will be cleared.

  • table (Table) – The table containing the row to be modified.

  • fields (list[Field]) – List of fields whose values will be cleared in the specified row.

  • match_field (Field | None) – Field used for value-based row identification instead of index-based identification. If provided, the row is identified by comparing this field’s value.

  • condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

add_duplicate_row_action(target_table, row, select_mode, condition=None)[source]

Adds an action to duplicate a row in a table.

Parameters:

  • target_table (Table) – Table in which to duplicate a row.

  • row (ContextVariable) – Context variable holding the source row index or key.

  • select_mode (RowSelectionMode) – Determines how the source row is selected (by index, by key, etc.).

  • condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

Returns:

The created action. Set action.key_field,

action.insertion_point, action.new_index_context_variable_id, and action.append_table_to_new_variable directly for further configuration.

Return type:

DuplicateRowArgs

add_insert_row_action(target_table, select_mode=RowSelectionMode.INDEX, row=None, condition=None)[source]

Adds an action to insert a new blank row into a table.

Parameters:

  • target_table (Table) – Table to insert the new row into.

  • select_mode (RowSelectionMode) – Defines how the reference row is selected (by index, by key, etc.). Defaults to INDEX.

  • row (ContextVariable | None) – Context variable indicating the reference point for insertion. Not required when insertion_point is END_OF_TABLE or START_OF_TABLE.

  • condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

Returns:

The created action. Set action.key_field,

action.insertion_point, action.new_index_context_variable_id, and action.append_table_to_new_variable directly for further configuration.

Return type:

InsertRowArgs

add_delete_row_action(target_table, row_count, select_mode, row=None, condition=None)[source]

Adds an action to delete one or more rows from a table.

Parameters:

  • target_table (Table) – Table from which rows will be deleted.

  • row_count (int) – Number of consecutive rows to delete.

  • select_mode (RowSelectionMode) – Defines how the starting row is selected for deletion (by index, by key, etc.).

  • row (ContextVariable | None) – Context variable holding the row index or key identifying the deletion reference point.

  • condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

Returns:

The created action. Set action.key_field and

action.delete_point directly for further configuration.

Return type:

DeleteRowArgs

add_run_data_source_action(data_source_name, condition=None)[source]

Adds an action to run or refresh a data source.

Parameters:

  • data_source_name (str) – Name of the data source to execute or refresh.

  • condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

add_set_table_value_action(value_source, target_table, target_field, target_row, condition=None)[source]

Adds an action to set a value in a specific table field and row.

Parameters:

  • value_source (Value | ContextVariable) – The source of the value to set. Can be either a constant Value or a ContextVariable whose value will be used.

  • target_table (Table) – The table containing the field to be updated.

  • target_field (Field) – The field in the target table that will receive the new value. Must be a field that exists in the target_table.

  • target_row (int | ContextVariable) – Identifies the row to update.

  • condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

Raises:

ValueError – If target_field is not a field in target_table.

add_set_name_value_action(value_source, name_value_target, condition=None)[source]

Adds an action to set the value of a named value (Parameter or Calculation).

Parameters:

  • value_source (Value | ContextVariable) – The source of the value to set. Can be either a constant Value or a ContextVariable whose value will be used.

  • name_value_target (Parameter | Calculation) – The named value (Parameter or Calculation) that will receive the new value.

  • condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

add_model_editor_navigate_action(model_id, scenario_id=None, open_new_tab=False, condition=None)[source]

Adds an action that navigates to the Daitum model editor.

Both model_id and scenario_id are optional. When provided, they are resolved at runtime to identify the target model and scenario. Omitting them opens the editor without pre-selecting a model or scenario.

Parameters:

  • model_id (Field | Parameter | Calculation | ContextVariable) – Value identifying the model to open. Must resolve to an integer.

  • scenario_id (Field | Parameter | Calculation | ContextVariable | None) – Value identifying the scenario to open within the selected model. Must resolve to an integer.

  • open_new_tab (bool) – If True, the editor opens in a new browser tab. Defaults to False.

  • condition (ContextVariable | None) – Context variable controlling conditional execution of the action. If provided, the action only executes when the context variable evaluates to true.

class EditorEvent(type, event)[source]

Bases: Buildable

Represents an event triggered from the editor (e.g. user interaction), which encapsulates a model event.

type

The type of editor event that was triggered (ON_CLICK, ON_CHANGE).

Type:

EditorEventType

event

The model event containing the list of actions to be executed in response.

Type:

ModelEvent

type: EditorEventType
event: ModelEvent