Skip to main content

Lookup workflows

A lookup lets the user search for or resolve a value through application-defined UI and data access. FDC supplies the invocation context and applies the returned field values; your callback decides how selection and search work.

This keeps lookup flexible enough for dialogs, searchable lists, code-entry resolution, remote APIs, and custom selectors.

Lookup editor workflow
Loading FDC sample…
FdcTextEdit(
  dataSet: customers,
  fieldName: 'customer_code',
  label: 'Customer code',
  hint: 'Type a code or press …',
  onLookup: (context) async {
    if (context.lookupMode == FdcLookupMode.resolve) {
      final customer = await resolveCustomerCode(context.lookupText);
      if (customer == null) {
        throw Exception('Customer code not found.');
      }

      return FdcLookupResult({
        'customer_id': customer.id,
        'customer_code': customer.code,
        'company_name': customer.name,
        'city': customer.city,
      });
    }

    final customer = await showCustomerPicker(
      context.buildContext,
      initialText: context.lookupText,
    );
    if (customer == null) {
      return null;
    }

    return FdcLookupResult({
      'customer_id': customer.id,
      'customer_code': customer.code,
      'company_name': customer.name,
      'city': customer.city,
    });
  },
);

Basic editor lookup​

FdcTextEdit(
  dataSet: orders,
  fieldName: 'customer_code',
  label: 'Customer',
  onLookup: (context) async {
    final customer = await showCustomerPicker(
      context.buildContext,
      initialText: context.lookupText,
    );

    if (customer == null) {
      return null;
    }

    return FdcLookupResult({
      'customer_code': customer.code,
      'customer_name': customer.name,
      'city': customer.city,
    });
  },
)

A lookup result can update the initiating field and related fields as one logical write set.

Lookup context​

FdcLookupContext provides:

  • buildContext for presenting UI;
  • dataSet for the active dataset;
  • fieldName for the initiating field;
  • lookupText for the editor text or current field text;
  • lookupMode for search versus resolve behavior;
  • valueOf<T>() and tryValueOf<T>() for reading current same-record values, including the active edit buffer.

Search and resolve modes​

FdcLookupMode.search represents an explicit user action, such as clicking the lookup button or pressing the configured shortcut.

FdcLookupMode.resolve represents silent resolution during commit. A callback can therefore use one function for both workflows:

onLookup: (context) async {
  switch (context.lookupMode) {
    case FdcLookupMode.search:
      return showProductSearch(context);
    case FdcLookupMode.resolve:
      return resolveProductCode(context.lookupText);
  }
}

Cancellation​

Return null when the user cancels or when a search should not change the record.

Shared lookup design​

The lookup context intentionally avoids grid-specific coordinates. The same lookup workflow can be reused from a standalone editor or a grid column because both operate on dataset fields and return FdcLookupResult.