well_formed 0.3.3

A form field package designed to relieve developers of much of the form-related coding. It provides field masking, validation, smart trimming, and more.

well_formed

Contents

• Overview
• Getting Started
  • Form Field in Action
• List of Form Fields by Category
  • Brazil
  • Core
  • Net
  • Numeric
• Demo application
  • Blank Field Error Messages
  • Invalid Inputs
  • Fields With Proper Values
• Left Out Properties
• References

Overview

Well-Formed Widget Fields — Well-Formed is a form field package designed to relieve developers of much of the form-related coding. This is achieved by providing out-of-the-box field masking, validation, smart trimming, and more. In addition, this package aims to:

• improve source code readability by providing form fields with "semantic" names — names that convey their purpose at first glance — such as "EmailField", "CpfField", "DigitField", "IntField", and so on.
• automate the selection of the keyboard type according to the field's purpose.
• not to end up being yet another buggy Flutter form package!

In order to be a reliable package, every class is well-documented and fully unit tested by a CI/CD pipeline with rigorous quality gates.

Getting Started

Most of the form fields in this package are built on top of the TextFormField widget so that they remain fully compatible with Flutter's Form widget. This is important to avoid erroneous (buggy) behavior, such as when a field does not reset when its parent widget is reset.

Besides most of the TextFormField properties, additional properties have been introduced to facilitate the creation of "Smarter" form fields with stunning capabilities such as:

• Fields can easily be made mandatory (required) by just filling in the blank property with text.
• Automatic field masking. For example (where each '#' is a digit [0–9]):
• CepField — '#####-##'; CpfField — '###.###.###-##'; CnpjField — '##.###.###/####-##'; BrMobileField — '(##) #####-####'; and so on.
• Stripping: this is the optional removal of non-digit characters. It is enabled by default. To disable it, simply set the strip property to false while instantiating a form field object.
• Smart trimming: this is when trimming is also applied to form field callback functions. The affected callback functions are onSaved, onChanged, and onFieldSubmitted. To enable it, simply set the trim property to true while instantiating a form field object.
• Validation with custom error messages (blank, malformed, long, etc.).
• Automatic keyboard type selection: the most suitable keyboard type is selected according to the field type. For example, the EmailFiel class sets the keyboardType to TextInputType.emailAddress, which in turn is optimized for email addresses.

Form Field in Action

The code below demonstrates how to use the EmailField widget with the trim property set to true so that the entered email value is trimmed before being validated. Furthermore, the example also illustrates some important features:

• auto validation
• error messages
• length constraint

  …
  // the form's mandatory state key
  final formKey = GlobalKey<FormState>();
  …
  @override
  Widget build(BuildContext context) {
    return Form(
      key: _formKey,
      child: Column(children: [
        EmailField.len(
          50, // limits the length to up to 50 characters
          trim: true, // trims the entered email
          blank: 'Inform the email', // error message if the field is left blank
          malformed: 'Invalid email', // error message if the email is invalid
          long: 'The email is too long', // error message for long emails
          decoration: const InputDecoration(
            labelText: 'Enter an email with up to 50 characters',
          ),
        ),
      ]),
    );
  }

List of Form Fields

The list of form fields with detailed information about each one (constructors, parameters, etc.):

• well_formed.

Brazil

Form fields related to Brazil. Each '#' represents a digit [0–9].

• BrMobileField — a masked (##) #####-#### form field for Brazilian mobile numbers.
• BrPhoneField — a masked (##) ####-#### form field for Brazilian landline telephone numbers.
• CepField — a masked #####-### form field for CEP (Código de Endereçamento Postal).
• CnpjField — masked ##.###.###/####-## form field for CNPJ (Cadastro Nacional da Pessoa Jurídica).
• CpfField — a masked ###.###.###-## form field for CPF (Cadastro da Pessoa Física).

Core

Core components.

• BasicTextField — a text form field that can be made required and/or have its input data trimmed.
• WellFormed — a convenient and well-formed form widget! It builds a Form widget within a structure consisting of SafeArea and Column widgets.

Net

Internet related form fields.

EmailField — form field optimized for emails. You can limit the length of an email by using the EmailField.len constructor.

Numeric

Numeric — form fields related to numbers or digits. Example of numeric inputs: a three-digit code; a six-digit password; a hexadecimal value; the Minimum Order Quantity of a product; and so on.

DigitField — digit-only form field. You can constrain the number of digits in several ways:

• to a fixed number of digits through the DigitField.len constructor;
• to a minimum number of digits through the DigitField.min constructor;
• to a maximum number of digits through the DigitField.max constructor;
• within a range through the DigitField.range constructor.

IntField — integer values form field. You can constrain the allowed values in several ways:

• to positive values through the IntField.pos constructor;
• to negative values through the IntField.neg constructor;
• to values greater than or equal to a minimum value through the IntField.min constructor;
• to values less than or equal to a maximum value through the IntField.max constructor;
• within a range through the IntField.range constructor.

NumField — floating-point values form field. You can constrain the allowed values in several ways:

• to positive values through the NumField.pos constructor;
• to negative values through the NumField.neg constructor;
• to values greater than or equal to a minimum value through the NumField.min constructor;
• to values less than or equal to a maximum value through the NumField.max constructor;
• within a range through the NumField.range constructor.

Demo application

The demo application provides a fully working example, focused on demonstrating exactly five widgets in action — WellFormed, DigitField, IntField, EmailField, and CpfField. You can take the code in this demo and experiment with it.

To run the demo application:

git clone https://github.com/dartoos-dev/well_formed.git
cd well_formed/example/
flutter run -d chrome

This should launch the demo application on Chrome in debug mode.

Blank Field Error Messages

Invalid Inputs

Fields With Proper Values

Left out Properties

Regarding compatibility with the TextFormField class, some properties were left out for one of two reasons:

• the property has been deprecated by the Flutter sdk. This is the case of the autovalidate and maxLengthEnforced properties.
• the property has been considered too superfluous — they have little use in the context of form fields. This is the case of the following properties (A–Z):

Brightness? keyboardAppearance,
Color? cursorColor,
FocusNode? focusNode,
GestureTapCallback? onTap,
InputCounterWidgetBuilder? buildCounter,
Iterable<String>? autofillHints,
MaxLengthEnforcement? maxLengthEnforcement,
Radius? cursorRadius,
ScrollController? scrollController,
ScrollPhysics? scrollPhysics,
SmartDashesType? smartDashesType,
SmartQuotesType? smartQuotesType,
StrutStyle? strutStyle,
TextAlignVertical? textAlignVertical,
TextCapitalization textCapitalization = TextCapitalization.none,
TextInputType? keyboardType,
TextSelectionControls? selectionControls,
ToolbarOptions? toolbarOptions,
bool autofocus = false,
bool enableSuggestions = true,
bool expands = false,
bool? showCursor,
double cursorWidth,
double? cursorHeight,
int? maxLines,
int? minLines,

References

• TextFormField
• build a Flutter form
• Mozilla input types