go_form 1.9.0
go_form: ^1.9.0 copied to clipboard
A generic controller for managing state and validation of input fields in Flutter. Supports initial value, validation, errors, and focus.
1.9.0 - 2025-08-26 #
Added #
-
Advanced validation trigger system - Complete overhaul of form validation behavior with granular control:
- Added
defaultValidationTriggers
parameter toFormController
constructor for setting global validation triggers - Added
validateOnlyAfterFirstSubmit
parameter to improve UX by preventing validation errors during initial input - Added
validationTriggers
parameter toaddTextField()
for field-specific validation behavior - Added
setFieldValidationTriggers()
method to dynamically change validation triggers for specific fields - Added
getFieldValidationTriggers()
method to retrieve current validation triggers for any field - Added
validateField()
method for synchronous validation of individual fields - Added
validateFieldAsync()
method for asynchronous validation of individual fields
- Added
-
New ValidationTrigger enum values for comprehensive validation control:
ValidationTrigger.onFocusLost
- validate when field loses focusValidationTrigger.onFocusGained
- validate when field gains focusValidationTrigger.onValueChange
- validate on every value changeValidationTrigger.onDebounceComplete
- validate after debounce completionValidationTrigger.onSubmit
- validate only on form submissionValidationTrigger.manual
- manual validation only
-
Form introspection methods for better debugging and development experience:
- Added
getFieldCount()
method to get the number of registered fields - Added
isEmpty
getter to check if form has no registered fields - Added
isNotEmpty
getter to check if form has registered fields - Added
getFieldNames()
method to get a list of all registered field names
- Added
Improved #
-
Enhanced user experience with
validateOnlyAfterFirstSubmit
:- Prevents irritating validation errors during initial form input
- Enables real-time validation feedback after first submission attempt
- Follows modern UX patterns used by Gmail, Facebook, and other major platforms
-
Better architecture - removed circular dependencies between
FormController
andFieldController
-
Comprehensive documentation - added detailed API documentation with practical examples for all new features
Changed #
- Breaking: Default validation behavior is now
ValidationTrigger.onSubmit
only (was previously mixed) - Updated
addTextField()
method signature to include optionalvalidationTriggers
parameter
Migration Guide #
Before (v1.8.1):
final formController = FormController();
// Validation behavior was not configurable
After (v1.9.0):
// For backward compatibility (validation only on submit)
final formController = FormController();
// For enhanced UX (recommended)
final formController = FormController(
defaultValidationTriggers: {
ValidationTrigger.onFocusLost,
ValidationTrigger.onValueChange,
},
validateOnlyAfterFirstSubmit: true,
);
// For field-specific behavior
formController.addTextField<String>(
name: 'email',
validator: emailValidator,
validationTriggers: {ValidationTrigger.onFocusLost},
);
formController.addTextField<String>(
name: 'password',
validator: passwordValidator,
validationTriggers: {ValidationTrigger.onValueChange},
);
Examples #
Real-time validation with user-friendly experience:
final formController = FormController(
defaultValidationTriggers: {ValidationTrigger.onValueChange},
validateOnlyAfterFirstSubmit: true, // No errors until first submit
);
Mixed validation strategies:
// Email: validate when user finishes typing
formController.setFieldValidationTriggers('email', {
ValidationTrigger.onFocusLost
});
// Password: validate in real-time for security
formController.setFieldValidationTriggers('password', {
ValidationTrigger.onValueChange,
ValidationTrigger.onFocusLost,
});
// Confirm password: validate only on submit
formController.setFieldValidationTriggers('confirmPassword', {
ValidationTrigger.onSubmit
});
1.8.1 - 2025-07-05 #
Fixed #
- Fixed an issue where validation error state would not clear after successful re-validation
1.8.0 - 2025-07-05 #
Added #
- Added
FieldStatus
enum with detailed states:idle
,loading
,validated
,error
,debounce
, andfilled
. - Each
FieldController
now exposesstatus
to track its current validation state. - Introduced
onDebounceComplete
callback forFieldController
, allowing custom actions after debounce finishes. - Added
setStatus()
method toFieldController
to programmatically update field status. - Enhanced
FormFieldData
with a newstatus
field and added complete documentation comments for all fields and methods. - Added internal logic to preserve
FieldStatus.error
if a field has an error during debounce resolution.
Fixed #
- Status no longer resets incorrectly after debounce if the field already has a validation error.
1.7.0 - 2025-06-28 #
Added #
- Added
hasChanges()
method inFormController
to detect if any fields differ from their initial values. - Added
resetToInitialValues()
method to reset all form fields to their originally registered values. - Added
getChangedFields()
method inFormController
to retrieve a map of all fields that have been changed.
1.6.0 - 2025-06-27 #
Added #
- Added new focus control methods in
FormController
:focus(String name)
– focuses the field with the given name.unfocus(String name)
– removes focus from the specified field.unfocusAll()
– removes focus from all fields.focusNext(String name)
– moves focus to the next field.focusPrevious(String name)
– moves focus to the previous field.focusFirstError()
– focuses the first field that has a validation error.hasFocus(String name)
– returnstrue
if the field is currently focused.hasError(String name)
– returnstrue
if the field currently has a validation error.
- Added support for debounced value changes via
debounceDuration
inFieldController
. - Added
validateAsync()
method inFieldController
andFormController
for asynchronous validation. - Added
asyncValidator
property inFormFieldModelBase
andFormController
to support field-level async validation logic.
Fixed #
- Fixed an issue where
FocusNode
state could be lost duringDynamicForm
rebuilds. - Improved compatibility with
scrollToFirstErrorField()
— it now reliably focuses the first field with a validation error. - Fixed a bug with recursive
Focus
wrapping that triggeredchild != this
assertion errors. - Added
isFocusHandledExternally
flag toFieldController
to allow external management of focus nodes. - Updated the example: added a form demonstrating automatic focus on the first error field.
- Fixed field rebuild behavior when using debounce; fields no longer lose state on delayed input.
1.5.3 - 2025-06-14 #
- bug fix
1.5.2 - 2025-06-14 #
Fixed #
- Migrated DynamicForm from StatelessWidget to StatefulWidget to support local state handling.
- lemented didUpdateWidget to properly refresh field entries when fields or controller change.
1.5.1 - 2025-06-14 #
Changed #
- Refactored
DynamicForm
to be aStatefulWidget
, allowing controller initialization andonInit
to be called once duringinitState()
. - Improved performance by avoiding repeated
addToController
andonInit
calls during everybuild
.
1.5.0 - 2025-06-14 #
Added #
- Added
onInit(FieldController<T>)
method toFormFieldModelBase
, which is called once when the field is initialized in the form. - Useful for custom one-time field logic (e.g., preloading data, triggering async calls).
Fixed #
addFieldValueListener
now triggers only on real value changes, not during validation.
1.4.0 - 2025-03-17 #
Added #
- Added new methods in
FormController
:addFieldFocusListener(void Function(String name, bool hasFocus) listener)
— adds a focus change listener.removeFieldFocusListener(void Function(String name, bool hasFocus) listener)
— removes a focus change listener.
Changed #
- Moved
FocusNode
storage fromFormFieldData
toFieldController
to prevent it from being recreated when data updates. FocusNode
is now created once inFieldController
and managed at the field level, improving focus stability.
1.3.0 - 2025-03-12 #
New Features #
- Added
addFieldValueListener(void Function(String, dynamic) listener)
toFormController
. - Added
removeFieldValueListener(void Function(String, dynamic) listener)
toFormController
. - Now
addTextField
automatically notifies listeners when field values change.
1.2.0 - 2025-03-09 #
New Features #
-
Added methods for subscribing to form validation state changes:
addValidationListener(void Function(bool) listener)
– allows subscribing to form validation state changes ( valid/invalid).removeValidationListener(void Function(bool) listener)
– removes a previously added validation listener.
-
Added a new method in
FieldController
:silentValidate()
– performs field validation without setting an error and returnstrue
if the field is valid orfalse
if there is an error.
1.1.0 - 2025-02-28 #
Added #
- Getter
errorsKey
: Returns aList<Key?>
containing all elements with validation errors. - Method
firstFieldKey
: Returns theKey
of the first element in_fields
, ornull
if_fields
is empty. - Method
scrollToFirstField()
: Automatically scrolls to the first field in_fields
and requests focus. - Method
scrollToFirstErrorField()
: Scrolls to the first field with an error and requests focus. - Improved validation handling: now it's easier to locate and scroll to invalid fields.
Fixed #
- Resolved potential issues with
Key
handling in forms.
Usage #
Scroll to the first field
You can now automatically scroll to the first field in _fields
:
scrollToFirstField();
1.0.0 - 2025-02-24 #
New Features #
- Added documentation – full README with examples, API descriptions, and usage instructions.
- Added support for
key
– now widgets can be identified more easily in tests.
Improvements #
- Optimized
dispose()
inFormController
– resources are now properly cleaned up. - Enhanced handling of
key
properties – fields can now use keys for better identification. - Optimized UI re-rendering – reduced unnecessary rebuilds.
Bug Fixes #
- Fixed memory leak issues related to
dispose()
. - Fixed test failures caused by missing
key
properties. - Improved error handling in form validation.
Developer Experience #
- Added full documentation – with examples, project structure, and best practices.
- Added new tests – improved unit and widget test coverage.
- Cleaner and more efficient code – improved architecture and optimized UI updates.
0.3.1 - 2025-01-29 #
Added #
- Introduced a named constructor
DynamicForm.separator
, allowing the use ofseparatorBuilder
for custom separators between form fields. - If
separatorBuilder
is provided, it will be used instead of the defaultSizedBox(height: fieldSpacing)
, offering greater flexibility in UI customization.
Example: #
DynamicForm.separator
(
fields: myFields,
controller: myController,
separatorBuilder: (context, index) => Divider(),
);
0.2.2 - 2024-12-04 #
Fixes #
- Fixed the "name field is already in use" issue.
- Disabled protection against duplicate field creation.
0.2.0 - 2024-12-02 #
Added #
- Listener support: Introduced the ability to add, remove, and check listeners for
FieldController
andFormController
.- New methods in
FormController
:addListener(String name, VoidCallback listener)
: Attach a listener to a specific field.removeListener(String name, VoidCallback listener)
: Detach a listener from a specific field.hasListener(String name)
: Check if a field has listeners attached.
- Enhancements to
FieldController
:- Stores and triggers custom listeners on value changes.
- Exposes
hasListeners
to check if listeners are registered.
- New methods in
0.1.1 - 2024-11-22 #
Fixed #
- Fixed an issue with generic type mismatch causing override errors in
FormFieldModelBase.build
.
0.1.0 #
- Added
FieldController
for form field state management. - Support for
TextFormField
synchronization viaTextEditingController
. - Added
setValue
method toFieldController
for programmatically updating field values. - Built-in validation and error handling.
0.0.2 #
- Initial release of the
go_form
plugin.
0.0.1 #
- Initial release of the
go_form
plugin. - Key features:
- Form controller