FormsManager

Overview

FormsManager is the BeepDM form-orchestration runtime in the TheTechIdea.Beep.Editor.UOWManager namespace. It coordinates block registration, current-block state, navigation, query-mode and CRUD-mode transitions, master/detail synchronization, triggers, LOV application, savepoints, locks, audit capture, security enforcement, paging, cache control, and multi-form communication.

The current public runtime surface is documented here under the FormsManager name.

Runtime Ownership

Signature Snapshot

public partial class FormsManager
{
    public IDMEEditor DMEEditor { get; }
    public string CurrentFormName { get; set; }
    public string CurrentBlockName { get; set; }
    public IReadOnlyDictionary<string, DataBlockInfo> Blocks { get; }
    public bool IsDirty { get; }
    public int BlockCount { get; }

    public IDirtyStateManager DirtyStateManager { get; }
    public IPerformanceManager PerformanceManager { get; }
    public ISystemVariablesManager SystemVariables { get; }
    public IValidationManager Validation { get; }
    public ILOVManager LOV { get; }
    public IItemPropertyManager ItemProperties { get; }
    public ITriggerManager Triggers { get; }
    public ISavepointManager Savepoints { get; }
    public ILockManager Locking { get; }
    public IQueryBuilderManager QueryBuilder { get; }
    public IMessageQueueManager Messages { get; }
    public IBlockPropertyManager BlockProperties { get; }
    public ISequenceProvider Sequences { get; }
    public ITimerManager Timers { get; }
    public IFormRegistry Registry { get; }
    public IFormMessageBus MessageBus { get; }
    public ISharedBlockManager SharedBlocks { get; }
    public IAuditManager AuditManager { get; }
    public ISecurityManager Security { get; }
    public IPagingManager Paging { get; }

    public FormsManager(IDMEEditor dmeEditor, ...);

    public void RegisterBlock<T>(...);
    public DataBlockInfo GetBlock<T>(string blockName);
    public Task<bool> InsertRecordAsync<T>(string blockName, T record = default);
    public Task<LOVResult> ShowLOVAsync(...);
    public Task<bool> OpenFormAsync(string formName);
    public Task<IErrorsInfo> CommitFormAsync();
    public Task<IErrorsInfo> RollbackFormAsync();
    public Task<IErrorsInfo> EnterQueryModeAsync(string blockName);
    public Task<IErrorsInfo> ExecuteQueryAndEnterCrudModeAsync(string blockName, List<AppFilter> filters = null);
    public Task<bool> FirstRecordAsync(string blockName);
    public Task<bool> NextRecordAsync(string blockName);
    public Task<bool> PreviousRecordAsync(string blockName);
    public Task<bool> LastRecordAsync(string blockName);
    public Task<bool> NavigateToRecordAsync(string blockName, int recordIndex);
}

Partial-Class Topology

Helper Manager Surface

FormsManager exposes most subsystem capabilities through helper properties so callers can use low-level behavior without re-implementing orchestration. In normal application code, start with FormsManager entry points and reach for helper managers only when you need custom registration or inspection behavior.

Form Lifecycle and Mode Transitions

The normal lifecycle is open form, register blocks, enter query mode when needed, execute a query, navigate, edit, and commit or rollback through a single form-level orchestration point.

var manager = new FormsManager(dmeEditor)
{
    CurrentFormName = "CUSTOMER_ORDERS"
};

await manager.OpenFormAsync("CUSTOMER_ORDERS");
await manager.EnterQueryModeAsync("CUSTOMERS");

var filters = new List<AppFilter>
{
    new AppFilter { FieldName = "Country", Operator = "=", FilterValue = "USA" }
};

await manager.ExecuteQueryAndEnterCrudModeAsync("CUSTOMERS", filters);
await manager.FirstRecordAsync("CUSTOMERS");
await manager.NextRecordAsync("CUSTOMERS");

var result = await manager.CommitFormAsync();
if (result.Flag != Errors.Ok)
{
    await manager.RollbackFormAsync();
}

Block Registration and CRUD Flow

Prefer typed registration so FormsManager can create records with the correct CLR type, use typed accessors, and keep new-record flows compatible with validation, LOVs, audit, and key generation.

manager.RegisterBlock<CustomerDto>(
    blockName: "CUSTOMERS",
    unitOfWork: customerUow,
    entityStructure: customerEntity,
    dataSourceName: "Northwind",
    isMasterBlock: true);

manager.RegisterBlock<OrderDto>(
    blockName: "ORDERS",
    unitOfWork: orderUow,
    entityStructure: orderEntity,
    dataSourceName: "Northwind");

manager.CreateMasterDetailRelation(
    masterBlockName: "CUSTOMERS",
    detailBlockName: "ORDERS",
    masterKeyField: "CustomerId",
    detailForeignKeyField: "CustomerId");

var orderBlock = manager.GetBlock<OrderDto>("ORDERS");
await manager.InsertRecordAsync<OrderDto>("ORDERS", new OrderDto { Status = "Draft" });

await manager.DuplicateCurrentRecordAsync("ORDERS");

using var jsonStream = new MemoryStream();
await manager.ExportBlockToJsonAsync("ORDERS", jsonStream);

jsonStream.Position = 0;
await manager.ImportBlockFromJsonAsync("ORDERS_ARCHIVE", jsonStream, clearFirst: true);

Key Generation and Record Creation

Key handling is part of the new-record and insert pipeline. FormsManager coordinates the strategy, but the datasource-backed UnitOfWork remains the authority for persisted identities and real sequence refresh.

1. Preserve explicit keys supplied by caller, default factory, or trigger.
2. Leave datasource-managed identity keys unset until insert or commit refresh completes.
3. Prefer datasource or UnitOfWork sequence generation before the in-memory FormsManager sequence provider.
4. Use FormsManager sequences for deterministic tests or non-database-backed flows.
5. Handle composite keys field by field.
6. Do not allocate keys during query, paging, navigation, or cache prefetch.

await manager.InsertRecordAsync<CustomerDto>("CUSTOMERS", new CustomerDto
{
    CustomerId = "ALFKI",
    CompanyName = "Alfreds Futterkiste"
});

manager.SetItemDefault("ORDERS", "Status", () => "Draft");

var nextNumber = manager.GetNextSequence("ORDER_SEQ");

await manager.InsertRecordAsync<OrderDto>("ORDERS", new OrderDto
{
    OrderNumber = nextNumber,
    CustomerId = "ALFKI"
});

await manager.InsertRecordAsync<OrderLineDto>("ORDER_LINES", new OrderLineDto
{
    OrderId = existingOrderId,
    ProductId = 12,
    Quantity = 3
    // Leave identity key unset. The datasource refresh path populates it after insert or commit.
});

manager.SetItemDefault("ORDERS", "CreatedAt", () => DateTime.UtcNow);
manager.SetItemDefault("ORDERS", "CreatedBy", () => Environment.UserName);

await manager.InsertRecordAsync<OrderDto>("ORDERS", new OrderDto());

Built-in Runtime Operations

manager.SetDefaultWhere("ORDERS", "IsDeleted = 0");
manager.SetOrderBy("ORDERS", "OrderDate desc");
manager.SetInsertAllowed("ORDERS", true);

var timer = manager.CreateTimer("REFRESH_ORDERS", TimeSpan.FromSeconds(30), repeating: true);
var confirmed = await manager.ConfirmAsync("Commit", "Save all pending changes?");

if (confirmed)
{
    await manager.CommitFormAsync();
}

Multi-Form, Globals, and Messaging

FormsManager implements modal and modeless form flows through the form registry, call stack, globals, parameter handoff, message bus, and shared block manager.

manager.SetGlobalVariable("ACTIVE_CUSTOMER_ID", "ALFKI");

manager.SubscribeToMessage("CustomerChanged", message =>
{
    Console.WriteLine($"Received {message.MessageType} from {message.SenderForm}");
});

manager.PostMessage("ORDER_FORM", "CustomerChanged", "ALFKI");

await manager.CallFormAsync(
    "ORDER_FORM",
    new Dictionary<string, object> { ["CustomerId"] = "ALFKI" },
    FormCallMode.Modal);

Triggers, Validation, and LOVs

Trigger system

FormsManager wires trigger behavior across insert, update, delete, query, commit, navigation, key events, and timer expiration. Trigger chaining, dependency tracking, and execution logging are part of the runtime.

manager.RegisterKeyTrigger(
    KeyTriggerType.KEY_COMMIT,
    "ORDERS",
    args =>
    {
        Console.WriteLine("Commit key trigger fired");
        return Task.CompletedTask;
    });

Validation

Validation rules can run at item, record, block, form, and cross-block scope. FormsManager integrates validation into field changes, query transitions, navigation, and commit flows.

manager.Validation.RegisterItemRule("ORDERS", "Quantity", value =>
{
    return value is int quantity && quantity > 0
        ? ValidationResult.Success()
        : ValidationResult.Failure("Quantity must be greater than zero.");
});

LOV orchestration

Register LOV definitions through the LOV helper, then apply a selected row through ShowLOVAsync. That keeps data loading, cache reuse, and related-field population inside the FormsManager orchestration path.

var customerLov = LOVDefinition
    .CreateLookup("CUSTOMER_LOV", "Northwind", "Customers", "CustomerId", "CompanyName")
    .MapField("CompanyName", "CustomerName");

manager.LOV.RegisterLOV("ORDERS", "CustomerId", customerLov);

var lovResult = await manager.ShowLOVAsync("ORDERS", "CustomerId", searchText: "alf");
var selected = lovResult.Records.FirstOrDefault();

if (selected != null)
{
    await manager.ShowLOVAsync("ORDERS", "CustomerId", selectedRecord: selected);
}

Audit, Security, and Performance

manager.SetAuditUser("fahad");
manager.ConfigureAudit(config =>
{
    config.Enabled = true;
    config.AuditedBlocks.Add("ORDERS");
});

manager.SetSecurityContext(new SecurityContext
{
    UserName = "fahad",
    Roles = new List<SecurityRole>
    {
        new SecurityRole
        {
            Name = "OrderClerk",
            Permissions = SecurityPermission.Query | SecurityPermission.Update
        }
    }
});

manager.SetBlockPageSize("ORDERS", 50);
manager.SetTotalRecordCount("ORDERS", 1200);
manager.SetFetchAheadDepth("ORDERS", 2);

var page = await manager.LoadPageAsync("ORDERS", 3);
var auditEntries = manager.GetAuditLog("ORDERS");
var cacheStats = manager.GetCacheStats();

Coverage Snapshot

Known Boundaries and Hardening Areas

Related Documentation

• UnitOfWork Pattern
• UnitOfWork Deep Dive
• Helpers Runtime Reference
• DMEEditor