forme 2.5.0-alpha1

forme: ^2.5.0-alpha1 copied to clipboard

Screenshot #

migrate from 2.1.x to 2.5.0 #

Forme 2.5.0 has lots of changes

1. support asyncValidator on ValueField
2. validate from FormeValueFieldController will return Future<String?>? instead of String?
3. validate from FormeController will return Future<Map<FormeValueFieldController>,String> instead of Map<FormeValueFieldController,String>
4. ValueField is not a subclass of FormField any more
5. you can easily detect whether a ValueField's value is nullable from ValueField's generic type, eg ValueField<String>'s value is a nonnull String , ValueField<String?>'s value is a nullable String
6. remove fieldValueListenable from FormeFieldController
7. remove lazyFieldValueListenable from FormeKey

Simple Usage #

add dependency #

flutter pub add forme

create forme #

FormeKey key = FormeKey();// formekey is a global key , also can be used to control form
Widget child = formContent;
Widget forme = Forme(
	key:key,
	child:child,
)

Forme Attributes #

Differences Between Form and Forme #

Forme is a form widget, but forme is not wrapped in a Form , because I don't want to refresh whole form after field's value changed or a validate performed , so it is a bit more complexable than Form.

Forme Fields #

field type #

-StatefulField
	- ValueField
	- CommonField

attributes supported by all stateful fields #

attributes supported by all value fields #

currently supported fields #

fields from other package #

1. forme_cupertino_fields cupertino style fields

Forme Model #

you can update a widget easily with FormeModel

eg: if you want to update labelText of a FormeTextField, you can do this :

FormeFieldController controller = formKey.field(fieldName);
controller.update(FormeTextFieldModel(decoration:InputDecoration(labelText:'New Label')));

if you want to update items of FormeDropdownButton:

controller.updateModel(FormeDropdownButtonModel<String>(
	icon: SizedBox(
	width: 14,
	height: 14,
	child: CircularProgressIndicator(),
)));
Future<List<DropdownMenuItem<String>>> future =
	Future.delayed(Duration(seconds: 2), () {
	return FormeUtils.toDropdownMenuItems(
		['java', 'dart', 'c#', 'python', 'flutter']);
	});
future.then((value) {
controller.updateModel(FormeDropdownButtonModel<String>(
	icon: Icon(Icons.arrow_drop_down), items: value));
});

update model will auto copywith old model's attribute

Custom way display error text #

if default error text display can not fit your needs , you can implementing a custom error display via ValueField's onErrorChanged or FormeValueFieldController's errorTextListenable

don't forget to set Forme's quieltyValidate attribute to true

via onErrorChanged #

onErrorChanged will triggered whenever errorText of field changes , it is suitable when you want to update a stateful field according to error state of field

eg: change border color when error state changes

FormeTextField(
	validator: validator,
	onErrorChanged: (m, a) {
		InputBorder border = OutlineInputBorder(
				borderRadius: BorderRadius.circular(30.0),
				borderSide: BorderSide(color: a == null ? Colors.green : Colors.red, width: 1));
		m.updateModel(FormeTextFieldModel(
			decoration: InputDecoration(
				focusedBorder: border, enabledBorder: border)));
	},
),

via errorTextListenable #

errorTextListenable is more convenient than onErrorChanged sometimes.

eg: when your want to display an valid or invalid suffix icon according to error state of field, in onErrorChanged , update model will rebuild whole field, but with errorTextListenable, you can only rebuild the suffix icon, below is an example to do this:

suffixicon: Builder(
	builder: (context) {
		FormeValueFieldController<String, FormeModel>
			controller = FormeFieldController.of(context);
		return ValueListenableBuilder<FormeValidateError?>(
			valueListenable: controller.errorTextListenable,
			child: const IconButton(
				onPressed: null,
				icon: const Icon(
				Icons.check,
				color: Colors.green,
				)),
			builder: (context, errorText, child) {
			if (errorText == null)
				return SizedBox();
			else
				return errorText.isPresent
					? const IconButton(
						onPressed: null,
						icon: const Icon(
						Icons.error,
						color: Colors.red,
						))
					: child!;
			});
	},
),

listenable #

there are five listenables in field

1. focusListenable
2. readOnlyListenable
3. errorTextListenable
4. valueListenable
5. modelListenable

get listenable #

you can get focusListenable and readOnlyListenable from FormeFieldController, get valueListenable and errorTextListenable from FormeValueFieldController

FormeTextField(
	decoratorBuilder:FormeDecoratorBuilder(),//decorator is a part of field 
	mode:FormeTextFieldModel(
		decoration:InputDecoration(
			suffixIcon: Builder(builder: (context) {
				FormeFieldController controller = FormeFieldController.of(context);
				return ValueListenable<bool>(valueListenable:controller.		valueListenable,builder:(context,focus,child){
					if(focus) return Icon(Icons.clear);
					return SizedBox();
				})
			}),
		),
	),
)

validate #

sync validate #

sync validate is supported by FormeValidates

when you use validators from FormeValidates , you must specific at least one errorText , otherwise errorText is an empty string

async validated #

async validator is supported after Forme 2.2.0 , you can specific an asyncValidator on ValueField , the unique difference between validator and asyncValidator is asyncValidator return a Future and validator return a String

when perform a asyncValidator

if FormField.autovalidateMode is AutovalidateMode.disabled , asyncValidator will never be performed unless you call validate from FormeValueFieldController manually.

if you specific both validator and asyncValidator , asyncValidator will only be performed after validator passed.

if you specific an asyncValidateConfiguration on ValueField and names attribute is not empty , when field's (which name is in names) value changed , asyncValidator will be performed if last validation is validated by asyncValidator.

debounce

you can specific a debounce on asyncValidateConfiguration , debounce will not worked when you manually call validate on FormeValueFieldController

FormeKey Methods #

whether form has a name field #

bool hasField = formeKey.hasField(String name);

whether current form is readOnly #

bool readOnly = formeKey.readOnly;

set readOnly #

formeKey.readOnly = bool readOnly;

get field's controller #

T controller = formeKey.field<T extends FormeFieldController>(String name);

get value field's controller #

T controller = formeKey.valueField<T extends FormeValueFieldController>(String name);

get form data #

Map<String, dynamic> data = formeKey.data;

validate #

since 2.2.0 , this method will return a Future ranther than a Map

Future<Map<FormeValueFieldController,String>> errorsFuture = formKey.validate({bool quietly = false});

set form data #

formeKey.data = Map<String,dynamic> data;

reset form #

formeKey.reset();

save form #

formeKey.save();

whether validate is quietly #

bool quietlyValidate = formKey.quietlyValidate;

set quietlyValidate #

formeKey.quieltyValidate = bool quietlyValidate;

Forme Field Methods #

get forme controller #

FormeController formeController = field.formeController;

get field's name #

String name = field.name

whether current field is readOnly #

bool readOnly = field.readOnly;

set readOnly on field #

field.readOnly = bool readOnly;

whether current field is focused #

bool hasFocus = field.hasFocus;

focus|unfocus current Field #

field.requestFocus();
field.unfocus();

focus next #

field.nextFocus();

set field model #

field.model = FormeModel model;

update field model #

field.updateModel(FormeModel model);

get field model #

FormeModel model = field.model;

ensure field is visible in viewport #

Future<void> result = field.ensureVisibe({Duration? duration,
      Curve? curve,
      ScrollPositionAlignmentPolicy? alignmentPolicy,
      double? alignment});

get focusListenable #

ValueListenable<bool> focusListenable = field.focusListenable;

get readOnlyListenable #

ValueListenable<bool> readOnlyListenable = field.readOnlyListenable;

get modelListenable #

ValueListenable<FormeModel> modelListenable = field.modelListenable;

Forme Value Field Methods #

FormeValueFieldController is extended FormeFieldController

get field value #

dynamic value = valueField.value;

set field value #

valueField.value = dynamic data;

reset field #

valueField.reset();

validate field #

since 2.2.0 , this method will return a Future ranther than a String

Future<String?>? errorFuture = valueField.validate({bool quietly = false});

get error #

FormeValidateError? error = valueField.error;

get decorator controller #

FormeDecoratorController decoratorController = valueField.decoratorController;

get errorTextListenable #

ValueListenable<FormeValidateError?>  errorTextListenable = valueField.errorTextListenable;

get valueListenable #

ValueListenable<dynamic> valueListenable = valueField.valueListenable;

get oldValue #

dynamic value = valueField.oldValue;

build your field #

1. create your FormeModel , if you don't need it , use FormeEmptyModel instead
2. create your ValueField<T,E> , T is your field return value's type, E is your FormeModel's type
3. if you want to create your custom State,extends ValueFieldState<T,E>

links below is some examples to help you to build your field

common field #

1. https://github.com/wwwqyhme/forme/blob/main/lib/src/field/forme_visible.dart
2. https://github.com/wwwqyhme/forme/blob/main/lib/src/field/forme_flex.dart

value field #

1. https://github.com/wwwqyhme/forme/blob/main/lib/src/field/forme_filter_chip.dart
2. https://github.com/wwwqyhme/forme/blob/main/lib/src/field/forme_radio_group.dart