well_formed #

EO-Color logo

Contents #

Overview
Getting Started
- Form Field in Action
List of Form Fields by Category
- Brazil
- Core
  - BasicTextField
  - WellFormed
- Net
  - EmailField
- Numeric
  - DigitField
  - HexField
  - IntField
  - NumField
Demo application
Left Out Properties
References

Overview #

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:

help developers to always keep the users' data well-formed.
reduce most of the code related to form fields and their validations.
improve source code readability by providing form fields with semantic names; that is, names that convey their purpose at first glance like EmailField, Ipv4Field, UrlField, and so on.
automate the selection of the keyboard type according to the field's purpose.

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 the Form widget. This is important to avoid erroneous (buggy) behavior, such as when a field does not reset when its parent Form widget is reset.

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

Fields that can easily be made required (mandatory): you have just to set the blank property with some text. This property is the error message that will be displayed if the user leaves the field blank.
Automatic field masking. For example, the
CpfField form field displays the mask '###.###.###-##' (where each '#' is a single digit [0–9]) while the user is entering the digits. Therefore, if the user enters '999999999', the displayed text will be '999.999.999-99'.
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.
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.
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 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.

Most of the fields in the Brazil library are masked fields; so whenever you see a '#' character in the documentation, think of it as a placeholder for a single digit [0–9].

BrMobileField

BrMobileField is a masked (##) #####-#### form field for Brazilian mobile numbers.

BrMobileField(
  strip: true, // remove non-digit characters when submitted/saved/changed.
  blank: 'Please enter the mobile number', // the error message if the field is left blank
  malformed: 'Invalid mobile number', // the error message if the number is invalid
  decoration: InputDecoration(labelText: 'Enter a mobile number'),
);

BrPhoneField

BrPhoneField is a masked (##) ####-#### form field for Brazilian landline telephone numbers.

BrPhoneField(
  strip: true, // remove non-digit characters when submitted/saved/changed.
  blank: 'Please enter the phone number', // the error message if the field is left blank
  malformed: 'Invalid phone number', // the error message if the number is invalid
  decoration: InputDecoration(labelText: 'Enter a phone number'),
);

CepField

CepField is a masked #####-### form field for CEP (Código de Endereçamento Postal — Brazilian Postal Code).

CepField(
  strip: true, // remove non-digit characters when submitted/saved/changed.
  blank: 'Please enter the CEP', // the error message if the field is left blank
  malformed: 'Invalid CEP', // the error message if the CEP is invalid
  decoration: InputDecoration(labelText: 'Enter a CEP'),
);

CnpjField

CnpjField is a masked ##.###.###/####-## form field for CNPJ (Cadastro Nacional da Pessoa Jurídica — Brazilian Company's Registered Number).

CnpjField(
  strip: true, // remove non-digit characters when submitted/saved/changed.
  blank: 'Please enter the CNPJ', // the error message if the field is left blank
  malformed: 'Invalid CNPJ', // the error message if the CNPJ is invalid
  decoration: InputDecoration(labelText: 'Enter a CNPJ'),
);

CpfField

CpfField is a masked ###.###.###-## form field for CPF (Cadastro da Pessoa Física; it is a kind of social security number).

CnpjField(
  strip: true, // remove non-digit characters when submitted/saved/changed.
  blank: 'Please enter the CPF', // the error message if the field is left blank
  malformed: 'Invalid CPF', // the error message if the CPF is invalid
  decoration: InputDecoration(labelText: 'Enter a CPF'),
);

Core #

Core components.

BasicTextField

BasicTextField is a text form field that can be made required and/or have its input data trimmed.

BasicTextField.max(
  50, // limits the length to 50 charactes
  trim: true, // trims the entered data when submitted/saved/changed.
  blank: 'Please enter your full name', // the error message if the field is left blank
  great: 'The name is too long', // the error message if the number of chars is greater than 50
  decoration: InputDecoration(labelText: 'Enter your full name (up to 50 chars)'),
);

WellFormed

WellFormed is 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

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

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: InputDecoration(
    labelText: 'Enter an email with up to 50 characters',
  ),
),

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

DigitField is a digit-only form field. It is ideal for verification code, PIN numbers, etc. Example of valid entries: 0123, 1111, 090909.

DigitField(
  blank: 'Please enter the verification code', // the error message if the field is left blank
  malformed:'non-digit character(s)' // the error message for malformed data.
  decoration: InputDecoration(labelText: 'Verification code'),
);

You can constrain the number of digits in several ways through constructors:

DigitField.len for a fixed number of digits.
DigitField.min for a minimum number of digits.
DigitField.max for a maximum number of digits.
DigitField.range for a range.

HexField

HexField is a hexadecimal form field. It accepts the digits 0–9 and the letters 'AaBbCcDdEeFf'. Example of valid entries: 123, 45fe, CafeBabe.

HexField(
  blank: 'Please enter the device number', // the error message if the field is left blank
  malformed:'non-hex character(s)' // the error message for malformed data.
  decoration: InputDecoration(labelText: 'Enter a device hex number'),
);

You can constrain the number of hex digits in several ways through constructors:

HexField.len for a fixed number of hex digits.
HexField.min for a minimum number of hex digits.
HexField.max for a maximum number of hex digits.
HexField.range for a range.

IntField

IntField is the form field for integers. It is ideal for entering the quantity of an item, number of children, age, etc.

IntField(
  blank: 'Please enter the number of items to purchase', // the error message if the field is left blank
  malformed:'non-digit character(s)' // the error message for malformed data.
  decoration: InputDecoration(labelText: 'Number of items'),
);

You can constrain the allowed values in several ways through constructors:

IntField.pos for positive integers.
IntField.neg for negative integers.
IntField.min for values greater than or equal to a minimum integer value
IntField.max for values less than or equal to a maximum integer value.
IntField.range for a range of integer values.

NumField

NumField is the floating-point form field. It is ideal for displaying the total price of a shopping cart, getting an auction bid, etc.

NumField(
  blank: 'Please enter your bid amount', // the error message if the field is left blank
  malformed:'non-numeric character(s)' // the error message for malformed data.
  decoration: InputDecoration(labelText: 'Your bid amount'),
);

You can constrain the allowed values in several ways:

NumField.pos for positive numbers.
NumField.neg for negative numbers.
NumField.min for values greater than or equal to a minimum numbers
NumField.max for values less than or equal to a maximum numbers.
NumField.range for a range.

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.

well_formed_demo_app

Blank Field Error Messages #

blank-fields

Invalid Inputs #

invalid-inputs

Fields With Proper Values #

valid-inputs

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 — it has little use in the context of form fields. This is the case of the following properties:

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,
TextSelectionControls? selectionControls,
ToolbarOptions? toolbarOptions,
bool autofocus,
bool enableSuggestions,
bool expands,
bool? showCursor,
double cursorWidth,
double? cursorHeight,
int? maxLines,
int? minLines,

well_formed 0.3.6
well_formed: ^0.3.6 copied to clipboard

Metadata

well_formed #

Contents #

Overview #

Getting Started #

Form Field in Action #

List of Form Fields #

Brazil #

BrMobileField

BrPhoneField

CepField

CnpjField

CpfField

Core #

BasicTextField

WellFormed

Net #

EmailField

Numeric #

DigitField

HexField

IntField

NumField

Demo application #

Blank Field Error Messages #

Invalid Inputs #

Fields With Proper Values #

Left out Properties #

References #

← Metadata

Publisher

Metadata

License

Dependencies

More

well_formed 0.3.6 well_formed: ^0.3.6 copied to clipboard

Metadata

well_formed #

Contents #

Overview #

Getting Started #

Form Field in Action #

List of Form Fields #

Brazil #

BrMobileField

BrPhoneField

CepField

CnpjField

CpfField

Core #

BasicTextField

WellFormed

Net #

EmailField

Numeric #

DigitField

HexField

IntField

NumField

Demo application #

Blank Field Error Messages #

Invalid Inputs #

Fields With Proper Values #

Left out Properties #

References #

← Metadata

Publisher

Metadata

License

Dependencies

More

well_formed 0.3.6
well_formed: ^0.3.6 copied to clipboard