From e522e3db0e12ee84494cd06828acaf0b536ac2e0 Mon Sep 17 00:00:00 2001 From: Jacques Doeleman Date: Wed, 28 Sep 2022 11:51:28 +0200 Subject: [PATCH] Updated readme and small clean up --- README.md | 77 ++++++++++++------- example/lib/form_example.dart | 2 +- lib/flutter_form.dart | 2 +- lib/{shell_form.dart => src/form.dart} | 24 +++--- .../input_carousel/input_carousel.dart | 4 +- .../input/input_types/input_email.dart | 4 +- .../input_password/input_password.dart | 2 +- .../input/input_types/input_plain_text.dart | 6 +- .../input_slider/input_slider.dart | 4 +- 9 files changed, 71 insertions(+), 54 deletions(-) rename lib/{shell_form.dart => src/form.dart} (97%) diff --git a/README.md b/README.md index 02fe8ec..186e1f6 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,60 @@ - - -TODO: Put a short description of the package here that helps potential users -know whether this package might be useful for them. +Flutter Form is a package you can use to create a single or multi page form with premade or custom inputfields. ## Features -TODO: List what your package can do. Maybe include images, gifs, or videos. +Single or multi page form with the ability to define the navigational buttons. +A handfull premade fields with their own controllers. +Full posibilty to create custom inputfields and controllers which can be used along side the premade fields and controllers. +A checkpage where the end user can check his answers and jump back to the page of an inputfield to change his answer without going through the whole form. +The look of the checkpage answers can be set own desire. -## Getting started +## Setup -TODO: List prerequisites and provide or point to information on how to -start using the package. +To use this package, add `flutter_form` as a [dependency in your pubspec.yaml file](https://flutter.dev/docs/development/platform-integration/platform-channels). -## Usage +## How To Use -TODO: Include short and useful examples for package users. Add longer examples -to `/example` folder. +See the [Example Code](example/lib/form_example.dart) for an example on how to use this package. -```dart -const like = 'sample'; -``` +WARNING Make sure to define your ShellFormInputControllers above your Flutter Form and not inside each page. This prevents that the used controllers differ from the registered ones. -## Additional information +Flutter Form has two paramaters: options and formController. Each of these parameters' own parameters will be explained in tabels below. -TODO: Tell users more about the package: where to find more information, how to -contribute to the package, how to file issues, what response they can expect -from the package authors, and more. +Options: + +| Parameter | Explaination | +| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| checkPage | If this is set the form will feature a checkpage at the end so the end user can verify and alter his answers. | +| nextButton | The button which is put in the stack of the Form. An onTap has to be implemented and should call to the FormController. Standard call is autoNextStep(). | +| backButton | Same as the nextButton. A widget that is put in the stack of the Form. An onTap has to be implemented and should call to the FormController. Standard call is previousStep(). | +| onFinised | The callback that will be called when the last page is finished. If checkPage is enabled this will call after the checkPage is passed. | +| onNext | The callback that is called when the user finishes a page. PageNumber is also provided. | + +FormController: + +| Parameter | Explaination | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| getFormPageControllers() | The getter to get all FormPageControllers. This should not be needed/called. | +| setFormPageControllers() | The setter for the FormPageControllers. This shoudl not be needed/called. | +| disableCheckPages() | This should be called when the user goes back to a page where the user alters an answer that alters the rest of the form. | +| autoNextStep() | This should be called under the nextButton of the FormOptions if no special actions are required. | +| previousStep() | This should be called under the backButton of the FormOptions. | +| jumpToPage() | A way to jump to a different page if desired. | +| validateAndSaveCurretnStep() | Calling the validate, and possibly save, for the current step. Returns the result of the validate. | +| getCurrentStepResults() | Get the result of the current step. Mostly called after validateAndSaveCurrentStep return true. | +| nextStep() | Called to go to the next step. This is does not do anything else like autoNextStep does do. | +| finishForm() | Calls the onFinished of the form options. | + +## Issues + +Please file any issues, bugs or feature request as an issue on our [GitHub](https://github.com/Iconica-Development/flutter_form/pulls) page. Commercial support is available if you need help with integration with your app or services. You can contact us at [support@iconica.nl](mailto:support@iconica.nl). + +## Want to contribute + +If you would like to contribute to the plugin (e.g. by improving the documentation, solving a bug or adding a cool new feature), please carefully review our [contribution guide](../CONTRIBUTING.md) and send us your [pull request](URL TO PULL REQUEST TAB IN REPO). + +## Author + +`flutter-form` for Flutter is developed by [Iconica](https://iconica.nl). You can contact us at diff --git a/example/lib/form_example.dart b/example/lib/form_example.dart index c6e6844..4593206 100644 --- a/example/lib/form_example.dart +++ b/example/lib/form_example.dart @@ -86,7 +86,7 @@ class _FormExampleState extends ConsumerState { onTap: () => FocusScope.of(context).unfocus(), child: Scaffold( body: Center( - child: ShellForm( + child: FlutterForm( formController: formController, options: ShellFormOptions( onFinished: (Map> results) { diff --git a/lib/flutter_form.dart b/lib/flutter_form.dart index c8536f3..dd5cd60 100644 --- a/lib/flutter_form.dart +++ b/lib/flutter_form.dart @@ -1,4 +1,4 @@ -export 'shell_form.dart'; +export 'src/form.dart'; export 'src/widgets/input/abstractions.dart'; export 'src/widgets/input/input_types/input_types.dart'; export 'src/widgets/page_indicator/page_indicators.dart'; diff --git a/lib/shell_form.dart b/lib/src/form.dart similarity index 97% rename from lib/shell_form.dart rename to lib/src/form.dart index a4474e4..6f09b4b 100644 --- a/lib/shell_form.dart +++ b/lib/src/form.dart @@ -1,13 +1,13 @@ import 'package:flutter/material.dart'; import 'package:flutter_riverpod/flutter_riverpod.dart'; -import 'flutter_form.dart'; -import 'next_shell/form.dart'; -import 'next_shell/translation_service.dart'; -import 'src/utils/form_page_controller.dart'; -import 'src/utils/formstate.dart' as fs; +import '../flutter_form.dart'; +import '../next_shell/form.dart'; +import '../next_shell/translation_service.dart'; +import 'utils/form_page_controller.dart'; +import 'utils/formstate.dart' as fs; /// A wrapper for flutters [Form] that can be controlled by a controller and provides multiple pre-defined input types/fields -/// [ShellForm] also provides multi page forms and a check page for validation. +/// [FlutterForm] also provides multi page forms and a check page for validation. /// /// A [ShellFormController] has to be given to control what happens to values and pages within the ShellForm. /// @@ -175,8 +175,8 @@ import 'src/utils/formstate.dart' as fs; /// ), /// ), /// ``` -class ShellForm extends ConsumerStatefulWidget { - const ShellForm({ +class FlutterForm extends ConsumerStatefulWidget { + const FlutterForm({ Key? key, required this.options, required this.formController, @@ -186,10 +186,10 @@ class ShellForm extends ConsumerStatefulWidget { final ShellFormController formController; @override - ConsumerState createState() => _ShellFormState(); + ConsumerState createState() => _ShellFormState(); } -class _ShellFormState extends ConsumerState { +class _ShellFormState extends ConsumerState { late ShellFormController _formController; @override @@ -428,10 +428,6 @@ class ShellFormController extends ChangeNotifier { disableCheckingPages() { _checkingPages = false; - clearController(); - } - - clearController() { for (var controller in _formPageControllers) { controller.clearControllers(); } diff --git a/lib/src/widgets/input/input_types/input_carousel/input_carousel.dart b/lib/src/widgets/input/input_types/input_carousel/input_carousel.dart index 449efb6..119a1eb 100644 --- a/lib/src/widgets/input/input_types/input_carousel/input_carousel.dart +++ b/lib/src/widgets/input/input_types/input_carousel/input_carousel.dart @@ -6,7 +6,7 @@ import 'package:flutter_form/next_shell/translation_service.dart'; import 'carousel_form.dart'; -/// Input for a carousel of items used in a [ShellForm]. +/// Input for a carousel of items used in a [FlutterForm]. /// /// [items] will be the [Widget]s to be displayed in the carousel. /// @@ -37,7 +37,7 @@ class ShellFormInputCarousel extends ShellFormInputWidget { } } -/// Controller for the carousel used by a [ShellFormInputWidget] used in a [ShellForm]. +/// Controller for the carousel used by a [ShellFormInputWidget] used in a [FlutterForm]. /// /// Mainly used by [ShellFormInputCarousel]. class ShellFormInputCarouselController diff --git a/lib/src/widgets/input/input_types/input_email.dart b/lib/src/widgets/input/input_types/input_email.dart index e646c25..bbb281a 100644 --- a/lib/src/widgets/input/input_types/input_email.dart +++ b/lib/src/widgets/input/input_types/input_email.dart @@ -4,7 +4,7 @@ import 'package:flutter_form/next_shell/translation_service.dart'; import '../../../../flutter_form.dart'; -/// Input for an email used in a [ShellForm]. +/// Input for an email used in a [FlutterForm]. /// /// Standard controller is [ShellFormInputEmailController]. class ShellFormInputEmail extends ShellFormInputWidget { @@ -39,7 +39,7 @@ class ShellFormInputEmail extends ShellFormInputWidget { } } -/// Controller for emails used by a [ShellFormInputWidget] used in a [ShellForm]. +/// Controller for emails used by a [ShellFormInputWidget] used in a [FlutterForm]. /// /// Mainly used by [ShellFormInputEmail]. class ShellFormInputEmailController diff --git a/lib/src/widgets/input/input_types/input_password/input_password.dart b/lib/src/widgets/input/input_types/input_password/input_password.dart index ec7eac6..2c3b82a 100644 --- a/lib/src/widgets/input/input_types/input_password/input_password.dart +++ b/lib/src/widgets/input/input_types/input_password/input_password.dart @@ -3,7 +3,7 @@ import 'package:flutter_form/src/widgets/input/input_types/input_password/passwo import 'package:flutter_riverpod/flutter_riverpod.dart'; import '../../../../../flutter_form.dart'; -/// Input for a password used in a [ShellForm]. +/// Input for a password used in a [FlutterForm]. /// /// Standard controller is [ShellFormInputEmailController]. class ShellFormInputPassword extends ShellFormInputWidget { diff --git a/lib/src/widgets/input/input_types/input_plain_text.dart b/lib/src/widgets/input/input_types/input_plain_text.dart index a31ca32..3c0ad87 100644 --- a/lib/src/widgets/input/input_types/input_plain_text.dart +++ b/lib/src/widgets/input/input_types/input_plain_text.dart @@ -4,7 +4,7 @@ import 'package:flutter_riverpod/flutter_riverpod.dart'; import '../../../../flutter_form.dart'; import 'package:flutter_form/next_shell/translation_service.dart'; -/// Input for plain text input used in a [ShellForm]. +/// Input for plain text input used in a [FlutterForm]. /// /// Standard controller is [ShellFormInputPlainTextController]. class ShellFormInputPlainText extends ShellFormInputWidget { @@ -32,7 +32,7 @@ class ShellFormInputPlainText extends ShellFormInputWidget { } } -/// Input for an plain text with extra styling used in a [ShellForm]. +/// Input for an plain text with extra styling used in a [FlutterForm]. /// /// Standard controller is [ShellFormInputPlainTextController]. class ShellFormInputPlainTextWhiteWithBorder extends ShellFormInputWidget { @@ -73,7 +73,7 @@ class ShellFormInputPlainTextWhiteWithBorder extends ShellFormInputWidget { } } -/// Controller for plain text used by a [ShellFormInputWidget] used in a [ShellForm]. +/// Controller for plain text used by a [ShellFormInputWidget] used in a [FlutterForm]. /// /// Mainly used by [ShellFormInputPlainText]. class ShellFormInputPlainTextController diff --git a/lib/src/widgets/input/input_types/input_slider/input_slider.dart b/lib/src/widgets/input/input_types/input_slider/input_slider.dart index a795c1b..943ea1b 100644 --- a/lib/src/widgets/input/input_types/input_slider/input_slider.dart +++ b/lib/src/widgets/input/input_types/input_slider/input_slider.dart @@ -5,7 +5,7 @@ import 'package:flutter_form/next_shell/translation_service.dart'; import '../../../../../flutter_form.dart'; -/// Input for a number value between two values via a slider. Used in a [ShellForm]. +/// Input for a number value between two values via a slider. Used in a [FlutterForm]. /// /// Standard controller is [ShellFormInputSliderController]. class ShellFormInputSlider extends ShellFormInputWidget { @@ -35,7 +35,7 @@ class ShellFormInputSlider extends ShellFormInputWidget { } } -/// Controller for slider used by a [ShellFormInputWidget] used in a [ShellForm]. +/// Controller for slider used by a [ShellFormInputWidget] used in a [FlutterForm]. /// /// Mainly used by [ShellFormInputSlider]. class ShellFormInputSliderController