Skip to content

Commit 0f08fcb

Browse files
danvickdanvick
committed
feat: Improvements and fixes to README
1 parent 327faa5 commit 0f08fcb

File tree

1 file changed

+60
-57
lines changed

1 file changed

+60
-57
lines changed

‎README.md

Lines changed: 60 additions & 57 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

@@ -12,17 +12,19 @@ Also included is the `l10n` / `i18n` of error text messages to multiple language
1212

1313
---
1414

15-
> ### Migrating from version 7 to 8
15+
> ## Migrating from version 7 to 8
1616
>
17-
> 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.
17+
> 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.
18+
19+
## Contents
1820

1921
- [Features](#features)
2022
- [Validators](#validators)
2123
- [Supported languages](#supported-languages)
2224
- [Use](#use)
2325
- [Setup](#setup)
2426
- [Basic use](#basic-use)
25-
- [Especific uses](#especific-uses)
27+
- [Specific uses](#specific-uses)
2628
- [Support](#support)
2729
- [Contribute](#contribute)
2830
- [Questions and answers](#questions-and-answers)
@@ -34,8 +36,9 @@ Also included is the `l10n` / `i18n` of error text messages to multiple language
3436

3537
## Features
3638

39+
- Ready-made validation rules
3740
- Multiple form inputs validators
38-
- Automatic error messages in several languages
41+
- Default error messages in several languages
3942

4043
## Validators
4144

@@ -47,22 +50,22 @@ Available built-in validators include:
4750
- `FormBuilderValidators.creditCard()` - requires the field's value to be a valid credit card number.
4851
- `FormBuilderValidators.date()` - requires the field's value to be a valid date string.
4952
- `FormBuilderValidators.email()` - requires the field's value to be a valid email address.
50-
- `FormBuilderValidators.equal()` - requires the field's value be equal to provided object.
53+
- `FormBuilderValidators.equal()` - requires the field's value to be equal to the provided object.
5154
- `FormBuilderValidators.integer()` - requires the field's value to be an integer.
5255
- `FormBuilderValidators.ip()` - requires the field's value to be a valid IP address.
5356
- `FormBuilderValidators.match()` - requires the field's value to match the provided regex pattern.
5457
- `FormBuilderValidators.max()` - requires the field's value to be less than or equal to the provided number.
55-
- `FormBuilderValidators.maxLength()` - requires the length of the field's value to be less than or equal to the provided maximum length.
58+
- `FormBuilderValidators.maxLength()` - requires the length of the field's value to be less than or equal to the provided maximum size.
5659
- `FormBuilderValidators.min()` - requires the field's value to be greater than or equal to the provided number.
5760
- `FormBuilderValidators.minLength()` - requires the length of the field's value to be greater than or equal to the provided minimum length.
5861
- `FormBuilderValidators.equalLength()` - requires the length of the field's value to be equal to the provided minimum length.
5962
- `FormBuilderValidators.numeric()` - requires the field's value to be a valid number.
60-
- `FormBuilderValidators.required()` - requires the field have a non-empty value.
61-
- `FormBuilderValidators.url()` - requires the field's value to be a valid url.
63+
- `FormBuilderValidators.required()` - requires the field to have a non-empty value.
64+
- `FormBuilderValidators.url()` - requires the field's value to be a valid URL.
6265

6366
### Supported languages
6467

65-
Validators support default errorText messages in this languages:
68+
Validators support default `errorText` messages in these languages:
6669

6770
- Arabic (ar)
6871
- Bangla (bn)
@@ -77,7 +80,7 @@ Validators support default errorText messages in this languages:
7780
- Dutch (nl)
7881
- Farsi/Persian (fa)
7982
- French (fr)
80-
- Greek (el)
83+
- Greek (el)
8184
- German (de)
8285
- Hungarian (hu)
8386
- Indonesian (id)
@@ -106,23 +109,23 @@ And you can still add your custom error messages.
106109

107110
### Setup
108111

109-
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`
110-
111-
```dart
112-
return MaterialApp(
113-
supportedLocales: [
114-
Locale('de'),
115-
Locale('en'),
116-
Locale('es'),
117-
Locale('fr'),
118-
Locale('it'),
119-
...
120-
],
121-
localizationsDelegates: [
122-
GlobalMaterialLocalizations.delegate,
123-
GlobalWidgetsLocalizations.delegate,
124-
FormBuilderLocalizations.delegate,
125-
],
112+
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`.
113+
114+
```Dart
115+
return MaterialApp(
116+
supportedLocales: [
117+
Locale('de'),
118+
Locale('en'),
119+
Locale('es'),
120+
Locale('fr'),
121+
Locale('it'),
122+
...
123+
],
124+
localizationsDelegates: [
125+
GlobalMaterialLocalizations.delegate,
126+
GlobalWidgetsLocalizations.delegate,
127+
FormBuilderLocalizations.delegate,
128+
],
126129
```
127130

128131
### Basic use
@@ -137,26 +140,26 @@ TextFormField(
137140

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

140-
### Especific uses
143+
### Specific uses
141144

142145
#### Composing multiple validators
143146

144-
`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.
147+
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.
145148

146-
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.
149+
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.
147150

148151
Example:
149152

150153
```dart
151154
TextFormField(
152-
decoration: InputDecoration(labelText: 'Age'),
153-
keyboardType: TextInputType.number,
154-
autovalidateMode: AutovalidateMode.always,
155-
validator: FormBuilderValidators.compose([
156-
/// Makes this field required
157-
FormBuilderValidators.required(),
158-
159-
/// Ensures the value entered is numeric - with custom error message
155+
decoration: InputDecoration(labelText: 'Age'),
156+
keyboardType: TextInputType.number,
157+
autovalidateMode: AutovalidateMode.always,
158+
validator: FormBuilderValidators.compose([
159+
/// Makes this field required
160+
FormBuilderValidators.required(),
161+
162+
/// Ensures the value entered is numeric - with a custom error message
160163
FormBuilderValidators.numeric(errorText: 'La edad debe ser numérica.'),
161164
162165
/// Sets a maximum value of 70
@@ -170,7 +173,7 @@ TextFormField(
170173
if (number < 0) return 'We cannot have a negative age';
171174
return null;
172175
}
173-
]),
176+
]),
174177
),
175178
```
176179

@@ -182,49 +185,49 @@ see [override_form_builder_localizations_en](example/lib/override_form_builder_l
182185

183186
### Contribute
184187

185-
You have some ways to contribute to this packages
188+
You have some ways to contribute to this package.
186189

187-
- Beginner: Reporting bugs or request new features
188-
- Intermediate: Implement new features (from issues or not) and created pull requests
189-
- Advanced: Join to [organization](#ecosystem) like a member and help coding, manage issues, dicuss new features and other things
190+
- Beginner: Reporting bugs or requesting new features
191+
- Intermediate: Answer questions, implement new features (from issues or not) and create pull requests
192+
- Advanced: Join [organization](#ecosystem) like a member and help to code, manage issues, discuss new features, and other things
190193

191-
See [contribution file](https://github.com/flutter-form-builder-ecosystem/.github/blob/main/CONTRIBUTING.md) for more details
194+
See the [contribution file](https://github.com/flutter-form-builder-ecosystem/.github/blob/main/CONTRIBUTING.md) for more details
192195

193196
#### Add new supported language
194197

195-
We especially welcome efforts to internationalize/localize the package by translating the default validation `errorText` strings for built-in validation rules.
198+
We welcome efforts to internationalize/localize the package by translating the default validation `errorText` strings for built-in validation rules.
196199

197-
1. Add ARB files
200+
1. Add ARB files
198201

199-
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`.
202+
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`.
200203

201204
2. Translate the error messages
202205

203-
Duplicate the contents of `intl_en.arb` (or any other ARB file) into your newly created ARB file, then translate the error messages by overwriting the default messages.
206+
Duplicate the contents of `intl_en.arb` (or any other ARB file) into your newly created ARB file, then translate the error messages by overwriting the default messages.
204207

205208
3. Generate localization code
206209

207-
To generate boilerplate code for localization, run the generate command inside the package directory where `pubspec.yaml` file is located:
210+
To generate boilerplate code for localization, run the generate command inside the package directory where `pubspec.yaml` file is located:
208211

209-
`flutter gen-l10n`
212+
`flutter gen-l10n`
210213

211-
Running the command will automatically create/update files inside the `lib/localization` directory, including your newly added locale support.
214+
The command will automatically create/update files inside the `lib/localization` directory, including your newly added locale support.
212215

213216
4. Update README
214217

215-
Remember to update README, adding the new language (and language code) under [Supported languages section](#supported-languages) so that everyone knows your new language is now supported!
218+
Remember to update README, adding the new language (and language code) under [Supported languages section](#supported-languages) so that everyone knows your new language is now supported!
216219

217220
5. Submit PR
218221

219-
Submit your PR and be of help to millions of developers all over the world!
222+
Submit your PR and be of help to millions of developers all over the world!
220223

221224
### Questions and answers
222225

223-
You can join to [our Discord server](https://discord.gg/25KNPMJQf2) or search answers in [StackOverflow](https://stackoverflow.com/questions/tagged/flutter-form-builder)
226+
You can join [our Discord server](https://discord.gg/25KNPMJQf2) or search for answers in [StackOverflow](https://stackoverflow.com/questions/tagged/flutter-form-builder)
224227

225228
### Donations
226229

227-
Buy a coffe to [Danvick Miller](https://twitter.com/danvickmiller), creator of this awesome package
230+
Buy a coffe for [Danvick Miller](https://twitter.com/danvickmiller), the creator of this awesome package
228231

229232
[![Buy me a coffee](https://www.buymeacoffee.com/assets/img/guidelines/download-assets-sm-1.svg)](https://www.buymeacoffee.com/danvick)
230233

@@ -234,7 +237,7 @@ Buy a coffe to [Danvick Miller](https://twitter.com/danvickmiller), creator of t
234237

235238
## Ecosystem
236239

237-
Take a look to [our awesome ecosystem](https://github.com/flutter-form-builder-ecosystem) and all packages in there
240+
Take a look at [our fantastic ecosystem](https://github.com/flutter-form-builder-ecosystem) and all packages in there
238241

239242
## Thanks to
240243

0 commit comments

Comments
 (0)