Skip to main content

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)​

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

    // Open another form in a modal window
    feCommands.Add(new
    {
        command = "OpenModal",
        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() }
            }
        }
    });
}

Save Form Data​

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 { }
    });
}

Download File​

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"
        }
    });
}

Show/Hide Widgets​

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>()
    };
}

Make Fields Read-Only or Editable​

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 }
        }
    };
}

Display Message​

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!"
        }
    });
}

Prefill Form Fields​

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"
            }
        });
    }
}

Populate Dropdown Options​

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"
        }
    });
}

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​