flutter-form-builder-ecosystem / form_builder_validators

Form Builder Validators is set of validators for FormFields. It provides common validators and a way to reuse multiple validators
https://pub.dev/packages/form_builder_validators
BSD 3-Clause "New" or "Revised" License
52 stars 98 forks source link
dart flutter form validator

Form Builder Validators

Form Builder Validators set of validators for any FormField widget or widgets that extend the FormField class - e.g., TextFormField, DropdownFormField, et cetera. It provides standard ready-made validation rules and a way to compose new validation rules combining multiple rules, including custom ones.

Also included is the l10n / i18n of error text messages to multiple languages.

Pub Version GitHub Workflow Status Codecov CodeFactor Grade


Call for Maintainers

We are looking for maintainers to contribute to the development and maintenance of Flutter Form Builder Ecosystem. Is very important to keep the project alive and growing, so we need your help to keep it up to date and with new features. You can contribute in many ways, we describe some of them in Support section.

Contents

Features

Validators

This package comes with several most common FormFieldValidators such as required, numeric, mail, URL, min, max, minLength, maxLength, minWordsCount, maxWordsCount, IP, credit card, etc., with default errorText messages.

Bool validators

Collection validators

Core validators

Datetime validators

File validators

Finance validators

Identity validators

Network validators

Numeric validators

String validators

Use-case validators

Extension method validators

Used for chaining and combining multiple validators.

Supported languages

Validators support default errorText messages in these languages:

And you can still add your custom error messages.

Use

Setup

The default error message is in English. To allow for localization of default error messages within your app, add FormBuilderLocalizations.delegate in the list of your app's localizationsDelegates.

return MaterialApp(
    supportedLocales: [
        Locale('de'),
        Locale('en'),
        Locale('es'),
        Locale('fr'),
        Locale('it'),
        ...
    ],
    localizationsDelegates: [
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        FormBuilderLocalizations.delegate,
    ],

Basic use

TextFormField(
    decoration: InputDecoration(labelText: 'Name'),
    autovalidateMode: AutovalidateMode.always,
    validator: FormBuilderValidators.required(),
),

See pub.dev example tab or github code for more details

Specific uses

Composing multiple validators

The FormBuilderValidators class comes with a handy static function named compose(), which takes a list of FormFieldValidator functions. Composing allows you to create once and reuse validation rules across multiple fields, widgets, or apps.

On validation, each validator is run, and if any validator returns a non-null value (i.e., a String), validation fails, and the errorText for the field is set as the returned string.

Example:

TextFormField(
    decoration: InputDecoration(labelText: 'Age'),
    keyboardType: TextInputType.number,
    autovalidateMode: AutovalidateMode.always,
    validator: FormBuilderValidators.compose([
        /// Makes this field required
        FormBuilderValidators.required(),

        /// Ensures the value entered is numeric - with a custom error message
        FormBuilderValidators.numeric(errorText: 'La edad debe ser numérica.'),

        /// Sets a maximum value of 70
        FormBuilderValidators.max(70),

        /// Include your own custom `FormFieldValidator` function, if you want
        /// Ensures positive values only. We could also have used `FormBuilderValidators.min(0)` instead
        (val) {
            final number = int.tryParse(val);
            if (number == null) return null;
            if (number < 0) return 'We cannot have a negative age';
            return null;
        },
    ]),
),

Modify the default error message in a specific language

see override_form_builder_localizations_en for more detail.

Migrations

v10 to v11

v7 to v8

Remove context as a parameter to validator functions. For example, FormBuilderValidators.required(context) becomes FormBuilderValidators.required() without context passed in.

Support

Contribute

You have some ways to contribute to this package.

See the contribution file for more details

Add new supported language

We welcome efforts to internationalize/localize the package by translating the default validation errorText strings for built-in validation rules.

  1. Add ARB files

    Create one ARB file inside the lib/l10n folder for each locale you need to add support. Name the files in the following way: intl_<LOCALE_ISO_CODE>.arb. For example: intl_fr.arb or intl_fr_FR.arb.

  2. Translate the error messages

    Copy and paste the contents of intl_en.arb into your newly created ARB file. Then translate the error messages by overwriting the default messages.

  3. Generate localization code

    To generate boilerplate code for localization, run the generate command inside the package directory where pubspec.yaml file is located:

    flutter gen-l10n

    The command will automatically create/update files inside the lib/localization directory, including your newly added locale support. The files in here are only necessary for local development and will not be committed to Github.

  4. Update README

    Remember to update README, adding the new language (and language code) under Supported languages section in alphabetic order, so that everyone knows your new language is now supported!

  5. Submit PR

    Submit your PR and be of help to millions of developers all over the world!

Add new validator

  1. Add a new validator to one of the folders in the src folder.
  2. Implement it using the BaseValidator or TranslatedValidator class. Override the validateValue method and let the base class handle the null check in the validate method.
  3. When using a TranslatedValidator, Override thetranslatedErrorTextproperty and return the correct translation fromFormBuilderLocalizations.current.`.
  4. Make sure to pass errorText and checkNullOrEmpty to the base class.
  5. Add static method to form_builder_validators.dart that uses the new validator.
  6. Implement tests
  7. Add to validators with name and description
  8. Add message error translated on all languages (yes, all languages). To accomplish this need: a. Add property to all intl_*.arb files, in alphabetic order. b. Translate message in all languages. c. Run flutter gen-l10n command
  9. Run dart dart fix --apply and dart format .
  10. Submit PR

Questions and answers

You can ask questions or search for answers on Github discussion or on StackOverflow

Donations

Donate or become a sponsor of Flutter Form Builder Ecosystem

Become a Sponsor

Roadmap

Ecosystem

Take a look at our fantastic ecosystem and all packages in there

Thanks to

All contributors