formGroup<T> function

T formGroup<T>(
  1. String name,
  2. T builder(), {
  3. bool applyWhen(
    1. ValueOf valueOf
    )?,
})

Defines a named group of fields within a formCtrl builder, scoping all Fields created inside builder under the given name prefix.

Every field constructed inside builder receives a dot-notation path prefixed with name (e.g. a field named 'city' inside a group named 'address' becomes 'address.city'). Groups can be nested arbitrarily deep.

Parameters:

  • name: The path segment segment prepended to nested fields.
  • builder: A function that creates and returns the grouped fields (must be a record).
  • applyWhen (optional): A condition function. When provided, validators of all fields created inside this group are only executed if the condition returns true.

Returns the record produced by builder holding the created Field instances.

Example:

final form = formCtrl(() {
  final hasDelivery = Field<bool>('hasDelivery', false);
  final delivery = formGroup(
    'delivery',
    () => (
      street: Field<String>('street').required(),
      city: Field<String>('city').required(),
    ),
    applyWhen: (valueOf) => valueOf<bool>('hasDelivery').value == true,
  );
  return (hasDelivery: hasDelivery, delivery: delivery);
});

Implementation

T formGroup<T>(
  String name,
  T Function() builder, {
  bool Function(ValueOf valueOf)? applyWhen,
}) {
  FormTracker.pushPath(name);
  final countBefore = FormTracker.currentFieldCount;
  try {
    final result = builder();
    if (applyWhen != null) {
      for (final field in FormTracker.getFieldsFrom(countBefore)) {
        field._applyGroupCondition(applyWhen);
      }
    }
    return result;
  } finally {
    FormTracker.popPath();
  }
}