flutter_mobx_form_validation_kit

• Compatible with Android, iOS, Web, Desktop, etc.
• Compatible with Mobx.
• Designed for asynchronous validation.
• Easy to embed into an existing project.

The library can be used in various approaches to the code structure, but I will describe it in terms of the MVC (Model-View-Controller) pattern. In other words, data display is implemented using "dumb" components, while the business logic (including validation) is embedded in Stores. The components will be built with React hooks just because it is a more advanced way, but the library also works well with the class-based approach.

class RegistrationForm extends ControlsCollection {
  final FormControl<String> name;
  RegistrationForm({this.name});
  @override
  Iterable<AbstractControl> allFields() => [this.name];
}
class RegistrationStore {
  FormGroup<RegistrationForm> form;

  RegistrationStore() {
    this.form = FormGroup(RegistrationForm(
        name: FormControl(
            value: "",
            options: OptionsFormControl(validators: [requiredValidator()]))));
  }

  void dispose() {
    this.form.dispose();
  }
}

class _RegistrationState extends State<Registration> {
  RegistrationStore store = RegistrationStore();

  @override
  void dispose() {
    store.dispose();
    super.dispose();
  }

  @override
  Widget build(_) => Observer(builder: (BuildContext context) {
        return Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Text(store.form.controls.name.value,
                  style: TextStyle(fontSize: 20)),
              TextField(
                controller: store.form.controls.name.controller,
                onChanged: (String text) =>
                    store.form.controls.name.value = text,
                decoration: InputDecoration(
                  border: OutlineInputBorder(),
                  labelText: "Name",
                ),
              ),
            ]);
      });
}

If you start typing, the error message will immediately disappear. In its natural and familiar display format, a validation error message appears either after entering a character or after losing the field focus; mobx-form-validation-kit possesses all the necessary tools to achieve this.

TextField(
        focusNode: store.form.controls.name.focusNode,
        controller: store.form.controls.name.controller,
        onChanged: (String text) =>
            store.form.controls.name.value = text,
        decoration: InputDecoration(
        border: OutlineInputBorder(),
        labelText: "Name",
        )),
    if (store.form.controls.name.touched)
    ...store.form.controls.name.errors.map((error) => Text(
        error.message,
        style: TextStyle(color: Colors.red, fontSize: 15)))

In this case, we display the error after the field has been "touched" (i.e., it has lost focus for the first time).

Now, let's discuss the structure of controller nesting and the capabilities of such controllers. The library of mobx-form-validation-kit has three main types of nodes.

The nodes can be assembled in a tree-like structure. Any nesting level is supported, but everything usually starts in FormGroup.

FormGroup
-- FormControl
-- FormControl
-- -- FormGroup
-- -- FormArray
-- -- -- FormGroup
-- -- --  -- FormControl
-- -- FormArray
-- -- --  FormControl

When being defined, each object of the class acquires the following set of options:

Aside from that, there is an additional set of options for FormControl

Each tree element supports the following set of fields:

await this.form.wait();
if (this.form.invalid) {
...

Note: In FormGroup and FormArray, the fields "valid" and "invalid" are focused on nested elements. By checking the top element, you can find out the validity of all the lower-level elements in the form. BUT! The FormGroup and FormArray nodes have their own set of validations and list of errors (errors, warnings, informationMessages, successes). In other words, if you ask FormGroup about the errors, it will return only its own errors, but not the errors in the nested FormControl.

The library of mobx-form-validation-kit allows you to write custom validations, but it also includes its own set.

firstName: FormControl(
    value: "",
    options: OptionsFormControl(validators: [
    requiredValidator(),
    minLengthValidator(2),
    maxLengthValidator(5),
    notContainSpacesValidator()
])),

As you can see, all the validations in the list have been completed, this issue is addressed by using wrapperSequentialCheck. The way it is called and used is not different from a common validator function, but it accepts an array of validators that will be run sequentially, i.e., the next validation will start only after the previous one is completed without errors. The second wrapper function is the function of validation flow control. As its first parameter, wrapperActivateValidation accepts a function in which you want to specify the conditions for activating validations. Unlike the activate function that is sent to FormControl, this check is designed for a more complex logic. Let's assume that we have a common builder for the entire FormGroup of payments, and moreover, the server has only one method server that accepts a common set of fields. But the problem is that even though the form is one, we have to display a different set of fields to the user depending on the "payment type." So, wrapperActivateValidation allows you to write a logic that will perform various checks depending on the payment type.

firstName: FormControl(
          value: "",
          options: OptionsFormControl(validators: [
            wrapperSequentialCheck([
              requiredValidator(),
              minLengthValidator(2),
              maxLengthValidator(5),
              notContainSpacesValidator()
            ])
          ]))

Custom validation of the group.

class FormRange extends ControlsCollection {
  final FormControl<DateTime> min;
  final FormControl<DateTime> max;
  FormRange({this.min, this.max});
  @override
  Iterable<AbstractControl> allFields() => [this.min, this.max];
}

class RegistrationForm extends ControlsCollection {
…
  RegistrationForm(
      {this.firstName, this.lastName, this.email, this.age, this.dateRange});

  @override
  Iterable<AbstractControl> allFields() =>
      [this.firstName, this.lastName, this.email, this.age, this.dateRange];
}

this.form = FormGroup(RegistrationForm(
...
      dateRange: FormGroup<FormRange>(
          FormRange(
              min: FormControl<DateTime>(value: DateTime.now()),
              max: FormControl<DateTime>(value: DateTime.now())),
          options: OptionsFormGroup<FormRange>(validators: [
            (FormGroup<FormRange> group) async {
              if (group.controls.max.value.isBefore(group.controls.min.value)) {
                return [
                  ValidationEvent(
                    message: 'Date in the "from" field is later than the date in the "to" field,'
                    type: ValidationEventTypes.Error,
                  )
                ];
              }
              return [];
            },
          ])),    
));

As you can see in the example, the validation is not assigned to something specific although this is also possible, but to the entire group. All that remains is to display the errors of the group in the interface.

await this.form.wait();
    if (this.form.invalid) {
      this.form.setTouched(true);
      final firstError = this.form.allControls().firstWhere((c) => c.invalid);
      firstError.focusNode.requestFocus();
    }

It is clear that the library's capabilities are not limited to the described use cases. We can present more of them and provide other examples. • Such as that the validations will work not only when the value changes, but also when an observable variable is changed within the validation. • The way the "active" method works. • The FormControl can be initialized not only by a specific variable but also by a function that returns a value. The changes within this function will also be tracked. • How to use FormArray. • How to make complex validation with requests to the server and still ensure that the variables in this validation will be tracked.

And much more, which allows you to use the mobx-form-validation-kit out of the box.

PS If you find any error, please contact us and we will fix it :)

//-----------------------------------------------------------------------------------------------------------------------

• Совместимость c Android, iOS, Web, Desktop и т.д.
• Совместимость с Mobx
• Рассчитан на асинхронные валидации
• Легко встроить в существующий проект.

Библиотеку можно применять при разных подходах к структуре кода, но я буду рассматривать библиотеку в концепции MVC (Model-View-Controller). Т.е. отображение происходит через «глупые» компоненты, а бизнес логика (в том числе и валидация) зашита в Stor-ах. Компоненты будут строятся на react-хуках, просто по причине, что он более современный, но библиотека хорошо работает и в «классовом подходе».

class RegistrationForm extends ControlsCollection {
  final FormControl<String> name;
  RegistrationForm({this.name});
  @override
  Iterable<AbstractControl> allFields() => [this.name];
}
class RegistrationStore {
  FormGroup<RegistrationForm> form;

  RegistrationStore() {
    this.form = FormGroup(RegistrationForm(
        name: FormControl(
            value: "",
            options: OptionsFormControl(validators: [requiredValidator()]))));
  }

  void dispose() {
    this.form.dispose();
  }
}

class _RegistrationState extends State<Registration> {
  RegistrationStore store = RegistrationStore();

  @override
  void dispose() {
    store.dispose();
    super.dispose();
  }

  @override
  Widget build(_) => Observer(builder: (BuildContext context) {
        return Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Text(store.form.controls.name.value,
                  style: TextStyle(fontSize: 20)),
              TextField(
                controller: store.form.controls.name.controller,
                onChanged: (String text) =>
                    store.form.controls.name.value = text,
                decoration: InputDecoration(
                  border: OutlineInputBorder(),
                  labelText: "Имя",
                ),
              ),
            ]);
      });
}

Если начать что-то вводить, то ошибка тут же пропадет. Но естественный и привычный нам формат отображения ошибки валидации подразумевает отображение этой самой ошибки или после ввода символа, либо после того как фокус у поля будет потерян. mobx-form-validation-kit имеется весь необходимый набор для этого.

TextField(
        focusNode: store.form.controls.name.focusNode,
        controller: store.form.controls.name.controller,
        onChanged: (String text) =>
            store.form.controls.name.value = text,
        decoration: InputDecoration(
        border: OutlineInputBorder(),
        labelText: "Имя",
        )),
    if (store.form.controls.name.touched)
    ...store.form.controls.name.errors.map((error) => Text(
        error.message,
        style: TextStyle(color: Colors.red, fontSize: 15)))

В данном случае мы отображаем ошибку после того как поле «потрогали» (т.е. оно потеряло фокус в первый раз).

Разберем структуру вложенности контроллеров и их возможности. Библиотека mobx-form-validation-kit имеет три основных типа узлов

Сами узлы можно складывать в древовидном стиле. Поддерживается любой уровень вложенности, но обычно все начинается в FormGroup.

FormGroup
-- FormControl
-- FormControl
-- -- FormGroup
-- -- FormArray
-- -- -- FormGroup
-- -- --  -- FormControl
-- -- FormArray
-- -- --  FormControl

Каждый объект класса поддерживает следующий набор опций при определении

Кроме этого для FormControl есть дополнительный набор опций

Каждый элемент дерева поддерживает следующий набор полей

await this.form.wait();
if (this.form.invalid) {
...

Примечание. Поля valid и invalid в FormGroup и FormArray ориентируется на вложенные элементы. И проверив самый верхний можно узнать валидность всех нижестоящих элементов формы. НО! Узлы FormGroup и FormArray имеют cвой набор валидаций и список ошибок (errors, warnings, informationMessages, successes). Т.е. если спросить у FormGroup errors – она выдаст только свои ошибки, но не ошибки на вложенном FormControl.

Библиотека mobx-form-validation-kit позволяет писать пользовательские валидации, но в ней присутствует и собственный набор.

firstName: FormControl(
    value: "",
    options: OptionsFormControl(validators: [
    requiredValidator(),
    minLengthValidator(2),
    maxLengthValidator(5),
    notContainSpacesValidator()
])),

Как можно заметить отработали все валидации в списке, для решения данной проблемы применяется обертка wrapperSequentialCheck. Её вызов и её применение ничем не отличается от обычной функции-валидатора, но на вход она принимает массив из валидаторов которые будут запускаться последовательно, т.е. следующая валидация запустится только после того, как предыдущая прошла без ошибок. Второй функций оберткой является функция управления потоком валидаций. wrapperActivateValidation первым параметром принимает функцию в которой нужно прописать условия активаций валидаций. В отличии от функции activate которая передается в FormControl данная проверка рассчитана на более сложную логику. Предположим, что у нас общий билдер для целой формы FormGroup платежей, и более того на сервере есть только один метод который и принимает общий набор полей. Но вот загвоздка в том, что хоть форма и одна, в зависимости от «типа платежа» мы показываем различный набор полей пользователю. Так вот wrapperActivateValidation позволяет написать логику при которой будут осуществляться различные проверки в зависимости от типа платежа.

firstName: FormControl(
          value: "",
          options: OptionsFormControl(validators: [
            wrapperSequentialCheck([
              requiredValidator(),
              minLengthValidator(2),
              maxLengthValidator(5),
              notContainSpacesValidator()
            ])
          ]))

Пользовательсяка валидация группы.

class FormRange extends ControlsCollection {
  final FormControl<DateTime> min;
  final FormControl<DateTime> max;
  FormRange({this.min, this.max});
  @override
  Iterable<AbstractControl> allFields() => [this.min, this.max];
}

class RegistrationForm extends ControlsCollection {
…
  RegistrationForm(
      {this.firstName, this.lastName, this.email, this.age, this.dateRange});

  @override
  Iterable<AbstractControl> allFields() =>
      [this.firstName, this.lastName, this.email, this.age, this.dateRange];
}

this.form = FormGroup(RegistrationForm(
...
      dateRange: FormGroup<FormRange>(
          FormRange(
              min: FormControl<DateTime>(value: DateTime.now()),
              max: FormControl<DateTime>(value: DateTime.now())),
          options: OptionsFormGroup<FormRange>(validators: [
            (FormGroup<FormRange> group) async {
              if (group.controls.max.value.isBefore(group.controls.min.value)) {
                return [
                  ValidationEvent(
                    message: 'Дата "от" больше даты "до"',
                    type: ValidationEventTypes.Error,
                  )
                ];
              }
              return [];
            },
          ])),    
));

Как видно из примера валидация вешается не на конкретное хотя так тоже можно, а вешается на всю группу целиком. Остается лишь вывести ошибки группы в интерфейсе.

await this.form.wait();
    if (this.form.invalid) {
      this.form.setTouched(true);
      final firstError = this.form.allControls().firstWhere((c) => c.invalid);
      firstError.focusNode.requestFocus();
    }

Понятное дело, что описанным набор возможности библиотеки не ограничиваются. Еще можно рассказать и показать примеры. • Что валидаци отработают не только когда меняется само значение, но и когда поменялась observable переменная внутри валидации. • Как работает метод active • Что FormControl можно инициализовать не только конкретной переменной, но и функцией которая возвращает значение. И изменения внутри этой функции будут также отслеживаться. • Как работать с FormArray • Как делать сложную валидацию с запросами на сервер и при этом всё равно переменные в этой валидации будут отслеживаемыми.

И еще кучу всего, что позволяет из коробки пакет mobx-form-validation-kit.

П.с. Найдете ошибки – пишите, исправим :)