Skip to content

Commit b04fbe1

Browse files
authored
Merge pull request #52 from danvick/main
Documentation improvements
2 parents 48b739a + ea70042 commit b04fbe1

File tree

1 file changed

+78
-70
lines changed

1 file changed

+78
-70
lines changed

README.md

Lines changed: 78 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Form Builder Validators
22

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.
44

55
Also included is the `l10n` / `i18n` of error text messages to multiple languages.
66

@@ -10,33 +10,36 @@ Also included is the `l10n` / `i18n` of error text messages to multiple language
1010
[![CodeFactor Grade](https://img.shields.io/codefactor/grade/github/flutter-form-builder-ecosystem/form_builder_validators?logo=codefactor&style=for-the-badge)](https://www.codefactor.io/repository/github/flutter-form-builder-ecosystem/form_builder_validators)
1111
---
1212

13-
> ### Migrating from version 7 to 8
13+
> ## Migrating from version 7 to 8
1414
>
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 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.
16+
17+
## Contents
1618

1719
- [Features](#features)
1820
- [Validators](#validators)
19-
- [Supported languages](#supported-languages)
21+
- [Supported languages](#supported-languages)
2022
- [Use](#use)
21-
- [Setup](#setup)
22-
- [Basic use](#basic-use)
23-
- [Especific uses](#especific-uses)
24-
- [Composing multiple validators](#composing-multiple-validators)
25-
- [Modify the default error message in a specific language](#modify-the-default-error-message-in-a-specific-language)
23+
- [Setup](#setup)
24+
- [Basic use](#basic-use)
25+
- [Specific uses](#specific-uses)
26+
- [Composing multiple validators](#composing-multiple-validators)
27+
- [Modify the default error message in a specific language](#modify-the-default-error-message-in-a-specific-language)
2628
- [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)
3234
- [Roadmap](#roadmap)
3335
- [Ecosystem](#ecosystem)
3436
- [Thanks to](#thanks-to)
3537

3638
## Features
3739

40+
- Ready-made validation rules
3841
- Multiple form inputs validators
39-
- Automatic error messages in several languages
42+
- Default error messages in several languages
4043

4144
## Validators
4245

@@ -48,24 +51,24 @@ Available built-in validators include:
4851
- `FormBuilderValidators.creditCard()` - requires the field's value to be a valid credit card number.
4952
- `FormBuilderValidators.date()` - requires the field's value to be a valid date string.
5053
- `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.
5255
- `FormBuilderValidators.integer()` - requires the field's value to be an integer.
5356
- `FormBuilderValidators.ip()` - requires the field's value to be a valid IP address.
5457
- `FormBuilderValidators.match()` - requires the field's value to match the provided regex pattern.
5558
- `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.
5861
- `FormBuilderValidators.min()` - requires the field's value to be greater than or equal to the provided number.
5962
- `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.
6164
- `FormBuilderValidators.equalLength()` - requires the length of the field's value to be equal to the provided minimum length.
6265
- `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.
6568

6669
### Supported languages
6770

68-
Validators support default errorText messages in this languages:
71+
Validators support default `errorText` messages in these languages:
6972

7073
- Albanian (al)
7174
- Arabic (ar)
@@ -82,7 +85,7 @@ Validators support default errorText messages in this languages:
8285
- Farsi/Persian (fa)
8386
- French (fr)
8487
- German (de)
85-
- Greek (el)
88+
- Greek (el)
8689
- Hungarian (hu)
8790
- Indonesian (id)
8891
- Italian (it)
@@ -112,71 +115,71 @@ And you can still add your custom error messages.
112115

113116
### Setup
114117

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`.
116119

117-
```dart
118-
return MaterialApp(
119-
supportedLocales: [
120+
```Dart
121+
return MaterialApp(
122+
supportedLocales: [
120123
Locale('de'),
121124
Locale('en'),
122125
Locale('es'),
123126
Locale('fr'),
124127
Locale('it'),
125128
...
126-
],
127-
localizationsDelegates: [
129+
],
130+
localizationsDelegates: [
128131
GlobalMaterialLocalizations.delegate,
129132
GlobalWidgetsLocalizations.delegate,
130133
FormBuilderLocalizations.delegate,
131-
],
134+
],
132135
```
133136

134137
### Basic use
135138

136139
```dart
137140
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(),
141144
),
142145
```
143146

144147
See [pub.dev example tab](https://pub.dev/packages/form_builder_validators/example) or [github code](example/lib/main.dart) for more details
145148

146-
### Especific uses
149+
### Specific uses
147150

148151
#### Composing multiple validators
149152

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.
151154

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.
153156

154157
Example:
155158

156159
```dart
157160
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+
]),
180183
),
181184
```
182185

@@ -188,35 +191,40 @@ see [override_form_builder_localizations_en](example/lib/override_form_builder_l
188191

189192
### Contribute
190193

191-
You have some ways to contribute to this packages
194+
You have some ways to contribute to this package.
192195

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
196199

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
198201

199202
#### Add new supported language
200203

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.
202205

203206
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`.
205209

206210
2. Translate the error messages
211+
207212
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.
208213

209214
3. Generate localization code
215+
210216
To generate boilerplate code for localization, run the generate command inside the package directory where `pubspec.yaml` file is located:
211217

212218
`flutter gen-l10n`
213219

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.
215221

216222
4. Update README
223+
217224
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!
218225

219226
5. Submit PR
227+
220228
Submit your PR and be of help to millions of developers all over the world!
221229

222230
#### Add new validator
@@ -225,14 +233,14 @@ Submit your PR and be of help to millions of developers all over the world!
225233
2. Implement tests
226234
3. Add to [validators](#validators) with name and description
227235
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.
230238
c. Run `flutter gen-l10n` command
231239
5. Submit PR
232240

233241
### Questions and answers
234242

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)
236244

237245
### Donations
238246

@@ -246,7 +254,7 @@ Donate or become a sponsor of Flutter Form Builder Ecosystem
246254

247255
## Ecosystem
248256

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
250258

251259
## Thanks to
252260

0 commit comments

Comments
 (0)