RunEvent Handler Overview

The RunEvent handler is the primary backend endpoint that processes all form events and controls form behavior dynamically from the server.

What is RunEvent?

runEvent is the main communication point between your frontend and backend that:

• Receives events from form widgets (buttons, fields, tables, etc.)
• Processes business logic based on the event
• Returns instructions (actions) for the frontend to execute
• Controls form behavior dynamically from the server

Every time a user interacts with a form widget that has event handlers enabled, your runEvent endpoint is called.

Asynchronous Form Rendering

When a form is rendering, different components run their event handlers asynchronously. This means:

• Multiple widgets (tables, dropdowns, etc.) can trigger runEvent calls simultaneously
• All these requests are made to the same runEvent controller endpoint
• Your backend must handle concurrent requests from the same form
• Events like onTableLoadData, onLoad, and field initializations may overlap

Example: If a form has 3 datatable widgets, all 3 will call runEvent with onTableLoadData events in parallel when the form loads.

Quick Start

Here's a minimal runEvent implementation:

C# / .NET

Controllers/FormsPublicController.cs

[HttpPost("runevent")]
[AllowAnonymous]
public async Task<IActionResult> RunEvent([FromBody] JsonElement requestBody)
{
    // Parse request
    var widgetName = requestBody.GetProperty("widgetName").GetString()?.ToUpper();
    var eventType = requestBody.GetProperty("widgetEvent").GetString()?.ToUpper();
    var formData = JsonSerializer.Deserialize<Dictionary<string, object>>(
        requestBody.GetProperty("formData").GetRawText()
    );

    Console.WriteLine($"Widget: {widgetName}, Event: {eventType}");

    // Initialize response
    var response = new Dictionary<string, object>
    {
        { "formData", formData },
        { "widgetData", new List<object>() },
        { "widgetsState", null },
        { "fieldAllowedValues", new Dictionary<string, object>() },
        { "feCommand", new List<object>() }
    };

    var feCommands = (List<object>)response["feCommand"];

    // Handle events
    if (widgetName == "SUBMITBTN" && eventType == "ONCLICK")
    {
        // Save form data to database
        await SaveFormData(formData);

        // Show success message
        feCommands.Add(new
        {
            command = "ShowMessage",
            args = new { type = "success", message = "Form saved successfully!" }
        });
    }

    return Ok(response);
}

PHP

controllers/FormsPublicController.php

<?php

public function runEvent(Request $request) {
    // Get request data
    $requestData = $request->json()->all();
    $widgetName = strtoupper($requestData['widgetName'] ?? '');
    $eventType = strtoupper($requestData['widgetEvent'] ?? '');
    $formData = $requestData['formData'] ?? [];

    error_log("Widget: $widgetName, Event: $eventType");

    // Initialize response
    $response = [
        'formData' => $formData,
        'widgetData' => [],
        'widgetsState' => null,
        'fieldAllowedValues' => [],
        'feCommand' => []
    ];

    // Handle events
    if ($widgetName === 'SUBMITBTN' && $eventType === 'ONCLICK') {
        // Save form data to database
        $this->saveFormData($formData);

        // Show success message
        $response['feCommand'][] = [
            'command' => 'ShowMessage',
            'args' => [
                'type' => 'success',
                'message' => 'Form saved successfully!'
            ]
        ];
    }

    return response()->json($response);
}

Event Types by Use Case

The runEvent handler processes different types of events:

Button Click Events

Handle button clicks to trigger actions like saving data, opening modals, or downloading files.

Common Events: onClick

Field Change Events

Handle field value changes to calculate dependent values, validate input, or load related data.

Common Events: onChange, onBlur, onFocus

Datatable Events

Handle table interactions like loading data, editing rows, batch operations, and file uploads.

Common Events: onTableLoadData, onTableRunActionEvent, onTableEditRunActionEvent, onTableRunBatchActionEvent

Form Lifecycle Events

Handle form initialization, saving, and closing to manage data flow.

Common Events: onLoad, onSave, onClose

File Upload Events

Handle file uploads through form widgets or datatable upload buttons.

Common Events: onFileUpload, onFileUploadCreateDocumentEvent

Response Structure

Your runEvent endpoint must return a plain dictionary/object. Learn more in Basic Concepts.

Frontend Commands

Control the frontend by returning commands in the feCommand array. See all Available Commands.

Event Reference

📋 Complete Event Reference - Full list of all available event types with constants for C# and PHP

Next Steps

1. Basic Concepts - Understand the response structure
2. Event Reference - See all available event types with constants
3. Button Events - Start with simple button click handlers
4. Datatable Events - Handle complex table interactions
5. Frontend Commands - Learn all available commands