class abstract

Base class for all form blocs in the blocx ecosystem.

Manages the full lifecycle of an immutable form backed by a BlocxBaseFormEntity subclass. Wires up validation, submission, optional stepped navigation, unique-field checking, and initial info-fetching automatically based on which mixins are applied.

Minimal setup

Define a field enum E and a BlocxBaseFormEntity subclass F.
Extend BlocxFormBloc with those types plus a payload type P. Use void when there is no initial payload.
Provide submitUseCaseTask, the required submit task.

class CreatePostBloc extends BlocxFormBloc<PostForm, void, PostField> {
  CreatePostBloc() : super(PostForm.empty());

  @override
  BlocxUseCaseTask<CreatePostInput, PostResponse> get submitUseCaseTask {
    return BlocxUseCaseTask<CreatePostInput, PostResponse>(
      useCase: _createPostUseCase,
      inputBuilder: () => CreatePostInput(title: formData.title),
    );
  }
}

Optional features

Mixin	Behaviour unlocked
BlocxFormSteppedMixin	Multi-step form navigation
BlocxUniqueFieldValidatorMixin	Async per-field uniqueness checks
BlocxFormInfoFetcherMixin	Fetches remote data before the form renders

Update / edit forms

When editing an existing entity, pass the entity as the payload P and override applyPayloadToFormData to hydrate F from it. Dispatch BlocxFormEventInit with the payload to trigger hydration.

Type parameters

F: The immutable form entity. Must extend BlocxBaseFormEntity.
P: The optional payload type used for edit-mode hydration. Use void for create-only forms.
E: The enum identifying each field. Used as the key for updates, validation errors, and info-fetching.

Inheritance

Object
BaseBloc<BlocxFormEvent, BlocxFormState<F, E>>
BlocxFormBloc

Mixed-in types

BlocxFormErrorsMixin<F, P, E>

Implementers

Constructors

BlocxFormBloc(F formData): Creates the bloc with the blank formData as the initial state.

Properties

comesFromPreviousStep → bool: Whether the current step was reached by going backward.
no setter
defaultError → ReadableError: The fallback ReadableError used when no BlocxErrorTranslator is registered or when the translator does not recognise the error.
no setterinherited
emitChangesOnUpdate → bool: Whether every field update should emit an intermediate update state.
no setterinherited
errorDisplayPolicy → ErrorDisplayPolicy: The default error display policy for this form bloc.
no setterinherited
errors → Map<E, Set<String>>: An immutable snapshot of the current field errors.
no setterinherited
fieldsFetchingInfo → Set<E>: The set of fields currently waiting on a remote info fetch.
no setter
formData ↔ F: Current form data.
getter/setter pairinherited
formValidationMode → FormValidationMode: The current validation mode.
no setterinherited
hashCode → int: The hash code for this object.
no setterinherited
isClosed → bool: Whether the bloc is closed.
no setterinherited
isFormSubmittable → bool: Whether the current form can execute the submit use case.
no setter
isInfoFetcher → bool: Whether this bloc has BlocxFormInfoFetcherMixin applied.
no setter
isStepped → bool: Whether this bloc has BlocxFormSteppedMixin applied.
no setter
isUniqueFieldValidator → bool: Whether this bloc has BlocxUniqueFieldValidatorMixin applied.
no setter
isUpdate → bool: Whether the form is currently in update/edit mode.
no setterinherited
payload → P?: The current update payload, if any.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
screenManagerCubit → ScreenManagerCubit: Direct access to the internal ScreenManagerCubit.
no setterinherited
state → BlocxFormState<F, E>: The current state.
no setterinherited
stepIndex → int: Current form step index.
no setterinherited
stream → Stream<BlocxFormState<F, E>>: The current stream of states.
no setterinherited
submitUseCaseTask → BlocxUseCaseTask<Object?, Object?>: The use case task executed when the form is submitted.
no setterinherited
uniqueKeysBeingChecked → Set<E>: The set of fields whose uniqueness is currently being checked remotely.
no setter
validateOnInit → bool: Whether the form should validate immediately after initialisation.
no setterinherited

Methods

add(BlocxFormEvent event) → void: Notifies the Bloc of a new event which triggers all corresponding EventHandler instances.
inherited
addError(Object error, [StackTrace? stackTrace]) → void: Reports an error which triggers onError with an optional StackTrace.
inherited
applyPayloadToFormData(P payload) → FutureOr<F>: Converts an update payload into form data.
inherited
clearAllErrors() → void: Clears all field errors and cancels all pending timed-error timers.
inherited
clearFieldError(E key, {String? errorMessage}) → bool: Clears either one error message or all errors for the field key.
inherited
clearFieldErrors(BlocxFormEventClearFieldError<E> event, Emitter<BlocxFormState<F, E>> emit) → FutureOr<void>: Handles BlocxFormEventClearFieldError.
inherited
clearTimers() → void: Cancels all pending timed-error timers.
inherited
close() → Future<void>: Closes the bloc and cancels all pending timed-error timers.
override
displayErrorSnackbar(String message, {String? title}) → void: Displays an error snackbar with message and optional title.
inherited
displayErrorWidget(ReadableError error) → void: Displays a full-page error widget for error.
inherited
displayErrorWidgetByErrorCode(BlocXErrorCode errorCode, {Object? error, StackTrace? stackTrace}) → void: Displays a full-page error widget derived from a BlocXErrorCode.
inherited
displayInfoSnackbar(String message, {String? title}) → void: Displays an info snackbar with message and optional title.
inherited
displayWarningSnackbar(String message, {String? title}) → void: Displays a warning snackbar with message and optional title.
inherited
doBeforeSubmit(Emitter<BlocxFormState<F, E>> emit) → Future<bool>: Runs before the submit use case.
inherited
emit(BlocxFormState<F, E> state) → void: emit is only for internal use and should never be called directly outside of tests. The Emitter instance provided to each EventHandler should be used instead.
inherited
emitState(Emitter<BlocxFormState<F, E>> emit) → void: Emits the current loaded form state.
handleError(Object error, Emitter<BaseState> emit, {StackTrace? stacktrace}) → FutureOr<void>: Logs error, translates it to a ReadableError, then surfaces it according to errorDisplayPolicy.
inherited
handleUpdateFormDataEvent(BlocxFormEventUpdateFormData<P> event, Emitter<BlocxFormState<F, E>> emit) → FutureOr<void>: Handles replacing the full form data from a new payload.
inherited
hasError(E key, [String? code]) → bool: Whether the field identified by key currently has an error.
inherited
initData(F formData) → void: Initialises form data and registers form data event handlers.
inherited
initErrors() → void: Initialises form error event handlers.
inherited
initForm(BlocxFormEventInit<P> event, Emitter<BlocxFormState<F, E>> emit) → FutureOr<void>: Handles the initial form event.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
on<E extends Event>(EventHandler<E, BlocxFormState<F, E>> handler, {EventTransformer<E>? transformer}) → void: Register event handler for an event of type E. There should only ever be one event handler per event type E.
inherited
onChange(Change<BlocxFormState<F, E>> change) → void: Called whenever a change occurs with the given change. A change occurs when a new state is emitted. onChange is called before the state of the cubit is updated. onChange is a great spot to add logging/analytics for a specific cubit.
inherited
onDone(BlocxFormEvent event, [Object? error, StackTrace? stackTrace]) → void: Called whenever an event handler for a specific Bloc has completed. This may include an error and stackTrace if an uncaught exception occurred within the event handler.
inherited
onError(Object error, StackTrace stackTrace) → void: Called whenever an error occurs and notifies BlocObserver.onError.
inherited
onEvent(BlocxFormEvent event) → void: Called whenever an event is added to the Bloc. A great spot to add logging/analytics at the individual Bloc level.
inherited
onFormSubmitted(Emitter<BlocxFormState<F, E>> emit, BlocxUseCaseResult<Object?> result) → Future<bool>: Runs after successful form submission.
inherited
onTransition(Transition<BlocxFormEvent, BlocxFormState<F, E>> transition) → void: Called whenever a transition occurs with the given transition. A transition occurs when a new event is added and a new state is emitted from a corresponding EventHandler.
inherited
pop() → void: Triggers a pop/back-navigation signal.
inherited
setErrorToField(BlocxFormEventSetErrorToField<E> event, Emitter<BlocxFormState<F, E>> emit) → FutureOr<void>: Handles BlocxFormEventSetErrorToField.
inherited
setFieldError(E key, String error) → bool: Adds error to the field identified by key.
inherited
setFieldErrorsBulk(E key, List<String> errors) → void: Adds multiple errors to the field identified by key.
inherited
setTimedErrorToField(BlocxFormEventSetTimedErrorToField<E> event, Emitter<BlocxFormState<F, E>> emit) → Future<void>: Handles BlocxFormEventSetTimedErrorToField.
inherited
submit(BlocxFormEventSubmit event, Emitter<BlocxFormState<F, E>> emit) → Future<void>: Handles form submission.
inherited
toString() → String: A string representation of this object.
inherited
updateData(BlocxFormEventUpdateData<E> event, Emitter<BlocxFormState<F, E>> emit) → FutureOr<void>: Handles a single field update event.
inherited
updateFormData(E key, dynamic data) → Future<F>: Updates the form data by field key and runs validation.
inherited
validateForm(F formData, {E? key, bool forceFullValidation = false}) → FutureOr<void>: Validates the form.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited