Merge pull request #14 from netglade/feat/listener-changes

glade_forms/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 1.2.0
+- **[Feat]**: Add `GladeFormListener` widget allowing to listen for model's changes
+- **[Feat]**: Add `groupEdit()` method in GladeModel allows to update multiple inputs at once.
+  - Works great with `GladeFormListener`
+- **[Feat]**: Add `valueTransform` in GladeInput. Transform value before it is assigned into value.
+  - Firstly `stringToTypeConverter` is called if needed, then `valueTransform`.
+- **[Feat]**: Add `updateValue(T value)` as shorthand for inputs when field is not TextField.
+- **[Feat]**: Add `resetToPure` method allowing to reset input into pure state.
+- **[Fix]**: Conversion error does not update model's stats and formatted errors.
+
 ## 1.1.2
 - Fix links in readme
 

glade_forms/README.md

@@ -22,7 +22,8 @@ A universal way to define form validators with support of translations.
   - [Validation](#validation)
     - [Using validators without GladeInput](#using-validators-without-gladeinput)
   - [GladeModel](#glademodel)
-    - [`GladeFormBuilder` and `GladeFormProvider`](#gladeformbuilder-and-gladeformprovider)
+    - [Flutter widgets](#flutter-widgets)
+    - [Edit multiple inputs at once](#edit-multiple-inputs-at-once)
   - [Dependencies](#dependencies)
   - [Controlling other inputs](#controlling-other-inputs)
   - [Translation](#translation)
@@ -125,13 +126,18 @@ On each input we can define
  - **translateError** - If there are validation errors, function for error translations can be provided.
  - **inputKey** - For debug purposes and dependencies, each input can have unique name for simple identification.
  - **dependencies** - Each input can depend on another inputs for validation.
- - **valueConverter** - If input is used by TextField and `T` is not a `String`, value converter should be provided.
+ - **stringTovalueConverter** - If input is used by TextField and `T` is not a `String`, value converter should be provided.
  - **valueComparator** - Sometimes it is handy to provied `initialValue` which will be never updated after input is mutated. `valueComparator` should be provided to compare `initialValue` and `value` if `T` is not comparable type by default. 
+ - **valueTransform** - transform `T` value into different `T` value. An example of usage can be sanitazation of string input (trim(),...).
  - **defaultTranslation** - If error's translations are simple, the default translation settings can be set instead of custom `translateError` method.
  - **textEditingController** - It is possible to provide custom instance of controller instead of default one.
 
 Most of the time, input is created with `.create()` factory with defined validation, translation and other properties.
 
+An overview how each input's value is updated. If needed it is converted from `string` into `T`, then transformed via `valueTransform` (if provided), after that new value is set.
+
+![input-flow-example](https://raw.githubusercontent.com/netglade/glade_forms/main/glade_forms/doc/flow-input-chart.png)
+
 #### StringInput
 
 StringInput is specialized variant of GladeInput<String> which has additional, string related, validations such as `isEmail`, `isUrl`, `maxLength` and more.
@@ -198,10 +204,39 @@ and properties such as `isValid` or `formattedErrors` will not work.
 
 For updating input call either `updateValueWithString(String?)` to update `T` value with string (will be converted if needed) or set `value` directly (via setter).
 
-#### `GladeFormBuilder` and `GladeFormProvider`
+#### Flutter widgets
 
 `GladeModelProvider` is predefined widget to provide `GladeModel` to widget's subtreee.
-Similarly `GladeFormBuilder` allows to listen to model's changes and rebuilts its child. 
+
+`GladeFormBuilder` allows to listen to model's changes and rebuilts its child. 
+
+`GladeFormListener` allows to listen to model's changes and react to it. Useful for invoking side-effects such as showing dialogs, snackbars etc. `listener` provides `lastUpdatedKeys` which is list of last updated input keys. 
+
+`GladeFormConsumer` combines GladeFormBuilder and GladeFormListener together.
+
+#### Edit multiple inputs at once
+With each update of input, via update or setting `.value` directly, listeners (if any) are triggered. Sometimes it is needed to edit multiple inputs at once and triggering listener in the end.
+
+For editing multiple values use `groupEdit()`. It takes void callback to update inputs.
+
+An example
+
+```dart
+class FormModel extends GladeModel {
+  late GladeInput<int> age;
+  late GladeInput<String> name;
+
+  // ....
+
+  groupEdit(() {
+    age.value = 18;
+    name.value = 'default john',
+  });
+}
+
+```
+
+After that listener will contain `lastUpdatedKeys` with keys of `age` and `name` inputs.
 
 ### Dependencies
 Input can have dependencies on other inputs to allow dependent validation. Define input's dependencies with `dependencies`.

glade_forms/example/lib/example.dart

@@ -12,9 +12,9 @@ class _Model extends GladeModel {
 
   @override
   void initialize() {
-    name = GladeInput.stringInput();
-    age = GladeInput.intInput(value: 0);
-    email = GladeInput.stringInput(validator: (validator) => (validator..isEmail()).build());
+    name = GladeInput.stringInput(inputKey: 'name');
+    age = GladeInput.intInput(value: 0, inputKey: 'age');
+    email = GladeInput.stringInput(validator: (validator) => (validator..isEmail()).build(), inputKey: 'email');
 
     super.initialize();
   }
@@ -25,7 +25,7 @@ class Example extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    return GladeFormBuilder(
+    return GladeFormBuilder.create(
       create: (context) => _Model(),
       builder: (context, model, _) => Padding(
         padding: const EdgeInsets.all(32),

glade_forms/lib/src/core/changes_info.dart

@@ -3,7 +3,7 @@ import 'package:glade_forms/src/validator/validator_result.dart';
 
 class ChangesInfo<T> extends Equatable {
   final T? initialValue;
-  final T previousValue;
+  final T? previousValue;
   final T value;
   final ValidatorResult<T>? validatorResult;