Skip to content

Commit 4a00026

Browse files
awhitfordawhitford
committed
Added CodeFactor and Gitter badges. Also editor reformatted a bunch of stuff.
1 parent de1ed38 commit 4a00026

File tree

1 file changed

+98
-69
lines changed

1 file changed

+98
-69
lines changed

‎README.md‎

Lines changed: 98 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -5,32 +5,38 @@ This package helps in creation of Flutter Forms by providing the syntactic sugar
55
[![Pub Version](https://img.shields.io/pub/v/flutter_form_builder?style=for-the-badge)](https://pub.dev/packages/flutter_form_builder)
66
[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/danvick/flutter_form_builder/CI?style=for-the-badge)](https://github.com/danvick/flutter_form_builder/actions?query=workflow%3ACI)
77
[![Codecov](https://img.shields.io/codecov/c/github/danvick/flutter_form_builder?style=for-the-badge)](https://codecov.io/gh/danvick/flutter_form_builder/)
8-
[![GitHub](https://img.shields.io/github/license/danvick/flutter_form_builder?style=for-the-badge)](LICENSE)
8+
[![CodeFactor Grade](https://img.shields.io/codefactor/grade/github/danvick/flutter_form_builder?style=for-the-badge)](https://www.codefactor.io/repository/github/danvick/flutter_form_builder)
9+
10+
[![GitHub](https://img.shields.io/github/license/danvick/flutter_form_builder?style=for-the-badge)](https://github.com/danvick/flutter_form_builder/blob/master/LICENSE)
911
[![OSS Lifecycle](https://img.shields.io/osslifecycle/danvick/flutter_form_builder?style=for-the-badge)](#support)
12+
[![Gitter](https://img.shields.io/gitter/room/danvick/flutter_form_builder?style=for-the-badge)](https://gitter.im/flutter_form_builder/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
1013

1114
[![Youtube Video Tutorial](https://imgur.com/AWzRq5Hl.png)](https://www.youtube.com/watch?v=7FBELQq808M)
1215

1316
[Check out the video tutorial from SyntacOps on Youtube](https://www.youtube.com/watch?v=7FBELQq808M)
1417

1518
## Simple Usage
19+
1620
To use this plugin, add `flutter_form_builder` as a [dependency in your pubspec.yaml file](https://flutter.io/platform-plugins/).
1721

18-
- For Flutter 1.17.x, use version 3.12.x
19-
- For Flutter 1.20.x, use version 3.13.x
20-
- For Flutter 1.22.X, use version 3.14.x
22+
- For Flutter 1.17.x, use version 3.12.x
23+
- For Flutter 1.20.x, use version 3.13.x
24+
- For Flutter 1.22.X, use version 3.14.x
2125

2226
### Example
27+
2328
```dart
2429
final GlobalKey<FormBuilderState> _fbKey = GlobalKey<FormBuilderState>();
2530
```
31+
2632
**Note:** Avoid defining the GlobalKey inside your build method because this will create a new GlobalKey on every build cycle bringing about some erratic behavior.
2733

2834
**Note:** If you use FormBuilderDateTimePicker
35+
2936
```dart
3037
import 'package:intl/intl.dart';
3138
```
3239

33-
3440
```dart
3541
Column(
3642
children: <Widget>[
@@ -204,49 +210,54 @@ Column(
204210
```
205211

206212
## Input widgets
213+
207214
The currently supported fields include:
208-
* `FormBuilderCheckbox` - Single Checkbox field
209-
* ~~`FormBuilderCheckboxList`~~ - List of Checkboxes for multiple selection with options listed vertically.
210-
* `FormBuilderCheckboxGroup` - List of Checkboxes for multiple selection. Unlike in `FormBuilderCheckboxList`, options can either be shown vertically or horizontally.
211-
* `FormBuilderChipsInput` - Takes a list of `Chip`s as input and suggests more options on typing
212-
* `FormBuilderChoiceChip` - Creates a chip that acts like a radio button.
213-
* `FormBuilderColorPicker` - For `Color` input selection
214-
* `FormBuilderCountryPicker` - Country selection from list
215-
* `FormBuilderDateRangePicker` - For selection of a range of dates
216-
* `FormBuilderDateTimePicker` - For `Date`, `Time` and `DateTime` input
217-
* `FormBuilderDropdown` - Used to select one value from a list as a Dropdown
218-
* `FormBuilderFilterChip` - Creates a chip that acts like a checkbox.
219-
* `FormBuilderImagePicker` - Picker a image from Gallery or Camera and stores it in a List of images, File or String. **Note**: This picker is available for iOS and Android.
220-
* `FormBuilderPhoneField` - International phone number input.
221-
* ~~`FormBuilderRadio`~~ - Used to select one value from a list of Radio Widgets listed vertically.
222-
* `FormBuilderRadioGroup` - Used to select one value from a list of Radio Widgets. Unlike in `FormBuilderRadio`, options can either be shown vertically or horizontally.
223-
* `FormBuilderRangeSlider` - Used to select a range from a range of values
224-
* `FormBuilderRate` - For selection of a numerical value as a rating
225-
* `FormBuilderSegmentedControl` - For selection of a value from the `CupertinoSegmentedControl` as an input
226-
* `FormBuilderSignaturePad` - Presents a drawing pad on which user can doodle
227-
* `FormBuilderSlider` - For selection of a numerical value on a slider
228-
* ~~`FormBuilderStepper`~~ - Selection of a number by tapping on a plus or minus symbol. Deprecated; replaced with `FormBuilderTouchSpin`
229-
* `FormBuilderSwitch` - On/Off switch
230-
* `FormBuilderTextField` - For text input. Accepts input of single-line text, multi-line text, password, email, urls etc by using different configurations and validators
231-
* `FormBuilderTouchSpin` - Selection of a number by tapping on a plus or minus icon
232-
* `FormBuilderTypeAhead` - Auto-completes user input from a list of items
215+
216+
- `FormBuilderCheckbox` - Single Checkbox field
217+
- ~~`FormBuilderCheckboxList`~~ - List of Checkboxes for multiple selection with options listed vertically.
218+
- `FormBuilderCheckboxGroup` - List of Checkboxes for multiple selection. Unlike in `FormBuilderCheckboxList`, options can either be shown vertically or horizontally.
219+
- `FormBuilderChipsInput` - Takes a list of `Chip`s as input and suggests more options on typing
220+
- `FormBuilderChoiceChip` - Creates a chip that acts like a radio button.
221+
- `FormBuilderColorPicker` - For `Color` input selection
222+
- `FormBuilderCountryPicker` - Country selection from list
223+
- `FormBuilderDateRangePicker` - For selection of a range of dates
224+
- `FormBuilderDateTimePicker` - For `Date`, `Time` and `DateTime` input
225+
- `FormBuilderDropdown` - Used to select one value from a list as a Dropdown
226+
- `FormBuilderFilterChip` - Creates a chip that acts like a checkbox.
227+
- `FormBuilderImagePicker` - Picker a image from Gallery or Camera and stores it in a List of images, File or String. **Note**: This picker is available for iOS and Android.
228+
- `FormBuilderPhoneField` - International phone number input.
229+
- ~~`FormBuilderRadio`~~ - Used to select one value from a list of Radio Widgets listed vertically.
230+
- `FormBuilderRadioGroup` - Used to select one value from a list of Radio Widgets. Unlike in `FormBuilderRadio`, options can either be shown vertically or horizontally.
231+
- `FormBuilderRangeSlider` - Used to select a range from a range of values
232+
- `FormBuilderRate` - For selection of a numerical value as a rating
233+
- `FormBuilderSegmentedControl` - For selection of a value from the `CupertinoSegmentedControl` as an input
234+
- `FormBuilderSignaturePad` - Presents a drawing pad on which user can doodle
235+
- `FormBuilderSlider` - For selection of a numerical value on a slider
236+
- ~~`FormBuilderStepper`~~ - Selection of a number by tapping on a plus or minus symbol. Deprecated; replaced with `FormBuilderTouchSpin`
237+
- `FormBuilderSwitch` - On/Off switch
238+
- `FormBuilderTextField` - For text input. Accepts input of single-line text, multi-line text, password, email, urls etc by using different configurations and validators
239+
- `FormBuilderTouchSpin` - Selection of a number by tapping on a plus or minus icon
240+
- `FormBuilderTypeAhead` - Auto-completes user input from a list of items
233241

234242
In order to create an input field in the form, along with the label, and any applicable validation, there are several attributes that are supported by all types of inputs namely:
235243

236-
| Attribute | Type | Default | Required | Description |
237-
|-----------|-------|---------|-------------|----------|
238-
| `attribute` | `String` | `null` | `true` | This will form the key in the form value Map |
239-
| `initialValue` | `dynamic` | `null` | `false` | The initial value of the input field |
240-
| `readOnly` | `bool` | `false` | `false` | Determines whether the field widget will accept user input. This value will be ignored if the `readOnly` attribute of `FormBuilder` widget is set to `true` |
241-
| `decoration` | `InputDecoration` | `InputDecoration()` | `false` | |
242-
| `validators` | `List<FormFieldValidator>` | `[]` | `false` | List of `FormFieldValidator`s that will check the validity of value candidate in the `FormField` |
243-
| `onChanged` | `ValueChanged<T>` | `null` | `false` | This event function will fire immediately the the field value changes |
244-
| `valueTransformer` | `ValueTransformer<T>` | `null` | `false` | Function that transforms field value before saving to form value. e.g. transform TextField value for numeric field from `String` to `num` |
244+
| Attribute | Type | Default | Required | Description |
245+
| ------------------ | -------------------------- | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
246+
| `attribute` | `String` | `null` | `true` | This will form the key in the form value Map |
247+
| `initialValue` | `dynamic` | `null` | `false` | The initial value of the input field |
248+
| `readOnly` | `bool` | `false` | `false` | Determines whether the field widget will accept user input. This value will be ignored if the `readOnly` attribute of `FormBuilder` widget is set to `true` |
249+
| `decoration` | `InputDecoration` | `InputDecoration()` | `false` | |
250+
| `validators` | `List<FormFieldValidator>` | `[]` | `false` | List of `FormFieldValidator`s that will check the validity of value candidate in the `FormField` |
251+
| `onChanged` | `ValueChanged<T>` | `null` | `false` | This event function will fire immediately the the field value changes |
252+
| `valueTransformer` | `ValueTransformer<T>` | `null` | `false` | Function that transforms field value before saving to form value. e.g. transform TextField value for numeric field from `String` to `num` |
253+
245254
The rest of the attributes will be determined by the type of Widget being used.
246255

247256
### Building your own custom field
257+
248258
To build your own field within a `FormBuilder`, we use `FormBuilderCustomField` which will require that you define your own `FormField`.
249259
The `FormField` will not require a `validator` if the `validators` property is already defined in the `FormBuilderCustomField`.
260+
250261
```dart
251262
var options = ["Option 1", "Option 2", "Option 3"];
252263
```
@@ -285,30 +296,34 @@ FormBuilderCustomField(
285296
```
286297

287298
## Validation
299+
288300
The `validators` attribute in fields take in any number of `FormFieldValidator` allowing composability
289301
of validation functions as well as allow reusability of already defined validator methods.
290302

291303
### Built-in Validators
304+
292305
The package comes with several most common `FormFieldValidator`s such as required, numeric, mail, URL, min,
293306
max, minLength, maxLength, IP, credit card etc. with default `errorText` in English but with
294307
ability to include you own error message that will display whenever validation fails.
295308

296309
Available built-in validators include:
297-
* `FormBuilderValidators.required()` - requires the field have a non-empty value.
298-
* `FormBuilderValidators.numeric()` - requires the field's value to be a valid number.
299-
* `FormBuilderValidators.min()` - requires the field's value to be greater than or equal to the provided number.
300-
* `FormBuilderValidators.max()` - requires the field's value to be less than or equal to the provided number.
301-
* `FormBuilderValidators.minLength()` - requires the length of the field's value to be greater than or equal to the provided minimum length.
302-
* `FormBuilderValidators.maxLength()` - requires the length of the field's value to be less than or equal to the provided maximum length.
303-
* `FormBuilderValidators.pattern()` - requires the field's value to match the provided regex pattern.
304-
* `FormBuilderValidators.email()` - requires the field's value to be a valid email address.
305-
* ``FormBuilderValidators.url()`` - requires the field's value to be a valid url.
306-
* `FormBuilderValidators.IP()` - requires the field's value to be a valid IP address.
307-
* `FormBuilderValidators.creditCard()` - requires the field's value to be a valid credit card number.
308-
* `FormBuilderValidators.date()` - requires the field's value to be a valid date string.
309-
* `FormBuilderValidators.requiredTrue()` - requires the field's value be true.
310+
311+
- `FormBuilderValidators.required()` - requires the field have a non-empty value.
312+
- `FormBuilderValidators.numeric()` - requires the field's value to be a valid number.
313+
- `FormBuilderValidators.min()` - requires the field's value to be greater than or equal to the provided number.
314+
- `FormBuilderValidators.max()` - requires the field's value to be less than or equal to the provided number.
315+
- `FormBuilderValidators.minLength()` - requires the length of the field's value to be greater than or equal to the provided minimum length.
316+
- `FormBuilderValidators.maxLength()` - requires the length of the field's value to be less than or equal to the provided maximum length.
317+
- `FormBuilderValidators.pattern()` - requires the field's value to match the provided regex pattern.
318+
- `FormBuilderValidators.email()` - requires the field's value to be a valid email address.
319+
- `FormBuilderValidators.url()` - requires the field's value to be a valid url.
320+
- `FormBuilderValidators.IP()` - requires the field's value to be a valid IP address.
321+
- `FormBuilderValidators.creditCard()` - requires the field's value to be a valid credit card number.
322+
- `FormBuilderValidators.date()` - requires the field's value to be a valid date string.
323+
- `FormBuilderValidators.requiredTrue()` - requires the field's value be true.
310324

311325
Validation example:
326+
312327
```dart
313328
FormBuilderTextField(
314329
attribute: "age",
@@ -321,7 +336,9 @@ FormBuilderTextField(
321336
```
322337

323338
### Custom validator function
339+
324340
As well as the built-in validators any function of type `FormFieldValidator` will be accepted into the list of `validators`.
341+
325342
```dart
326343
FormBuilderTextField(
327344
attribute: "over_18",
@@ -337,7 +354,9 @@ FormBuilderTextField(
337354
```
338355

339356
### Conditional validation
357+
340358
You can also validate a field based on the value of another field
359+
341360
```
342361
FormBuilderRadio(
343362
decoration: InputDecoration(labelText: 'My best language'),
@@ -367,44 +386,54 @@ FormBuilderTextField(
367386
```
368387

369388
## CREDITS
389+
370390
### Contributors
391+
371392
<a href="https://github.com/danvick/flutter_form_builder/graphs/contributors">
372393
<img src="https://contributors-img.firebaseapp.com/image?repo=danvick/flutter_form_builder" />
373394
</a>
374395

375396
Made with [contributors-img](https://contributors-img.firebaseapp.com).
376397

377398
### Dependencies
399+
378400
This package is dependent on the following packages and plugins:
379-
* [flutter_typeahead](https://pub.dev/packages/flutter_typeahead) by [AbdulRahmanAlHamali](https://github.com/AbdulRahmanAlHamali)
380-
* [rating_bar](https://pub.dev/packages/rating_bar) by [Joshua Matta](https://github.com/joshmatta)
381-
* [datetime_picker_formfield](https://pub.dev/packages/datetime_picker_formfield) by [Jacob Phillips](https://github.com/jifalops)
382-
* [date_range_picker](https://github.com/anicdh/date_range_picker) by [anicdh](https://github.com/anicdh)
383-
* [validators](https://pub.dev/packages/validators) by [dart-league](https://github.com/dart-league)
384-
* [signature](https://pub.dev/packages/signature) by [4Q s.r.o.](https://github.com/4Q-s-r-o) with some minor improvements to fit our usage
385-
* [flutter_colorpicker](https://pub.dev/packages/flutter_colorpicker) by [mchome](https://github.com/mchome)
386-
* [flutter_chips_input](https://pub.dev/packages/flutter_chips_input) & [flutter_touch_spin](https://pub.dev/packages/flutter_touch_spin) by [Yours truly :-)](https://github.com/danvick)
401+
402+
- [flutter_typeahead](https://pub.dev/packages/flutter_typeahead) by [AbdulRahmanAlHamali](https://github.com/AbdulRahmanAlHamali)
403+
- [rating_bar](https://pub.dev/packages/rating_bar) by [Joshua Matta](https://github.com/joshmatta)
404+
- [datetime_picker_formfield](https://pub.dev/packages/datetime_picker_formfield) by [Jacob Phillips](https://github.com/jifalops)
405+
- [date_range_picker](https://github.com/anicdh/date_range_picker) by [anicdh](https://github.com/anicdh)
406+
- [validators](https://pub.dev/packages/validators) by [dart-league](https://github.com/dart-league)
407+
- [signature](https://pub.dev/packages/signature) by [4Q s.r.o.](https://github.com/4Q-s-r-o) with some minor improvements to fit our usage
408+
- [flutter_colorpicker](https://pub.dev/packages/flutter_colorpicker) by [mchome](https://github.com/mchome)
409+
- [flutter_chips_input](https://pub.dev/packages/flutter_chips_input) & [flutter_touch_spin](https://pub.dev/packages/flutter_touch_spin) by [Yours truly :-)](https://github.com/danvick)
387410

388411
### RELATED PACKAGES
412+
389413
Here are other field types for `flutter_form_builder`:
414+
390415
- [form_builder_file_picker](https://pub.dev/packages/form_builder_file_picker) - A file picker field for `FlutterFormBuilder`.
391416
- [form_builder_map_field](https://pub.dev/packages/form_builder_map_field) - A map input field for `FlutterFormBuilder`.
392417

393418
## FUTURE PLANS:
419+
394420
### Improvements
395-
- [X] Allow addition of custom input types
396-
- [X] Improve documentation by showing complete list of input types and their usage and options
397-
- [X] Create a `transformer` function option that will convert field value when field is saved - can be used to convert string to number, change to uppercase etc.
398-
- [X] Assert no duplicates in `FormBuilderInput`s `attribute` names
399-
- [X] Allow options for Checkboxes and Radios to appear left or right - Done via `leadingInput` courtesy of [Sven Schöne](https://github.com/SvenSchoene)
400-
- [X] Use flutter_touch_spin for FormBuilderStepper. Possibly rename to FormBuilderTouchSpin in next major version
401-
- [X] For RangeSlider use Flutter provided
421+
422+
- [x] Allow addition of custom input types
423+
- [x] Improve documentation by showing complete list of input types and their usage and options
424+
- [x] Create a `transformer` function option that will convert field value when field is saved - can be used to convert string to number, change to uppercase etc.
425+
- [x] Assert no duplicates in `FormBuilderInput`s `attribute` names
426+
- [x] Allow options for Checkboxes and Radios to appear left or right - Done via `leadingInput` courtesy of [Sven Schöne](https://github.com/SvenSchoene)
427+
- [x] Use flutter_touch_spin for FormBuilderStepper. Possibly rename to FormBuilderTouchSpin in next major version
428+
- [x] For RangeSlider use Flutter provided
402429

403430
### Known Issues
404-
* Setting `autovalidate` to `true` validates fields immediately they're rendered even if pristine - which is the default behavior in Flutter
405-
* Form's `reset()` doesn't clear SignaturePad - You'll be forced to clear manually
431+
432+
- Setting `autovalidate` to `true` validates fields immediately they're rendered even if pristine - which is the default behavior in Flutter
433+
- Form's `reset()` doesn't clear SignaturePad - You'll be forced to clear manually
406434

407435
## SUPPORT
436+
408437
If this package was helpful to you in delivering on your project or you just wanna to support this project, a cup of coffee would be highly appreciated ;-)
409438

410439
[![Buy me a coffee](https://www.buymeacoffee.com/assets/img/custom_images/purple_img.png)](https://buymeacoff.ee/wb5M9y2Sz)

0 commit comments

Comments
 (0)