Button Click Events

Button click events are the most common widget events. They trigger actions like saving data, opening forms, downloading files, or displaying messages.

Event Type

Event: onClick Triggered: When user clicks a button widget

Request Example

{
  "widgetName": "submitbtn",
  "widgetEvent": "onClick",
  "formData": {
    "customerName": "John Doe",
    "email": "john@example.com"
  },
  "formCode": "CUSTOMERFORM",
  "guid": "new"
}

Common Use Cases

Open Another Form (Modal or New Tab)

C# / .NET

if (widgetName == "OPENMODALWINBTN" && eventType == "ONCLICK")
{
    var feCommands = (List<object>)response["feCommand"];

    // Open another form in a modal window
    feCommands.Add(new
    {
        command = "OpenRecord",
        args = new
        {
            id = Guid.NewGuid().ToString(),
            pluginCode = "NONE",
            formCode = "DETAILSFORM",
            guid = "new",
            pGuid = (string)null,
            isFormEditorMode = false,
            originator = (object)null,
            parent = (object)null,
            folderData = (object)null,
            prefillData = new Dictionary<string, string>
            {
                { "parentId", formData.GetValueOrDefault("customerId", "").ToString() }
            }
        }
    });
}

PHP

if ($widgetName === 'OPENMODALWINBTN' && $eventType === 'ONCLICK') {
    // Open another form in a modal window
    $response['feCommand'][] = [
        'command' => 'OpenRecord',
        'args' => [
            'id' => uniqid('', true),
            'pluginCode' => 'NONE',
            'formCode' => 'DETAILSFORM',
            'guid' => 'new',
            'pGuid' => null,
            'isFormEditorMode' => false,
            'originator' => null,
            'parent' => null,
            'folderData' => null,
            'prefillData' => [
                'parentId' => $formData['customerId'] ?? ''
            ]
        ]
    ];
}

Save Form Data

C# / .NET

if (widgetName == "SAVEBTN" && eventType == "ONCLICK")
{
    var feCommands = (List<object>)response["feCommand"];

    // Validate form data
    if (string.IsNullOrEmpty(formData.GetValueOrDefault("customerName", "").ToString()))
    {
        feCommands.Add(new
        {
            command = "ShowMessage",
            args = new
            {
                type = "error",
                message = "Customer name is required"
            }
        });
        return Ok(response);
    }

    // Save to database
    var customer = new Customer
    {
        Id = Guid.Parse(requestBody.GetProperty("guid").GetString()),
        Name = formData["customerName"].ToString(),
        Email = formData["email"].ToString(),
        Phone = formData.GetValueOrDefault("phone", "").ToString()
    };

    if (requestBody.GetProperty("guid").GetString() == "new")
    {
        customer.Id = Guid.NewGuid();
        await _dbContext.Customers.AddAsync(customer);
    }
    else
    {
        _dbContext.Customers.Update(customer);
    }

    await _dbContext.SaveChangesAsync();

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

    // Close the form
    feCommands.Add(new
    {
        command = "CloseForm",
        args = new { }
    });
}

PHP

if ($widgetName === 'SAVEBTN' && $eventType === 'ONCLICK') {
    // Validate form data
    if (empty($formData['customerName'])) {
        $response['feCommand'][] = [
            'command' => 'ShowMessage',
            'args' => [
                'type' => 'error',
                'message' => 'Customer name is required'
            ]
        ];
        return response()->json($response);
    }

    // Save to database
    $guid = $requestData['guid'];

    if ($guid === 'new') {
        // Create new customer
        $customerId = DB::table('customers')->insertGetId([
            'name' => $formData['customerName'],
            'email' => $formData['email'],
            'phone' => $formData['phone'] ?? '',
            'created_at' => now(),
            'updated_at' => now()
        ]);
    } else {
        // Update existing customer
        DB::table('customers')
            ->where('id', $guid)
            ->update([
                'name' => $formData['customerName'],
                'email' => $formData['email'],
                'phone' => $formData['phone'] ?? '',
                'updated_at' => now()
            ]);
    }

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

    // Close the form
    $response['feCommand'][] = [
        'command' => 'CloseForm',
        'args' => []
    ];
}

Download File

C# / .NET

if (widgetName == "DOWNLOADBTN" && eventType == "ONCLICK")
{
    var feCommands = (List<object>)response["feCommand"];

    // Generate or retrieve file
    string customerId = formData.GetValueOrDefault("customerId", "").ToString();
    string filePath = await GenerateCustomerReport(customerId);

    // Trigger download
    feCommands.Add(new
    {
        command = "Download",
        args = new
        {
            fileName = $"customer-report-{customerId}.pdf",
            filePath = filePath
        }
    });

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

PHP

if ($widgetName === 'DOWNLOADBTN' && $eventType === 'ONCLICK') {
    // Generate or retrieve file
    $customerId = $formData['customerId'] ?? '';
    $filePath = $this->generateCustomerReport($customerId);

    // Trigger download
    $response['feCommand'][] = [
        'command' => 'Download',
        'args' => [
            'fileName' => "customer-report-{$customerId}.pdf",
            'filePath' => $filePath
        ]
    ];

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

Show/Hide Widgets

C# / .NET

if (widgetName == "HIDEWIDGETSBTN" && eventType == "ONCLICK")
{
    // Hide multiple widgets
    response["widgetsState"] = new
    {
        visibility = new Dictionary<string, bool>
        {
            { "phone", false },
            { "email", false },
            { "address", false }
        },
        readOnly = new Dictionary<string, bool>()
    };
}
else if (widgetName == "SHOWWIDGETSBTN" && eventType == "ONCLICK")
{
    // Show hidden widgets
    response["widgetsState"] = new
    {
        visibility = new Dictionary<string, bool>
        {
            { "phone", true },
            { "email", true },
            { "address", true }
        },
        readOnly = new Dictionary<string, bool>()
    };
}

PHP

if ($widgetName === 'HIDEWIDGETSBTN' && $eventType === 'ONCLICK') {
    // Hide multiple widgets
    $response['widgetsState'] = [
        'visibility' => [
            'phone' => false,
            'email' => false,
            'address' => false
        ],
        'readOnly' => []
    ];
}
elseif ($widgetName === 'SHOWWIDGETSBTN' && $eventType === 'ONCLICK') {
    // Show hidden widgets
    $response['widgetsState'] = [
        'visibility' => [
            'phone' => true,
            'email' => true,
            'address' => true
        ],
        'readOnly' => []
    ];
}

Make Fields Read-Only or Editable

C# / .NET

if (widgetName == "LOCKBTN" && eventType == "ONCLICK")
{
    // Make fields read-only
    response["widgetsState"] = new
    {
        visibility = new Dictionary<string, bool>(),
        readOnly = new Dictionary<string, bool>
        {
            { "customerName", true },
            { "email", true },
            { "phone", true }
        }
    };
}
else if (widgetName == "UNLOCKBTN" && eventType == "ONCLICK")
{
    // Make fields editable
    response["widgetsState"] = new
    {
        visibility = new Dictionary<string, bool>(),
        readOnly = new Dictionary<string, bool>
        {
            { "customerName", false },
            { "email", false },
            { "phone", false }
        }
    };
}

PHP

if ($widgetName === 'LOCKBTN' && $eventType === 'ONCLICK') {
    // Make fields read-only
    $response['widgetsState'] = [
        'visibility' => [],
        'readOnly' => [
            'customerName' => true,
            'email' => true,
            'phone' => true
        ]
    ];
}
elseif ($widgetName === 'UNLOCKBTN' && $eventType === 'ONCLICK') {
    // Make fields editable
    $response['widgetsState'] = [
        'visibility' => [],
        'readOnly' => [
            'customerName' => false,
            'email' => false,
            'phone' => false
        ]
    ];
}

Display Message

C# / .NET

if (widgetName == "DISPLAYMSGBTN" && eventType == "ONCLICK")
{
    var feCommands = (List<object>)response["feCommand"];

    // Display different types of messages
    feCommands.Add(new
    {
        command = "ShowMessage",
        args = new
        {
            type = "warning", // "success", "error", "warning", "info"
            message = "This is a warning from the backend!"
        }
    });
}

PHP

if ($widgetName === 'DISPLAYMSGBTN' && $eventType === 'ONCLICK') {
    // Display different types of messages
    $response['feCommand'][] = [
        'command' => 'ShowMessage',
        'args' => [
            'type' => 'warning', // 'success', 'error', 'warning', 'info'
            'message' => 'This is a warning from the backend!'
        ]
    ];
}

Prefill Form Fields

C# / .NET

if (widgetName == "LOADTEMPLATEBTN" && eventType == "ONCLICK")
{
    // Load template data and prefill form
    var template = await _dbContext.Templates
        .FirstOrDefaultAsync(t => t.Name == "Default Customer");

    if (template != null)
    {
        formData["customerName"] = template.CustomerName;
        formData["email"] = template.Email;
        formData["phone"] = template.Phone;
        formData["address"] = template.Address;
        formData["notes"] = template.Notes;
        response["formData"] = formData;

        var feCommands = (List<object>)response["feCommand"];
        feCommands.Add(new
        {
            command = "ShowMessage",
            args = new
            {
                type = "info",
                message = "Template loaded successfully"
            }
        });
    }
}

PHP

if ($widgetName === 'LOADTEMPLATEBTN' && $eventType === 'ONCLICK') {
    // Load template data and prefill form
    $template = DB::table('templates')
        ->where('name', 'Default Customer')
        ->first();

    if ($template) {
        $formData['customerName'] = $template->customer_name;
        $formData['email'] = $template->email;
        $formData['phone'] = $template->phone;
        $formData['address'] = $template->address;
        $formData['notes'] = $template->notes;
        $response['formData'] = $formData;

        $response['feCommand'][] = [
            'command' => 'ShowMessage',
            'args' => [
                'type' => 'info',
                'message' => 'Template loaded successfully'
            ]
        ];
    }
}

Populate Dropdown Options

C# / .NET

if (widgetName == "LOADOPTIONSBTN" && eventType == "ONCLICK")
{
    // Load dynamic dropdown options from database
    var statuses = await _dbContext.Statuses.ToListAsync();
    var categories = await _dbContext.Categories.ToListAsync();

    var statusOptions = statuses.ToDictionary(
        s => s.Id.ToString(),
        s => s.Name
    );

    var categoryOptions = categories.ToDictionary(
        c => c.Id.ToString(),
        c => c.Name
    );

    response["fieldAllowedValues"] = new Dictionary<string, object>
    {
        { "statusField", statusOptions },
        { "categoryField", categoryOptions }
    };

    var feCommands = (List<object>)response["feCommand"];
    feCommands.Add(new
    {
        command = "ShowMessage",
        args = new
        {
            type = "success",
            message = "Options loaded successfully"
        }
    });
}

PHP

if ($widgetName === 'LOADOPTIONSBTN' && $eventType === 'ONCLICK') {
    // Load dynamic dropdown options from database
    $statuses = DB::table('statuses')->get();
    $categories = DB::table('categories')->get();

    $statusOptions = [];
    foreach ($statuses as $status) {
        $statusOptions[$status->id] = $status->name;
    }

    $categoryOptions = [];
    foreach ($categories as $category) {
        $categoryOptions[$category->id] = $category->name;
    }

    $response['fieldAllowedValues'] = [
        'statusField' => $statusOptions,
        'categoryField' => $categoryOptions
    ];

    $response['feCommand'][] = [
        'command' => 'ShowMessage',
        'args' => [
            'type' => 'success',
            'message' => 'Options loaded successfully'
        ]
    ];
}

Best Practices

1. Validate input - Always validate form data before processing
2. Provide feedback - Use ShowMessage to inform users of success/errors
3. Handle errors gracefully - Catch exceptions and return user-friendly messages
4. Use transactions - For database operations that modify multiple tables
5. Log actions - Keep audit logs of important operations

Next Steps

• Field Events - Handle field value changes
• Datatable Events - Handle table interactions
• Frontend Commands - Learn all available commands