You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+78-70Lines changed: 78 additions & 70 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Form Builder Validators
2
2
3
-
Form Builder Validators set of validators for `FlutterFormBuilder`. Provides common validators and a way to make your own.
3
+
Form Builder Validators set of validators for any `FormField` widget or widgets that extend the `FormField` class - *e.g.*, `TextFormField`, `DropdownFormField`, *et cetera*. It provides standard ready-made validation rules and a way to compose new validation rules combining multiple rules, including custom ones.
4
4
5
5
Also included is the `l10n` / `i18n` of error text messages to multiple languages.
6
6
@@ -10,33 +10,36 @@ Also included is the `l10n` / `i18n` of error text messages to multiple language
> To migrate from v7 to v8, remove `context` as a parameter to validator functions. For example, `FormBuilderValidators.required(context)` becomes `FormBuilderValidators.required()` without context passed to it.
15
+
> To migrate from v7 to v8, remove `context` as a parameter to validator functions. For example, `FormBuilderValidators.required(context)` becomes `FormBuilderValidators.required()` without `context` passed in.
-[Modify the default error message in a specific language](#modify-the-default-error-message-in-a-specific-language)
26
28
-[Support](#support)
27
-
-[Contribute](#contribute)
28
-
-[Add new supported language](#add-new-supported-language)
29
-
-[Add new validator](#add-new-validator)
30
-
-[Questions and answers](#questions-and-answers)
31
-
-[Donations](#donations)
29
+
-[Contribute](#contribute)
30
+
- [Add new supported language](#add-new-supported-language)
31
+
- [Add new validator](#add-new-validator)
32
+
-[Questions and answers](#questions-and-answers)
33
+
-[Donations](#donations)
32
34
-[Roadmap](#roadmap)
33
35
-[Ecosystem](#ecosystem)
34
36
-[Thanks to](#thanks-to)
35
37
36
38
## Features
37
39
40
+
- Ready-made validation rules
38
41
- Multiple form inputs validators
39
-
-Automatic error messages in several languages
42
+
-Default error messages in several languages
40
43
41
44
## Validators
42
45
@@ -48,24 +51,24 @@ Available built-in validators include:
48
51
-`FormBuilderValidators.creditCard()` - requires the field's value to be a valid credit card number.
49
52
-`FormBuilderValidators.date()` - requires the field's value to be a valid date string.
50
53
-`FormBuilderValidators.email()` - requires the field's value to be a valid email address.
51
-
-`FormBuilderValidators.equal()` - requires the field's value be equal to provided object.
54
+
-`FormBuilderValidators.equal()` - requires the field's value to be equal to the provided object.
52
55
-`FormBuilderValidators.integer()` - requires the field's value to be an integer.
53
56
-`FormBuilderValidators.ip()` - requires the field's value to be a valid IP address.
54
57
-`FormBuilderValidators.match()` - requires the field's value to match the provided regex pattern.
55
58
-`FormBuilderValidators.max()` - requires the field's value to be less than or equal to the provided number.
56
-
-`FormBuilderValidators.maxLength()` - requires the length of the field's value to be less than or equal to the provided maximum length.
57
-
-`FormBuilderValidators.maxWordsCount()` - requires the words count of the field's value to be less than or equal to the provided maximum count.
59
+
-`FormBuilderValidators.maxLength()` - requires the length of the field's value to be less than or equal to the provided maximum size.
60
+
-`FormBuilderValidators.maxWordsCount()` - requires the word count of the field's value to be less than or equal to the provided maximum count.
58
61
-`FormBuilderValidators.min()` - requires the field's value to be greater than or equal to the provided number.
59
62
-`FormBuilderValidators.minLength()` - requires the length of the field's value to be greater than or equal to the provided minimum length.
60
-
-`FormBuilderValidators.minWordsCount()` - requires the words count of the field's value to be greater than or equal to the provided minimum count.
63
+
-`FormBuilderValidators.minWordsCount()` - requires the word count of the field's value to be greater than or equal to the provided minimum count.
61
64
-`FormBuilderValidators.equalLength()` - requires the length of the field's value to be equal to the provided minimum length.
62
65
-`FormBuilderValidators.numeric()` - requires the field's value to be a valid number.
63
-
-`FormBuilderValidators.required()` - requires the field have a non-empty value.
64
-
-`FormBuilderValidators.url()` - requires the field's value to be a valid url.
66
+
-`FormBuilderValidators.required()` - requires the field to have a non-empty value.
67
+
-`FormBuilderValidators.url()` - requires the field's value to be a valid URL.
65
68
66
69
### Supported languages
67
70
68
-
Validators support default errorText messages in this languages:
71
+
Validators support default `errorText` messages in these languages:
69
72
70
73
- Albanian (al)
71
74
- Arabic (ar)
@@ -82,7 +85,7 @@ Validators support default errorText messages in this languages:
82
85
- Farsi/Persian (fa)
83
86
- French (fr)
84
87
- German (de)
85
-
- Greek (el)
88
+
- Greek (el)
86
89
- Hungarian (hu)
87
90
- Indonesian (id)
88
91
- Italian (it)
@@ -112,71 +115,71 @@ And you can still add your custom error messages.
112
115
113
116
### Setup
114
117
115
-
The default error message is in English. To allow for localization of default error messages within your app, add `FormBuilderLocalizations.delegate` in the list of your app's `localizationsDelegates`
118
+
The default error message is in English. To allow for localization of default error messages within your app, add `FormBuilderLocalizations.delegate` in the list of your app's `localizationsDelegates`.
116
119
117
-
```dart
118
-
return MaterialApp(
119
-
supportedLocales: [
120
+
```Dart
121
+
return MaterialApp(
122
+
supportedLocales: [
120
123
Locale('de'),
121
124
Locale('en'),
122
125
Locale('es'),
123
126
Locale('fr'),
124
127
Locale('it'),
125
128
...
126
-
],
127
-
localizationsDelegates: [
129
+
],
130
+
localizationsDelegates: [
128
131
GlobalMaterialLocalizations.delegate,
129
132
GlobalWidgetsLocalizations.delegate,
130
133
FormBuilderLocalizations.delegate,
131
-
],
134
+
],
132
135
```
133
136
134
137
### Basic use
135
138
136
139
```dart
137
140
TextFormField(
138
-
decoration: InputDecoration(labelText: 'Name'),
139
-
autovalidateMode: AutovalidateMode.always,
140
-
validator: FormBuilderValidators.required(),
141
+
decoration: InputDecoration(labelText: 'Name'),
142
+
autovalidateMode: AutovalidateMode.always,
143
+
validator: FormBuilderValidators.required(),
141
144
),
142
145
```
143
146
144
147
See [pub.dev example tab](https://pub.dev/packages/form_builder_validators/example) or [github code](example/lib/main.dart) for more details
145
148
146
-
### Especific uses
149
+
### Specific uses
147
150
148
151
#### Composing multiple validators
149
152
150
-
`FormBuilderValidators` class comes with a very useful static function named `compose()` which takes a list of `FormFieldValidator` functions. Composing allows you to create once and reuse validation rules across multiple fields, widgets, or apps.
153
+
The `FormBuilderValidators` class comes with a handy static function named `compose()`, which takes a list of `FormFieldValidator` functions. Composing allows you to create once and reuse validation rules across multiple fields, widgets, or apps.
151
154
152
-
On validation, each validator is run, and if any one validator returns a non-null value (i.e., a String), validation fails, and the `errorText` for the field is set as the returned string.
155
+
On validation, each validator is run, and if any validator returns a non-null value (i.e., a String), validation fails, and the `errorText` for the field is set as the returned string.
153
156
154
157
Example:
155
158
156
159
```dart
157
160
TextFormField(
158
-
decoration: InputDecoration(labelText: 'Age'),
159
-
keyboardType: TextInputType.number,
160
-
autovalidateMode: AutovalidateMode.always,
161
-
validator: FormBuilderValidators.compose([
162
-
/// Makes this field required
163
-
FormBuilderValidators.required(),
164
-
165
-
/// Ensures the value entered is numeric - with custom error message
166
-
FormBuilderValidators.numeric(errorText: 'La edad debe ser numérica.'),
167
-
168
-
/// Sets a maximum value of 70
169
-
FormBuilderValidators.max(70),
170
-
171
-
/// Include your own custom `FormFieldValidator` function, if you want
172
-
/// Ensures positive values only. We could also have used `FormBuilderValidators.min(0)` instead
173
-
(val) {
174
-
final number = int.tryParse(val);
175
-
if (number == null) return null;
176
-
if (number < 0) return 'We cannot have a negative age';
177
-
return null;
178
-
}
179
-
]),
161
+
decoration: InputDecoration(labelText: 'Age'),
162
+
keyboardType: TextInputType.number,
163
+
autovalidateMode: AutovalidateMode.always,
164
+
validator: FormBuilderValidators.compose([
165
+
/// Makes this field required
166
+
FormBuilderValidators.required(),
167
+
168
+
/// Ensures the value entered is numeric - with a custom error message
169
+
FormBuilderValidators.numeric(errorText: 'La edad debe ser numérica.'),
170
+
171
+
/// Sets a maximum value of 70
172
+
FormBuilderValidators.max(70),
173
+
174
+
/// Include your own custom `FormFieldValidator` function, if you want
175
+
/// Ensures positive values only. We could also have used `FormBuilderValidators.min(0)` instead
176
+
(val) {
177
+
final number = int.tryParse(val);
178
+
if (number == null) return null;
179
+
if (number < 0) return 'We cannot have a negative age';
180
+
return null;
181
+
}
182
+
]),
180
183
),
181
184
```
182
185
@@ -188,35 +191,40 @@ see [override_form_builder_localizations_en](example/lib/override_form_builder_l
188
191
189
192
### Contribute
190
193
191
-
You have some ways to contribute to this packages
194
+
You have some ways to contribute to this package.
192
195
193
-
- Beginner: Reporting bugs or request new features
194
-
- Intermediate: Implement new features (from issues or not) and created pull requests
195
-
- Advanced: Join to [organization](#ecosystem) like a member and help coding, manage issues, dicuss new features and other things
196
+
- Beginner: Reporting bugs or requesting new features
197
+
- Intermediate: Answer questions, implement new features (from issues or not), and create pull requests
198
+
- Advanced: Join [organization](#ecosystem) like a member and help to code, manage issues, discuss new features, and other things
196
199
197
-
See [contribution file](https://github.com/flutter-form-builder-ecosystem/.github/blob/main/CONTRIBUTING.md) for more details
200
+
See the [contribution file](https://github.com/flutter-form-builder-ecosystem/.github/blob/main/CONTRIBUTING.md) for more details
198
201
199
202
#### Add new supported language
200
203
201
-
We especially welcome efforts to internationalize/localize the package by translating the default validation `errorText` strings for built-in validation rules.
204
+
We welcome efforts to internationalize/localize the package by translating the default validation `errorText` strings for built-in validation rules.
202
205
203
206
1. Add ARB files
204
-
Create one ARB file inside the `lib/l10n` folder for each of the locales you need to add support. Name the files in the following way: `intl_<LOCALE_ISO_CODE>.arb`. For example: `intl_fr.arb` or `intl_fr_FR.arb`.
207
+
208
+
Create one ARB file inside the `lib/l10n` folder for each locale you need to add support. Name the files in the following way: `intl_<LOCALE_ISO_CODE>.arb`. For example: `intl_fr.arb` or `intl_fr_FR.arb`.
205
209
206
210
2. Translate the error messages
211
+
207
212
Copy and paste the contents of `intl_en.arb` into your newly created ARB file. Then translate the error messages by overwriting the default messages.
208
213
209
214
3. Generate localization code
215
+
210
216
To generate boilerplate code for localization, run the generate command inside the package directory where `pubspec.yaml` file is located:
211
217
212
218
`flutter gen-l10n`
213
219
214
-
Running the command will automatically create/update files inside the `lib/localization` directory, including your newly added locale support.
220
+
The command will automatically create/update files inside the `lib/localization` directory, including your newly added locale support.
215
221
216
222
4. Update README
223
+
217
224
Remember to update README, adding the new language (and language code) under [Supported languages section](#supported-languages) in alphabetic order, so that everyone knows your new language is now supported!
218
225
219
226
5. Submit PR
227
+
220
228
Submit your PR and be of help to millions of developers all over the world!
221
229
222
230
#### Add new validator
@@ -225,14 +233,14 @@ Submit your PR and be of help to millions of developers all over the world!
225
233
2. Implement tests
226
234
3. Add to [validators](#validators) with name and description
227
235
4. Add message error translated on all languages (yes, all languages). To accomplish this need:
228
-
a. Add property to all `intl_*.arb` files, on alphabetic order.
229
-
b. Translate message on all languages.
236
+
a. Add property to all `intl_*.arb` files, in alphabetic order.
237
+
b. Translate message in all languages.
230
238
c. Run `flutter gen-l10n` command
231
239
5. Submit PR
232
240
233
241
### Questions and answers
234
242
235
-
You can question or search answers on [Github discussion](https://github.com/flutter-form-builder-ecosystem/form_builder_validators/discussions) or on [StackOverflow](https://stackoverflow.com/questions/tagged/flutter-form-builder)
243
+
You can ask questions or search for answers on [Github discussion](https://github.com/flutter-form-builder-ecosystem/form_builder_validators/discussions) or on [StackOverflow](https://stackoverflow.com/questions/tagged/flutter-form-builder)
236
244
237
245
### Donations
238
246
@@ -246,7 +254,7 @@ Donate or become a sponsor of Flutter Form Builder Ecosystem
246
254
247
255
## Ecosystem
248
256
249
-
Take a look to[our awesome ecosystem](https://github.com/flutter-form-builder-ecosystem) and all packages in there
257
+
Take a look at[our fantastic ecosystem](https://github.com/flutter-form-builder-ecosystem) and all packages in there
0 commit comments