formx 0.36.0 copy "formx: ^0.36.0" to clipboard
formx: ^0.36.0 copied to clipboard

Access, build, format, validate, sanitize and fill forms easily with Form/Field extensions.

Formx #

Image 1 Image 2

Acessing the state #

BuildContext.formx(String key) automatically retrieves FormState by key value.

// specify the form key:
final addressState = context.formx('address'); 

if (addressState.validate()) {
  final map = addressState.toMap();
  addressState.save();
  // do your logic

} else {
  throw FormxException(addressState.errorTexts);
}

You can do the same for a specific field final emailState = context.field('email')

Submit shortcut #

Performs .validate(), .save() and .toMap(). Throws errorTexts if invalid.

// essentially the same as the code above, but in one line
final map = context.submit('address');
final mapOrNull = context.trySubmit('address');

We recommend using it with flutter_async to handle errors effortlessly.

FormState extensions #

  • .toMap({FormxOptions? options}), a structured Map with all the values of the form.
    • Use options to modify the output. If null, the global Formx.options will be used.
    • If a Key is used, it will apply the associated adapter or unmask to the value.
  • .rawValues, a structured Map with all [FormFieldState.value]. Unmodified.
  • .initialValues, a structured Map with all [FormField.initialValue]. Unmodified.
  • .isInitial, whether any nested [FormFieldStateExtension.isInitial].
  • .hasInteractedByUser, whether any nested [FormFieldState.hasInteractedByUser].
  • .hasError, whether any nested [FormFieldState.hasError].
  • .isValid, whether all nested [FormFieldState.isValid].
  • .invalids, a list with all invalid field keys, regardless if validated.
  • .errorTexts, a flat Map with all nested [FormFieldState.errorText].
  • .fill(Map<String, dynamic> map), sets each associated field by it's key-value pair.

FormxState extension type #

FormxState is an inline-class that redeclares some of the FormState methods:

  • .validate([List<String>? keys])
  • .save([List<String>? keys])
  • .reset([List<String>? keys])

These methods function identically to their original counterparts but extend their effects to nested forms. Using FormState.validate only validates the top-level form, whereas FormxState.validate also validates any nested forms.

You have the option to specify a list of keys with these methods to target specific forms or fields for validation, saving, or resetting.

You can redeclare any FormState to a FormxState by using FormxState(formState) type extension.

FormFieldState extensions #

  • .setErrorText(String? errorText), sets the field errorText programmatically. Requires Validator.

FormxSetup #

You can use Formx.setup to set global options for all formx widgets.

  • defaultTitle to set the default title for fields that internally use ListTile.
  • datePicker to pick a date in FormField<DateTime> fields.
  • image/filePicker to pick a file in FormField<XFile> fields.
  • image/filesPicker to pick a file in FormField<List<XFile>> fields.
  • image/fileUploader to upload a file in FormField<XFile> fields.
  • image/fileDeleter to delete a file in FormField<XFile> fields.

FormxOptions #

You can use Formx.options to modify FormState.values output.

  • trim removes leading and trailing whitespaces.
  • unmask removes all [MaskedInputFormatter] masks.
  • nonNull removes all null values.
  • nonEmptyMaps removes all empty maps.
  • nonEmptyStrings removes all empty strings.
  • nonEmptyIterables removes all empty iterables.

By default, all options are enabled, except for [nonEmptyIterables].

To get the unmodified values, use FormState.rawValues.

FieldKey options #

  • .adapter to format the field value.
  • .unmask to (un)mask the field value, regardless of the form global options.
TextFormField(
  key: const Key('age').options(
    unmask: true,
    adapter: (String value) => value?.toInt(),
  ),
),

Validator class #

Looking for a way to create validators declaratively? Validator class provides a readable and declarative approach to defining validation rules for your Dart applications.

TextFormField(
  validator: Validator<String>(
    required: true,
    test: (value) => value.isEmail,
  ),
),

For the one-liners, the modifiers allows you to chain your validators.

TextFormField(
  validator: Validator().required().email(),
),

Customizing #

// You can set a default `requiredText`/`invalidText` for all validators:
Validator.defaultRequiredText = 'This field is required';
Validator.defaultInvalidText = 'This field is invalid';

// You can also modify the errorText of a validator:
Validator.translator = (key, errorText) => errorText; // good for translations

// In case you need to temporarily disable all validators:
Validator.disableOnDebug = true; // only works on debug mode

Modifiers #

  • .test(bool Function(T value) test)
  • .number(bool Function(num value) test)
  • .datetime(bool Function(DateTime value) test)
  • .required
  • .email
  • .url
  • .phone
  • .creditCard
  • .cpf
  • .cnpj
  • .date
  • .alpha
  • .numeric
  • .alphanumeric
  • .hasAlpha
  • .hasNumeric
  • .hasAlphanumeric
  • .hasUppercase
  • .hasLowercase
  • .hasSpecialCharacter
  • .minLength(int length)
  • .maxLength(int length)
  • .minWords(int words)
  • .maxWords(int words)
  • .minNumber(num number)
  • .maxNumber(num number)
  • .isAfter(DateTime date)
  • .isBefore(DateTime date)

Validators, Sanitizers & Helpers extensions #

Formx comes bundled with a set of built-in validators and sanitizers, which you can use to validate and sanitize your form fields.

String #

  • .isPhone
  • .isCpf
  • .isCnpj
  • .numeric (returns the numbers)
  • .alpha (returns the letters)
  • .alphanumeric (returns numbers/letters)
  • .hasAlpha
  • .hasNumeric
  • .hasAlphanumeric
  • .hasUppercase
  • .hasLowercase
  • .hasSpecialCharacters
  • .equalsIgnoreCase(String)

Iterable #

  • .castJson() for casting any List as List<Map<String, dynamic>>.
  • .mapJson() for mapping any jsonList to List
  • .orderedBy(R selector(T), {bool ascending}) for ordering.

Map #

  • .pairs for getting a list of key-value pairs.
  • .indented for a map view that indents when printed.
  • .indentedText for getting an indented text.
  • .deepMap() for mapping nested maps.
  • .clean() for values that are null or empty string/iterable/map.
  • .cleaned() for a new map with all null or empty values removed.

Deeply recases all your map keys:

  • .camelCase "camelCase"
  • .constantCase "CONSTANT_CASE"
  • .sentenceCase "Sentence case"
  • .snakeCase "snake_case"
  • .dotCase "dot.case"
  • .paramCase "param-case"
  • .pathCase "path/case"
  • .pascalCase "PascalCase"
  • .headerCase "Header-Case"
  • .titleCase "Title Case"

Additionally exports recase library. See it for complete list of extensions.

List<Widget> #

  • .keepAlive usually needed for building forms with [PageView.children].
  • .expanded usually needed for building forms with [Column.children] or [Row.children].

Contributing #

Contributions to formx are welcome! Whether it's bug reports, feature requests, or pull requests, all "forms" of collaboration can help make formx better for everyone.

8
likes
150
points
872
downloads

Publisher

verified publisherbranvier.com

Weekly Downloads

Access, build, format, validate, sanitize and fill forms easily with Form/Field extensions.

Homepage
Repository (GitHub)
View/report issues

Topics

#form #extension #validator #formatter #sanitizer

Documentation

API reference

License

MIT (license)

Dependencies

collection, cross_file, flutter, meta, recase

More

Packages that depend on formx