Button Events

Events fired by button widgets. All events on this page trigger FormHostProvider.runFormEvent.

The payload structure is identical across all button events — only widgetEvent differs.

Button Types

Type	widgetEvent value	Description
Save	onSave	Built-in save action
Cancel	onCancel	Built-in cancel action
Print	onPrint	Built-in print action
Click	onClick	Generic click handler
Custom	developer-defined	Calls a specific backend method by name

note

widgetContext is transmitted as a JSON-encoded string on the wire. The values shown below are the deserialized structure.

---

onClick

Fired when the user clicks a button.

{
  "pluginCode":   "construct",
  "formCode":     "documents",
  "guid":         "550e8400-e29b-41d4-a716-446655440000",
  "projectGuid":  "38I9rEPw1BmxP75XcxgzD5WGOk1",
  "pGuid":        "38I9rEPw1BmxP75XcxgzD5WGOk1",
  "formData":     { "name": "Project Alpha", "status": "active" },
  "widgetsState": null,
  "widgetName":   "SAVEBTN",
  "widgetValue":  null,
  "widgetEvent":  "onClick",
  "widgetContext": {
    "referer":        "/forms/documents/550e8400",
    "parentWidgetId": null,
    "hasParentForm":  false,
    "originator": {
      "widgetName": null,
      "params": {
        "pluginCode": "construct",
        "formCode":   "documents",
        "guid":       "550e8400-e29b-41d4-a716-446655440000",
        "pGuid":      "38I9rEPw1BmxP75XcxgzD5WGOk1"
      }
    },
    "parent": {
      "widgetName": null,
      "params": {
        "pluginCode": "construct",
        "formCode":   "documents",
        "guid":       "550e8400-e29b-41d4-a716-446655440000",
        "pGuid":      "38I9rEPw1BmxP75XcxgzD5WGOk1"
      }
    }
  }
}

---

onCancel

Fired when the user clicks the Cancel button.

{
  "pluginCode":   "construct",
  "formCode":     "documents",
  "guid":         "550e8400-e29b-41d4-a716-446655440000",
  "projectGuid":  "38I9rEPw1BmxP75XcxgzD5WGOk1",
  "pGuid":        "38I9rEPw1BmxP75XcxgzD5WGOk1",
  "formData":     { "name": "Project Alpha", "status": "active" },
  "widgetsState": null,
  "widgetName":   "CANCELBTN",
  "widgetValue":  null,
  "widgetEvent":  "onCancel",
  "widgetContext": {
    "referer":        "/forms/documents/550e8400",
    "parentWidgetId": null,
    "hasParentForm":  false,
    "originator": {
      "widgetName": null,
      "params": {
        "pluginCode": "construct",
        "formCode":   "documents",
        "guid":       "550e8400-e29b-41d4-a716-446655440000",
        "pGuid":      "38I9rEPw1BmxP75XcxgzD5WGOk1"
      }
    },
    "parent": {
      "widgetName": null,
      "params": {
        "pluginCode": "construct",
        "formCode":   "documents",
        "guid":       "550e8400-e29b-41d4-a716-446655440000",
        "pGuid":      "38I9rEPw1BmxP75XcxgzD5WGOk1"
      }
    }
  }
}

---

onPrint

Fired when the user clicks the Print button.

{
  "pluginCode":   "construct",
  "formCode":     "documents",
  "guid":         "550e8400-e29b-41d4-a716-446655440000",
  "projectGuid":  "38I9rEPw1BmxP75XcxgzD5WGOk1",
  "pGuid":        "38I9rEPw1BmxP75XcxgzD5WGOk1",
  "formData":     { "name": "Project Alpha", "status": "active" },
  "widgetsState": null,
  "widgetName":   "PRINTBTN",
  "widgetValue":  null,
  "widgetEvent":  "onPrint",
  "widgetContext": {
    "referer":        "/forms/documents/550e8400",
    "parentWidgetId": null,
    "hasParentForm":  false,
    "originator": {
      "widgetName": null,
      "params": {
        "pluginCode": "construct",
        "formCode":   "documents",
        "guid":       "550e8400-e29b-41d4-a716-446655440000",
        "pGuid":      "38I9rEPw1BmxP75XcxgzD5WGOk1"
      }
    },
    "parent": {
      "widgetName": null,
      "params": {
        "pluginCode": "construct",
        "formCode":   "documents",
        "guid":       "550e8400-e29b-41d4-a716-446655440000",
        "pGuid":      "38I9rEPw1BmxP75XcxgzD5WGOk1"
      }
    }
  }
}

---

onSave

Fired when the user clicks the Save button.

{
  "pluginCode":   "construct",
  "formCode":     "documents",
  "guid":         "550e8400-e29b-41d4-a716-446655440000",
  "projectGuid":  "38I9rEPw1BmxP75XcxgzD5WGOk1",
  "pGuid":        "38I9rEPw1BmxP75XcxgzD5WGOk1",
  "formData":     { "name": "Project Alpha", "status": "active" },
  "widgetsState": null,
  "widgetName":   "SAVEBTN",
  "widgetValue":  null,
  "widgetEvent":  "onSave",
  "widgetContext": {
    "referer":        "/forms/documents/550e8400",
    "parentWidgetId": null,
    "hasParentForm":  false,
    "originator": {
      "widgetName": null,
      "params": {
        "pluginCode": "construct",
        "formCode":   "documents",
        "guid":       "550e8400-e29b-41d4-a716-446655440000",
        "pGuid":      "38I9rEPw1BmxP75XcxgzD5WGOk1"
      }
    },
    "parent": {
      "widgetName": null,
      "params": {
        "pluginCode": "construct",
        "formCode":   "documents",
        "guid":       "550e8400-e29b-41d4-a716-446655440000",
        "pGuid":      "38I9rEPw1BmxP75XcxgzD5WGOk1"
      }
    }
  }
}

---

Custom Button

A Custom button lets you define your own handler name directly in the Form Builder. When clicked, it fires runFormEvent just like any other button — but widgetEvent is set to the method name you configured, allowing the backend to route it to a specific handler.

When to use: Any button action that doesn't map to a built-in event — calculating totals, triggering a workflow, loading related data, running a validation step, etc.

How to configure: In the Form Builder button properties, set the button type to Custom and enter the method name. That name becomes the value of widgetEvent in the request.

{
  "pluginCode":   "construct",
  "formCode":     "documents",
  "guid":         "550e8400-e29b-41d4-a716-446655440000",
  "projectGuid":  "38I9rEPw1BmxP75XcxgzD5WGOk1",
  "pGuid":        "38I9rEPw1BmxP75XcxgzD5WGOk1",
  "formData":     { "name": "Project Alpha", "status": "active" },
  "widgetsState": null,
  "widgetName":   "CALCULATEBTN",
  "widgetValue":  null,
  "widgetEvent":  "calculateTotals",
  "widgetContext": {
    "referer":        "/forms/documents/550e8400",
    "parentWidgetId": null,
    "hasParentForm":  false,
    "originator": {
      "widgetName": null,
      "params": {
        "pluginCode": "construct",
        "formCode":   "documents",
        "guid":       "550e8400-e29b-41d4-a716-446655440000",
        "pGuid":      "38I9rEPw1BmxP75XcxgzD5WGOk1"
      }
    },
    "parent": {
      "widgetName": null,
      "params": {
        "pluginCode": "construct",
        "formCode":   "documents",
        "guid":       "550e8400-e29b-41d4-a716-446655440000",
        "pGuid":      "38I9rEPw1BmxP75XcxgzD5WGOk1"
      }
    }
  }
}

The backend identifies the method using widgetEvent:

string widgetEvent = request.WidgetEvent; // "calculateTotals"

if (widgetEvent == "calculateTotals")
{
    // run your custom handler
}