Skip to main content

Events and Callbacks

FDC exposes callbacks at several layers. The most maintainable applications place behavior at the layer that owns the state transition.

DataSet lifecycle events​

Use dataset events for data lifecycle policy:

  • open and close lifecycle;
  • edit, insert, post, delete, and cancel lifecycle;
  • state changes;
  • validation and dataset errors;
  • background work start, completion, and failure;
  • field changes;
  • record navigation.

For example:

final customers = FdcDataSet(
  fields: fields,
  beforePost: (dataSet) {
    final creditLimit = dataSet.fieldByName('credit_limit').value;
    if (creditLimit == null) {
      throw FdcDataSetAbortException('Credit limit is required.');
    }
  },
  afterPost: (dataSet) {
    auditCustomerChange(dataSet);
  },
  onError: (dataSet, errors, cause) {
    reportDataErrors(errors, cause: cause);
  },
);

Use a dataset lifecycle callback when the rule must apply regardless of whether the change came from a grid, a standalone editor, or application code.

Grid callbacks​

Use grid callbacks for interaction and presentation behavior:

  • cell changes;
  • row, column, and cell enter/exit notifications;
  • edit permission gates;
  • column value-changing/value-changed hooks;
  • lookup interactions;
  • context menus.

See Grid Events and Callbacks for grid-specific examples.

Editor callbacks​

Standalone editors participate in the same dataset edit buffer. Use editor callbacks for UI-local behavior, while field and record validation stays at the field or dataset layer.

Lookup callbacks can return a value or a multi-field write set. See Lookup.

Adapter callbacks and transport hooks​

Adapter and transport callbacks belong to persistence boundaries. Examples include JSON/REST request transport, metadata builders, and custom adapter load/apply implementations.

Do not use a grid callback to implement adapter behavior, or an adapter hook to implement visual interaction policy.

Abort versus error​

Throw FdcDataSetAbortException from supported veto points when an operation should be intentionally stopped. Use normal exceptions for actual failures. Silent aborts are available when the operation should stop without raising the normal dataset error event.