Getting Started with FForm 🌟

Step 1: Installation

First things first, let's get the FForm package into your Flutter project. Add FForm to your pubspec.yaml file under dependencies:

dependencies:
  fform: ^latest_version

Don't forget to run flutter pub get in your terminal to install the package.

Overview

FForm is a high-level Flutter package designed to make form creation and management a breeze, with simplified field validation. It offers two main components: FFormField and FFormBuilder, that together bring ease and flexibility to your form handling in Flutter apps.

• FFormField<T, E>: A base class for all form fields supporting values, on-the-fly validation, and change handling.
• FFormBuilder<F extends FForm>: A widget that constructs and manages the form state, utilizing streams to refresh the UI dynamically as data changes.
• FForm: A base class for creating custom form classes, allowing you to add specific methods and properties to your forms.
• FFormException: A base class for creating custom exceptions for form fields, enabling you to define custom validation rules and error messages.
• FFormProvider: A widget that allows you to access the form in the widget tree without passing it as a parameter.

Why It Rocks 🎸

• State Management Simplified: Automatically handles the state of both individual form fields and the form as a whole.
• Built-in Validation with a Twist: Supports on-the-fly validation and error handling for each field, ensuring a smooth user experience.
• Flexibility at Its Finest: Supports any data type for field values and validation errors thanks to generics.
• Reactive Forms for the Win: Leverages streams for tracking form state changes, ensuring your UI is always in sync.
• Multiple Forms, No Problem: Create multiple forms with custom fields and validation rules, all managed seamlessly by FForm.
• Custom Exceptions for Custom Needs: Define custom exceptions for form fields to handle complex validation rules and error messages with ease.

Previews

Login Form	Add Forms to Multiple Form	Infinity Forms

Usage Examples

FFormField

FFormField is a base class for all form fields, supporting values, on-the-fly validation, and change handling. It provides a set of getters and methods to manage the field state, including checking the field's validity, retrieving the current value, and handling exceptions.

Example

enum EmailError {
  empty,
  not;

  @override
  String toString() {
    switch (this) {
      case empty:
        return 'emailEmpty';
      case not:
        return 'invalidFormatEmail';
      default:
        return 'invalidFormatEmail';
    }
  }
}

class EmailField extends FFormField<String, EmailError> {

  EmailField({required String value}) : super(value);

  @override
  EmailError? validator(value) {
    if (value.isEmpty) return EmailError.empty;
    return null;
  }
}

FFormField API

FForm

FForm is a base class for creating custom form classes with specific fields and validation rules. It provides a set of getters and methods to manage the form state, including checking the form's validity, retrieving answers, and handling exceptions.

Example

This is a simple example of how to create a form with a single field. You can extend the FForm class to create custom forms with specific fields and validation rules.

class LoginForm extends FForm {
  EmailField email;

  LoginForm({
    required this.email,
  });

  @override
  List<FFormField> get fields => [email];
}

This is a more complex example of how to create a form with multiple fields. You can extend the FForm class to create custom forms with specific fields and validation rules.

class Form extends FForm {
  List<Form> forms;

  Form({
    required this.forms,
  });

  @override
  List<FFormField> get subForms => forms;
}

allFieldUpdateCheck is a property in FForm that determines whether every field update triggers a rebuild of the FFormBuilder. When set to true, the form will rebuild on every field update, ensuring real-time feedback to the user. When set to false, the form will only rebuild when the isValid or isInvalid getters are invoked, reducing the number of rebuilds and enhancing performance.

class LoginForm extends FForm {
  EmailField email;

  LoginForm({
    required this.email,
  });

  @override
  bool get allFieldUpdateCheck => true;

  @override
  List<FFormField> get fields => [email];
}

FForm API

FFormBuilder

FFormBuilder is a widget that constructs and manages the form state, utilizing streams to refresh the UI dynamically as data changes. It provides a builder function that takes the form and returns a widget tree based on the form's state.

Example

This is an example of how to use FFormBuilder to create a form with a single field. The builder function takes the form as a parameter and returns a widget tree based on the form's state.

void _submit() {
  if(_form.isValid) { // .isValid or .isInvalid start rebuild in FFormBuilder and returned boolean
    print('Form Valid');
  };
}

@override
Widget build(BuildContext context) {
  return FFormBuilder<LoginForm>(
    form: _form,
    builder: (context, form) {
      EmailField email = form.email; // or FFormProvider.of<LoginForm>(context).get<NameField>()

      return Column(
        children: [
          TextField(
            key: email.key,
            controller: _emailController,
            decoration: InputDecoration(
              labelText: 'Email',
              errorText: email.exception.toString(),
            ),
          ),
          ElevatedButton(
            onPressed: _submit,
            child: const Text('Submit'),
          ),
        ],
      );
    },
  );
}

FFormProvider

FFormProvider is a widget that allows you to access the form in the widget tree without passing it as a parameter.

Example

FFormBuilder<LoginForm>(
  form: _form,
  builder: (context, form) {

    FFormProvider.of<LoginForm>(context).email; // or form.email;
    FFormProvider.of<LoginForm>(context).get<NameField>(); // or form.get<NameField>();

    return YourForm();
  },
)

FFormException

FFormException is a base class for creating custom exceptions for form fields. It allows you to define custom validation rules and error messages for form fields, enabling you to handle complex validation scenarios with ease.

Example

You can create a custom exception class that extends FFormException to define specific validation rules and error messages for a form field.

class PasswordValidationException extends FFormException {
  final bool isMinLengthValid;
  final bool isSpecialCharValid;
  final bool isNumberValid;

  PasswordValidationException({
    required this.isMinLengthValid,
    required this.isSpecialCharValid,
    required this.isNumberValid,
  });

  @override
  bool get isValid => isMinLengthValid && isSpecialCharValid && isNumberValid;
}

class PasswordField extends FFormField<String, PasswordValidationException> {
  PasswordField(String value) : super(value);

  @override
  PasswordValidationException? validator(String value) {
    final validator = FFormValidator(value);
    return PasswordValidationException(
      isMinLengthValid: validator.isMinLength(8),
      isSpecialCharValid: validator.isHaveSpecialChar,
      isNumberValid: validator.isHaveNumber,
    );
  }
}

FFormException API