form_companion_presenter

Description:

form companion presenter

form_companion_presenter #
Ease and simplify your Form related work with fine application structure.
With form_companion_generator, your boilerplate code will be gone!
If you use Flutter FormBuilder, check outform_builder_companion_presenter, which is a brother of this package for Flutter FormBuilder.
Features #

With form_companion_generator, your boilerplate code will be gone!
Separete "presentation logic" from your Widget and make them testable.

Easily and simply bind properties and event-handlers to form fields.


Remove boring works from your form usage code.

Enable "submit" button if there are no validation errors.
Combine multiple validators for single FormField.


Asynchronous validation support with throttling and canceling.
Provide a best practice to fetch validated value. You don't have to think about onSave or onChange or TextController or Key...
State restoration even if you use DropdownButtonFormField.

Getting Started #
Installation #
Do you read this section in pub.dev? Check above and click "Installing" tab!

Write a dependency to form_companion_presenter in your pubspec.yaml and run flutter pub get
Or, run flutter pub add form_companion_presenter.

Usage #
Prerequisite
Note that this example uses riverpod and form_companion_generator, and it is recommended approach.

Ensure following packages are added to dependencies of your pubspec.yaml


riverpod
riverpod_annotation
form_companion_presenter


Ensure following packages are added to dev_dependencies of your pubspec.yaml


build_runner
riverpod_generator
form_companion_generator

Example:
dependencies:
riverpod: # put favorite version above 2.0.0 here
riverpod_annotation: # put favorite version here
form_companion_presenter: # put favorite version here
...

dev_dependencies:
build_runner: # put favorite version above 2.0.0 here
riverpod_generator: # put favorite version here
form_companion_generator: # put favorite version here
copied to clipboard

(Optional) Add build.yaml in your project's package root (next to pubspec.yaml) and configure it (see documentation of build_config and form_companion_generator docs for details).

Steps

Declare presenter class. Note that this example uses riverpod and form_companion_generator, and it is recommended approach.

@riverpod
@formCompanion
class MyPresenter extends _$MyPresenter {
MyPresenter() {
}

@override
FutureOr<$MyPresenterFormProperties> build() async {
}
}
copied to clipboard

Declare with in your presenter for CompanionPresenterMixin and FormCompanionMixin in this order:

@riverpod
@formCompanion
class MyPresenter extends _$MyPresenter
with CompanionPresenterMixin, FormCompanionMixin {
MyPresenter() {
}

@override
FutureOr<$MyPresenterFormProperties> build() async {
}
}
copied to clipboard

Add initializeCompanionMixin() call with property declaration in the constructor of the presenter. Properties represents values of states which will be input via form fields. They have names and validators, and their type must be same as FormField's type rather than type of state object property:

MyPresenter() {
initializeCompanionMixin(
PropertyDescriptorBuilder()
..string(
name: 'name',
validatorFactories: [
(context) => (value) => (value ?? '').isEmpty ? 'Name is required.' : null,
],
)
..integerText(
name: 'age',
validatorFactories: [
(context) => (value) => (value ?? '').isEmpty ? 'Age is required.' : null,
(context) => (value) => int.parse(value!) < 0 ? 'Age must not be negative.' : null,
],
)
);
}
copied to clipboard
Note that there are various extension methods of PropertyDescriptorBuilder to implement initialization easily. In addition, you can specify form field types for generated form factories with extension methods of PropertyDescriptorBuilder which have WithField suffixes.

Implement build to fetch upstream state and fill it as properties' initial state.

@override
FutureOr<$MyPresenterFormProperties> build() async {
final upstreamState = await ref.watch(upstreamStateProvider.future);
return resetProperties(
(properties.copyWith()
..name(upstreamState.name)
..age(upstreamState.age)
).build()
)
}
copied to clipboard

Add part directive near top of the file where example.dart is the file name of this code.

part 'example.fcp.dart';
part 'example.g.dart';
copied to clipboard


Run build_runner (for example, run flutter pub run build_runner build -d). Provider global property and related types will be created by riverpod_generator, and $MyPresenterFormStates and related extensions will be created by form_companion_generator.


Implement doSubmit override method in your presenter. It handle 'submit' action of the entire form.


@override
FutureOr<void> doSubmit(BuildContext context) async {
// Gets a validated input values
String name = properties.values.name;
int age = properties.values.age;
// Calls your business logic here. You can use await here.
...
// Set state to expose for other components of your app.
ref.read(anotherStateProvider).state = AsyncData(MyState(name: name, age: age));
// and more...
}
copied to clipboard

Create a widget. We use ConsumerWidget here. Note that you must place Form and FormFields to separate widget. Note that state.fields have form field factories generated by form_companion_generator and their type can be controlled in the presenter:

class MyForm extends StatelessWidget {
@override
Widget build(BuildContext context) => Form(
child: MyFormFields(),
);
}

class MyFormFields extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final state = ref.watch(myPresenterProvider);
return Column(
children: [
state.value.fields.name(
context,
decoration: InputDecoration(
labelText: 'Name',
),
),
state.value.fields.age(
context,
decoration: InputDecoration(
labelText: 'Age',
),
),
ElevatedButton(
onTap: state.value.submit(context),
child: Text('Submit'),
),
],
);
}
}
copied to clipboard
If you set AutovalidateMode.disabled (default value) to Form, you can execute validation in head of your doSubmit() as following:
@override
FutureOr<void> doSubmit(BuildContext context) async{
if (!await validateAndSave(context)) {
return;
}

..rest of code..
}
copied to clipboard
That's it!
Enable State Restoration #
State restoration improves form input experience because it restores inputting data for the form when the app was killed on background by mobile operating systems. Is it very frustrated if you lose inputting data during open browser to find how to fill the form fields correctly? The browser tends to use large memory, so your app could be terminated frequently.
To enable state restoration, just put FormPropertiesRestorationScope under your Form like following:
class MyForm extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final presenter = ref.read(myPresenterProvider.notifier);
return Form(
child: FormPropertiesRestorationScope(
presenter: presenter,
child: MyFormFields(),
),
);
}
}
copied to clipboard
Note that if you omit (or specify null for) restorationId of FormPropertiesRestorationScope, string representation of runtimeType of presenter will be used. If you avoid restoration in whole fields, just remove FormPropertiesRestorationScope your widget tree.
More examples? #
See repository. *_vanilla_form_*.dart files use form_companion_presenter. Note that *_form_builder_*.dart files use form_builder_companion_presenter instead.
Components #
This package includes three main constructs:

CompanionPresenterMixIn, which is main entry point of this form_companion_presenter.
FormCompanionMixin, which connects flutter's built-in Form and CompanionPresenterMixIn.
FormPropertiesRestorationScope which enables State restoration.

There are advanced constructs for you:

AsyncValidatorExecutor, which is helper of asynchronous validation.

This is a helper of FormCompanionPresenterMixIn, but you can utilize alone.


FutureInvoker, which translates Future based async to completion callback based async.

This is base class of AsyncValidatorExecutor, and you can use it as you like.



Localization #
Of course, you can localize texts and messages to be shown for users!
For localize built-in validators' messages, you can use .copyWith() method and ParseFailureMessageProvider<T> function to plug in the localization code.
For AsyncValidatorExecutor's text, just specify the localized label via text named parameter of the constructor.
For FormFields which are created in form field factory (.fields in previous example), you can add your localization logic with configuring "templates" in your build.yaml. See form_companion_generator docs for details.
PropertyDescriptor details #
You can customize PropertyDescriptor via optional named parameters of PropertyDescriptorsBuilder's add method or its extension methods. Following table shows parameters of the add method. Note that some of them are common in other (extension) methods.



name
summary
type
default
note




P
Type of the property to be stored.
extends Object
(required)
Can be accessed via PropertyDescriptor<P, F>.value getter.


F
Type of the value in FormField.
extends Object
(required)
Can be accessed via getFieldValue and setFieldValue.


name
Name of the property.
String
(required)
Name will be 1) getter names generated by form_companion_generator, 2) keys to get PropertyDescriptor


validatorFactories
Factories for normal validations.
List<FormFieldValidatorFactory<F>>?
[]
See below for details.


asyncValidatorFactories
Factories for asynchronous validations.
List<AsyncValidatorFactory<F>>?
[]
See below for details.


initialValue
An initial value of the property.
P?
null



equality
Custom equality comparer for F.
Equality<F>?
null
If null, values for FormField will be compared with equals() method.


valueConverter
Value conversion between P and F.
ValueConverter<P, F>?
null
If null, internal default converters will be used. Note that value conversion will be treated as normal validation implicitly. See below for details.


enumValues
(introduced in 0.5) Tells values of the specified enum for state restoration.
Iterable<T>
(required)
In most cases, E.values static member like Brightness.values.


valueTraits
(introduced in 0.5) Specifies additional traits of the value.
PropertyValueTraits?
null
null means uses PropertyValueTraits.none. For details, see "Value Traits" section bellow.


restorableValueFactory
(introduced in 0.5) Factory to produce RestorableValue<F> for the property.
RestorableValueFactory<F>?
null
If null, restoration will not work. There are some out-of-box built-in factories: stringRestorableValueFactory, intRestorableValueFactory, doubleRestorableValueFactory, boolRestorableValueFactory, bigIntRestorableValueFactory, enumRestorableValueFactory(), enumListRestorableValueFactory(), dateTimeRestorableValueFactory, dateTimeRangeRestorableValueFactory, and rangeValuesRestorableValueFactory.



Normal Validations #
Normal validations are done by normal validators, and the validators will be constructed via validator factories which are specified in validatorFactories parameter.
validatorFactories parameter's type is List<FormFieldValidatorFactory<F>>?, and FormFieldValidatorFactory<F> is alias of FormFieldValidator<T> Function(ValidatorCreationOptions) function type, where FormFieldValidator<T> is alias of String? Function(T?) function type, which is defined in flutter/widgets.dart library.
The ValidatorCreationOptions contains BuildContext and Locale, which are determined when PropertyDescriptor<P, F>.getValidator() method is called. The validator factories can use these parameters to build their validators, a main use-cases including error message localization and format (such as decimal number or currency) localization.
The contract of FormFieldValidator<T> is same as normal flutter's validators. So, you return null for valid input, or return non-null validation error message for invalid input.
Note that tail of normal validators chain is always implicit validator which try to convert from F to P. It will return conversion failure message as validation result when it will fail to convert value from F to P.
Asynchronous Validation #
Asynchronoous validations are done by asynchronous validators, and the validators will be constructed via validator factories which are specified in asyncValidatorFactories parameter.
asyncValidatorFactories parameter's type is List<AsyncValidatorFactory<F>>?, and AsyncValidatorFactory<F> is alias of AsyncValidator<T> Function(ValidatorCreationOptions) function type. The AsyncValidator<T> is alias of FutureOr<String?> Function(T?, AsyncValidatorOptions) function type.
The ValidatorCreationOptions contains BuildContext and Locale, which are determined when PropertyDescriptor<P, F>.getValidator() method is called. This is same as normal validator factories, so see previous description for it. More importantly, all async validation logics take a second parameter, whih type is AsyncValidatorOptions. The AsyncValidatorOptions object also contains Locale, which is guaranteed to be available when the async validation is called. So, async validators should always use this value instead of the value passed via ValidatorCreationOptions as long as possible.
The contract of AsyncValidator<T> is same as normal flutter's validators except it is wrapped with FutureOr<T>. So, you declare the async validation logic as async, and you return null for valid input, or return non-null validation error message for invalid input.
Note that asynchronous validators chain will be invoked after all normal validators including an implicit validator which try to convert from F to P.
Value Conversion #
Sometimes, a type of stored property value (P) and a type of the value which is edited via FormField<T> (F) are different. For example, if a numeric value is input in text box (such as TextFormField), P should be int (or one of the other numeric types). To handle such cases, valueConverter parameter takes ValueConverter<P, F> object.
ValueConverter<P, F> defines two conversion methods, F? toFieldValue(P? value, Locale locale) and SomeConversionResult<P> toPropertyValue(F? value, Locale locale). For most cases, you just use ValueConverter.fromCallbacks factory method, which takes two functions, PropertyToFieldConverter<P, F> and FieldToPropertyConverter<P, F>, they are conpatible with toFieldValue method and toPropertyValue methods respectively. Furthermore, you should use StringConverter<P>.fromCallbacks when F is String, it provides basic implementation for String conversion.
There are some built-in StringConverters are available:

intStringConverter for int and String conversion.
doubleStringConverter for double and String conversion.
bigIntStringConverter for BigInt and String conversion.
dateTimeStringConverter for DateTime and String conversion.
uriStringConverter for Uri and String conversion.

You can use StringConverter.copyWith method when you only customize any combination of:

Conversion failure message.

It is usually done for message localization.


Default conversion result for null input from FormField.
Default String result for null input (initialValue of the property).

So, it is advanced scenario to call StringConverter.fromCallbacks directly, and it is more advanced scenario to call ValueConverter.fromCallbacks directory or extends their converter types. StringConverter.copyWith should cover most cases.
Note that tail of normal validators chain (described above) is always implicit validator which try to convert from F to P. This means that value conversion should be done twice for field value to property value conversion propcess. In addition, when you use text form like field, validation and conversion pipeline should be fired in every charactor input. So, you should implement value convertor that it is light weight and idempotent.
Value Traits #
From 0.5, you can specify PropertyValueTraits for each properties. It affects runtime behavior as following:



member
effect




doNotRestore
If this value is specified, state restoration with form_companion_presenter is disabled for the form field. This is useful the field which input is trivial for users but it can occupy restoration state data.


sensitive
If this value is specified, state restoration with form_companion_presenter is disabled for the form field to avoid persist sensitive data in the local device. In addition, form factories which will be generated by form_companion_generator uses true for default values for obscureText parameters of text field based form fields.



Extension methods #
PropertyDescriptorsBuilder
As described above, there are some extension methods for PropertyDescriptorsBuilder to provide convinient way to define property with commonly used parameters.



name
summary
parameters
package
defined in
note




string
Short hand for add<String, String>.
Mostly same as add but no valueConverter.
form_companion_presenter/form_companion_presenter.dart
FormCompanionPropertyDescriptorsBuilderExtension
For text field based form fields and String property.


boolean
Short hand for add<bool, bool>.
Only name and initialValue.
form_companion_presenter/form_companion_presenter.dart
FormCompanionPropertyDescriptorsBuilderExtension
For check box like form fields and bool property. Note that default initial value is defined as false rather than null. Use enumerated<T> for tri-state value.


enumerated<T>
Short hand for add<T, T> and T is enum.
Only name and initialValue.
form_companion_presenter/form_companion_presenter.dart
FormCompanionPropertyDescriptorsBuilderExtension
For drop down or single selection form fields for enum value.


integerText
Short hand for add<int, String>.
Mostly same as add but there is a stringConverter instead of valueConverter (default is intStringConverter).
form_companion_presenter/form_companion_presenter.dart
FormCompanionPropertyDescriptorsBuilderExtension



realText
Short hand for add<double, String>.
Mostly same as add but there is a stringConverter instead of valueConverter (default is doubleStringConverter).
form_companion_presenter/form_companion_presenter.dart
FormCompanionPropertyDescriptorsBuilderExtension



bigIntText
Short hand for add<BigInt, String>.
Mostly same as add but there is a stringConverter instead of valueConverter (default is bigIntStringConverter).
form_companion_presenter/form_companion_presenter.dart
FormCompanionPropertyDescriptorsBuilderExtension



uriText
Short hand for add<Uri, String>.
Mostly same as add but there is a stringConverter instead of valueConverter (default is uriStringConverter).
form_companion_presenter/form_companion_presenter.dart
FormCompanionPropertyDescriptorsBuilderExtension



stringConvertible<P>
Short hand for add<P, String>.
Mostly same as add but stringConverter (instead of valueConverter) is required.
form_companion_presenter/form_companion_presenter.dart
FormCompanionPropertyDescriptorsBuilderExtension
Use other extension (xxxText) if you can.



See API docs of FormCompanionPropertyDescriptorsBuilderExtensionfor details.
WithField extension methods
There are some WithField variations for above extension methods. There methods accept additional type parameter TField, which asks for form_companion_generator to use the specified FormField class for the property. So, notice that TField does no effect when you do not use form_companion_generator.

Question Why some extension methods rack of xxxWithField companion?
A: Because there are no out-of-box alternative form fields for them, and you can use addWithField<P, F, TField> anyway. If you find that there is a new out-of-box or popular alternative form fields, please file the issue.

PropertyDescriptor
There are also extension methods for PropertyDescriptor, to provide convinient access when you do not use form_companion_generator. These extension methods are defined in CompanionPresenterMixinPropertiesExtension in form_companion_presenter/form_companion_extension.dart library.
See API docs of CompanionPresenterMixinPropertiesExtension for details.
State Restoration in Detail #
As mentioned above, state restoration improves form input experience because it restores inputting data for the form when the app was killed on background by mobile operating systems. Is it very frustrated if you lose inputting data during open browser to find how to fill the form fields correctly? The browser tends to use large memory, so your app could be terminated frequently.
So, every form fields should support restoration, but it is hard to expect all fields implement it. To resolve this problem, form_companion_presenter uses following strategy:

PropertyDescriptor.initialValue remembers "initial value", which is the "field value" of the property if the restored value does not exist.
The validator returned from PropertyDescriptor.getValidator() remembers validation result.
When there is a restored value, PropertyDescriptor.initialValue returns the restored value and it eventually set to initialValue of the form field. In addition, it schedules validation invocation if the form field had validation error before app termination and is not configured to use auto-validation.

Note that state restoration does not work in Web nand Desktop platforms by Flutter's design.
Implementing Your Own Mixin #
You can implement own mixin for your favorite form field framework. To do so, you should implement following:

Your CompanionPresenterFeatures subtype, which implements actual behavior of the mixin. Override methods which you must to do.
Your FormStateAdapter subtype, which wraps actual State of your favorite form field framework. You just implement the class to wrap the actual state.
Your CompanionPresenterMixin subtype as follows:

Declare a field which hold your CompanionPresenterFeatures subtype. It should be declared as late final because it will be initialized in initializeCompanionMixin method override.
Override presenterFeatures getter to return the field which is typed as the CompanionPresenterFeatures subtype.
Override initializeCompanionMixin to initialize the field and call super.initializeCompanionMixin() with a properties argument.
Override other methods if and only if you should do.



For better understand, see source codes of FormCompanionFeatures, FormStateAdapter, FormCompanionPresneter, FormBuilderCompanionFeatures, FormBuilderStateAdapter, and FormBuilderCompanionPresenter.
CompanionPresenterMixin #
This extension defines helper methods to implement your own mixin related types which were described above. See API docs of CompanionPresenterMixinExtension for details.
Breaking Changes #
See [https://github.com/yfakariya/form_companion_presenter/blob/main/BREAKING_CHANGES.md] to check breaking changes.