example/README.md

Pixl Forms Example #

This example will guide you through creating a form and generating the necessary functionality to manage form state using the pixl_forms library. For more detailed instructions, see the documentation.

Example #

Step 1: Define Your Form

Create a form class and annotate it with @UIForm. This will generate all the needed functionality for managing form state when you run the build_runner.

import 'package:pixl_forms/forms.dart';

part 'login_form.g.dart';

@UIForm(fields: [
  UIField(name: 'email'),
  UIField(name: "password"),
])
class LoginFormVm extends $LoginFormVm with LoggerMixin {
  LoginFormVm();

  @override
  String? emailValidator(String? value, FormValue formState) {
    return Validator(value: value).notEmpty().email().validate();
  }

  @override
  String? passwordValidator(String? value, FormValue formState) {
    return Validator(value: value)
        .minLength(7)
        .custom(Validator.password)
        .validate();
  }
}

Step 2: Extend with Custom Validators

Optionally, use the PixlValidator class for field validations. Developers can extend PixlValidator to add their own customized validations.

class Validator extends PixlValidator {
Validator({required super.value});

static String? password(value) {
    if (value == null || value.isEmpty) {
    return 'Password cannot be empty';
    }

    if (value.length < 7) {
      return 'Password must be at least 7 characters';
    }

    if (!RegExp(r'[A-Z]').hasMatch(value)) {
      return 'Password must contain at least one uppercase letter';
    }

    return null;

    }
}

Step 3: Create a FormBuilder Widget

Use the UIFormBuilder widget to wrap your form fields. This widget uses a ChangeNotifierProvider to listen to form changes and adds a submit handler.

class LoginFormBuilder extends StatelessWidget {
  final Widget Function(BuildContext context, LoginFormVm form) builder;
  const LoginFormBuilder({super.key, required this.builder});

  @override
  Widget build(BuildContext context) {
    return UIFormBuilder(
      name: "login",
      vm: LoginFormVm(),
      onSaved: (type) {
        // Callback for field save
      },
      onSubmitError: (error) {
        // Callback to handle errors
      },
      onSubmit: (form) async {
        // Callback for handling submit
        return Future(() => true);
      },
      builder: (context, form) {
        // You could implement your form widget here.
        // We use a callback builder to be able to pass
        // different widgets as children
        return builder(context, form);
      }
    );
  }
}

Step 4: Create Your Form Widget

Create a widget to display the form. Use the useForm hook to get access to the form state provided by the LoginFormBuilder.

class LoginForm extends StatelessWidget {
  const LoginForm({super.key});

  @override
  Widget build(BuildContext context) {
    // Get access to the form state provided in the LoginFormBuilder
    final form = useForm<LoginFormVm>(context, listen: true);

    return Column(
      children: [
        UIInput(
          label: "Email",
          placeholder: "Email",
          controller: form.email.controller,
          validator: form.email.validator,
        ),
        UIInput(
          label: "Password",
          placeholder: "Password",
          controller: form.password.controller,
          validator: form.password.validator,
          hideErrorMessage: false,
        ),
        UIButton(
          text: "Login",
          onTap: () {
            form.submit();
          },
        ),
      ],
    );
  }
}

This example provides a clear and concise walkthrough for creating a form using pixl_forms, adding custom validators, and handling form submission. For further details and advanced usage, refer to the documentation.