FormController

Coordinates validation and submission for one mounted Form.

Learn more: Forms & validation

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

// A State field; dispose it with the state.
final form = FormController();

// In build: rebuild on submission progress and submit from the button.
NotifierBuilder(
  notifier: form,
  builder: (context, form) => Form(
    controller: form,
    onSubmit: save, // async: the form stays busy until it completes
    child: Column(
      children: [
        FormField(
          validator: () => name.text.trim().isEmpty ? 'Enter a name.' : null,
          child: TextInput(controller: name),
        ),
        Button(
          text: form.isBusy ? 'Saving…' : 'Save',
          onPressed: form.isBusy ? null : form.submit,
        ),
      ],
    ),
  ),
)

Details

A controller owns no field values. Application state remains the source of truth; the controller only drives the form that is currently attached to it. Create it once in State, pass it to Form, and dispose it alongside that state when external access is useful. Omit it for forms that submit through Form.of from inside their subtree.

Constructors

FormController()

This constructor has no public parameters.

Source

FormController is defined in packages/fleury/lib/src/catalog/form.dart.

Category: Forms · All widgets

Live demo

save_project.dart

Restart Run Expand

Example · editable Revert Format

import 'package:fleury/fleury_core.dart';

// A local service simulation; this demo sends no requests.
enum SaveScenario { success, nameTaken, offline }

enum SaveReply { saved, nameTaken }

class ServiceUnavailable implements Exception {}

Future<SaveReply> simulateSave(
  String name,
  SaveScenario scenario,
) async {
  await Future<void>.delayed(const Duration(seconds: 1));
  if (scenario == SaveScenario.offline) {
    throw ServiceUnavailable();
  }
  return scenario == SaveScenario.nameTaken
      ? SaveReply.nameTaken
      : SaveReply.saved;
}

class SaveProject extends StatefulWidget {
  const SaveProject({super.key, this.save = simulateSave});

  final Future<SaveReply> Function(String, SaveScenario)
  save;

  @override
  State<SaveProject> createState() => _SaveProjectState();
}

class _SaveProjectState extends State<SaveProject> {
  final form = FormController();
  final name = TextEditingController(text: 'Atlas');
  SaveScenario scenario = SaveScenario.success;
  String? nameError;
  String status = 'Ready to save';

  Future<void> save() async {
    // Snapshot the submitted value before the asynchronous work.
    final submittedName = name.text.trim();
    setState(() => status = 'Saving $submittedName…');
    try {
      final reply = await widget.save(
        submittedName,
        scenario,
      );
      if (!mounted) return;
      if (reply == SaveReply.nameTaken) {
        setState(() {
          nameError = 'That name is taken. Try another.';
          status = 'Choose another name';
        });
        // submit() applies this error, focuses Name, and returns false.
        return;
      }
      // Success-only actions (including closing a dialog) belong here.
      setState(() => status = 'Saved $submittedName');
    } on ServiceUnavailable {
      if (mounted) {
        setState(
          () => status =
              'Offline. Your draft is kept. Retry.',
        );
      }
      rethrow; // An awaiting caller must not mistake this for success.
    }
  }

  Future<void> submit() async {
    try {
      await form.submit();
    } on ServiceUnavailable {
      // save() already displayed this expected failure. Keep the UI open.
    }
  }

  @override
  void dispose() {
    form.dispose();
    name.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => Padding(
    padding: const EdgeInsets.all(1),
    child: NotifierBuilder(
      notifier: form,
      builder: (context, _) => Column(
        mainAxisSize: MainAxisSize.min,
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          const Text('Simulated server response'),
          Select<SaveScenario>(
            semanticLabel: 'Server response',
            value: scenario,
            onChanged: form.isBusy
                ? null
                : (value) =>
                      setState(() => scenario = value),
            options: const [
              SelectOption(
                value: SaveScenario.success,
                label: 'Success',
              ),
              SelectOption(
                value: SaveScenario.nameTaken,
                label: 'Name taken',
              ),
              SelectOption(
                value: SaveScenario.offline,
                label: 'Offline',
              ),
            ],
          ),
          const SizedBox(height: 1),
          Form(
            controller: form,
            onSubmit: save,
            child: Column(
              mainAxisSize: MainAxisSize.min,
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                const Text('Name'),
                FormField(
                  error: nameError,
                  validator: () => name.text.trim().isEmpty
                      ? 'Enter a project name.'
                      : null,
                  child: TextInput(
                    controller: name,
                    semanticLabel: 'Name',
                    readOnly: form.isSubmitting,
                    onChanged: (_) =>
                        setState(() => nameError = null),
                    onSubmit: (_) => submit(),
                  ),
                ),
                const SizedBox(height: 1),
                Button(
                  text: form.isBusy ? 'Saving…' : 'Save',
                  onPressed: form.isBusy ? null : submit,
                ),
              ],
            ),
          ),
          const SizedBox(height: 1),
          Text(status),
        ],
      ),
    ),
  );
}

Live preview

Live · interactive

click & type to interact ⓘ how this demo runs ⛶ Expand