Skip to content

Commit 1f9eaf8

Browse files
deandreamatiasdeandreamatias
authored
Merge pull request #5 from flutter-form-builder-ecosystem/improve-docs
Improve docs
2 parents bc6b41b + 3239d99 commit 1f9eaf8

File tree

2 files changed

+152
-94
lines changed

2 files changed

+152
-94
lines changed

‎.github/workflows/base.yaml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,3 +78,13 @@ jobs:
7878
sh ./tool/pub_login.sh
7979
- name: Publish package
8080
run: dart pub publish -v -f
81+
- name: Build changelog
82+
id: github_release
83+
uses: mikepenz/release-changelog-builder-action@v3
84+
env:
85+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
86+
- name: Create release
87+
uses: softprops/[email protected]
88+
with:
89+
body: ${{steps.github_release.outputs.changelog}}
90+

‎README.md

Lines changed: 142 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,44 @@
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 `FlutterFormBuilder`. Provides common validators and a way to make your own.
44

55
Also included is the `l10n` / `i18n` of error text messages to multiple languages.
6-
___
76

87
[![Pub Version](https://img.shields.io/pub/v/form_builder_validators?logo=flutter&style=for-the-badge)](https://pub.dev/packages/form_builder_validators)
98
[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/flutter-form-builder-ecosystem/form_builder_validators/Base?logo=github&style=for-the-badge)](https://github.com/flutter-form-builder-ecosystem/form_builder_validators/actions/workflows/base.yaml)
109
[![Codecov](https://img.shields.io/codecov/c/github/flutter-form-builder-ecosystem/form_builder_validators?logo=codecov&style=for-the-badge)](https://codecov.io/gh/flutter-form-builder-ecosystem/form_builder_validators/)
1110
[![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)
11+
[![Discord](https://img.shields.io/discord/985922433578053673?logo=discord&style=for-the-badge)](https://discord.com/invite/25KNPMJQf2)
1212

13-
14-
[![Buy me a coffee](https://www.buymeacoffee.com/assets/img/guidelines/download-assets-sm-1.svg)](https://www.buymeacoffee.com/danvick)
1513
___
1614

1715
> ### Migrating from version 7 to 8
1816
> 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.
1917
20-
### Example
21-
```dart
22-
import 'package:form_builder_validators/form_builder_validators.dart';
18+
- [Features](#features)
19+
- [Validators](#validators)
20+
- [Supported languages](#supported-languages)
21+
- [Use](#use)
22+
- [Setup](#setup)
23+
- [Basic use](#basic-use)
24+
- [Especific uses](#especific-uses)
25+
- [Support](#support)
26+
- [Contribute](#contribute)
27+
- [Questions and answers](#questions-and-answers)
28+
- [Donations](#donations)
29+
- [Roadmap](#roadmap)
30+
- [Ecosystem](#ecosystem)
31+
- [Thanks to](#thanks-to)
32+
- [Contributors](#contributors)
2333

24-
...
2534

26-
TextFormField(
27-
decoration: InputDecoration(labelText: 'Name'),
28-
autovalidateMode: AutovalidateMode.always,
29-
validator: FormBuilderValidators.required(),
30-
),
31-
TextFormField(
32-
decoration: InputDecoration(labelText: 'Age'),
33-
keyboardType: TextInputType.number,
34-
autovalidateMode: AutovalidateMode.always,
35-
validator: FormBuilderValidators.compose([
36-
FormBuilderValidators.numeric(errorText: 'La edad debe ser numérica.'),
37-
FormBuilderValidators.max(70),
38-
(val) {
39-
var number = int.tryParse(val ?? '');
40-
if (number != null) if (number < 0)
41-
return 'We cannot have a negative age';
42-
return null;
43-
}
44-
]),
45-
),
46-
```
35+
## Features
36+
37+
- Multiple form inputs validators
38+
- Automatic error messages in several languages
39+
40+
## Validators
4741

48-
## Built-in Validators
4942
This package comes with several most common `FormFieldValidator`s such as required, numeric, mail,
5043
URL, min, max, minLength, maxLength, IP, credit card, etc., with default `errorText` messages.
5144

@@ -66,7 +59,79 @@ Available built-in validators include:
6659
* `FormBuilderValidators.required()` - requires the field have a non-empty value.
6760
* ``FormBuilderValidators.url()`` - requires the field's value to be a valid url.
6861

69-
## Composing multiple validators
62+
### Supported languages
63+
64+
Validators support default errorText messages in this languages:
65+
66+
- Arabic (ar)
67+
- Bangla (bn)
68+
- Catalan (ca)
69+
- Chinese Simplified (zh_Hans)
70+
- Chinese Traditional (zh_Hant)
71+
- English (en)
72+
- Estonian (et)
73+
- Dutch (nl)
74+
- Farsi/Persian (fa)
75+
- French (fr)
76+
- German (de)
77+
- Hungarian (hu)
78+
- Indonesian (id)
79+
- Italian (it)
80+
- Japanese (ja)
81+
- Korean (ko)
82+
- Lao (lo)
83+
- Polish (pl)
84+
- Portuguese (pt)
85+
- Romanian (ro)
86+
- Russian (ru)
87+
- Slovak (sk)
88+
- Slovenian (sl)
89+
- Spanish (es)
90+
- Swahili (sw)
91+
- Ukrainian (uk)
92+
- Turkish (tr)
93+
94+
And you can still add your custom error messages.
95+
96+
## Use
97+
98+
### Setup
99+
100+
To allow for localization of default error messages within your app, add `FormBuilderLocalizations.delegate` in the list of your app's `localizationsDelegates`
101+
102+
```dart
103+
return MaterialApp(
104+
supportedLocales: [
105+
Locale('de'),
106+
Locale('en'),
107+
Locale('es'),
108+
Locale('fr'),
109+
Locale('it'),
110+
...
111+
],
112+
localizationsDelegates: [
113+
GlobalMaterialLocalizations.delegate,
114+
GlobalWidgetsLocalizations.delegate,
115+
FormBuilderLocalizations.delegate,
116+
],
117+
```
118+
119+
### Basic use
120+
121+
```dart
122+
TextFormField(
123+
decoration: InputDecoration(labelText: 'Name'),
124+
autovalidateMode: AutovalidateMode.always,
125+
validator: FormBuilderValidators.required(),
126+
),
127+
```
128+
129+
See [pud.dev example tab](https://pub.dev/packages/form_builder_validators/example) or [github code](example/lib/main.dart) for more details
130+
131+
### Especific uses
132+
133+
#### Composing multiple validators
134+
70135
`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.
71136

72137
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.
@@ -99,88 +164,71 @@ TextFormField(
99164
),
100165
```
101166

102-
## l10n
103-
To allow for localization of default error messages within your app, add `FormBuilderLocalizations.delegate` in the list of your app's `localizationsDelegates`
167+
## Support
104168

105-
```dart
106-
return MaterialApp(
107-
supportedLocales: [
108-
Locale('de'),
109-
Locale('en'),
110-
Locale('es'),
111-
Locale('fr'),
112-
Locale('it'),
113-
...
114-
],
115-
localizationsDelegates: [
116-
GlobalMaterialLocalizations.delegate,
117-
GlobalWidgetsLocalizations.delegate,
118-
FormBuilderLocalizations.delegate,
119-
],
120-
```
121-
### Supported languages (default errorText messages)
122-
- Arabic (ar)
123-
- Bangla (bn)
124-
- Catalan (ca)
125-
- Chinese Simplified (zh_Hans)
126-
- Chinese Traditional (zh_Hant)
127-
- English (en)
128-
- Estonian (et)
129-
- Dutch (nl)
130-
- Farsi/Persian (fa)
131-
- French (fr)
132-
- German (de)
133-
- Hungarian (hu)
134-
- Indonesian (id)
135-
- Italian (it)
136-
- Japanese (ja)
137-
- Korean (ko)
138-
- Lao (lo)
139-
- Polish (pl)
140-
- Portuguese (pt)
141-
- Romanian (ro)
142-
- Russian (ru)
143-
- Slovak (sk)
144-
- Slovenian (sl)
145-
- Spanish (es)
146-
- Swahili (sw)
147-
- Ukrainian (uk)
148-
- Turkish (tr)
169+
### Contribute
149170

150-
And you can still add your custom error messages.
171+
You have some ways to contribute to this packages
151172

152-
## Support
153-
### Issues and PRs
154-
Any support in reporting bugs, answering questions, or PRs is always appreciated.
173+
- Beginner: Reporting bugs or request new features
174+
- Intermediate: Implement new features (from issues or not) and created pull requests
175+
- Advanced: Join to [organization](#ecosystem) like a member and help coding, manage issues, dicuss new features and other things
176+
177+
See [contribution file](https://github.com/flutter-form-builder-ecosystem/.github/blob/main/CONTRIBUTING.md) for more details
178+
179+
#### Add new supported language
155180

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

158-
### Localizing messages
183+
1. Add ARB files
159184

160-
#### 1. Add ARB files
161185
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`.
162186

163-
#### 2. Translate the error messages
187+
2. Translate the error messages
164188

165189
Duplicate the contents of `intl_messages.arb` (or any other ARB file) into your newly created ARB file, then translate the error messages by overwriting the default messages.
166190

167-
#### 3. Run command
191+
3. Generate localization code
192+
168193
To generate boilerplate code for localization, run the generate command inside the package directory where `pubspec.yaml` file is located:
169194

170-
```
171-
flutter pub run intl_utils:generate
172-
```
195+
`flutter pub run intl_utils:generate`
173196

174197
Running the command will automatically create/update files inside the `lib/localization` directory, including your newly added locale support.
175198

176-
#### 4. Update README
177-
Remember to update README, adding the new language (and language code) under [Supported languages section](#supported-languages-default-errortext-messages) so that everyone knows your new language is now supported!
199+
4. Update README
200+
201+
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!
202+
203+
5. Submit PR
178204

179-
#### 5. Submit PR
180205
Submit your PR and be of help to millions of developers all over the world!
181206

182-
### Coffee :-)
183-
If this package was helpful to you in delivering your project, or you want to support this package, I would highly appreciate a cup of coffee ;-)
207+
### Questions and answers
208+
209+
You can join to [our Discord server](https://discord.gg/25KNPMJQf2) or search answers in [StackOverflow](https://stackoverflow.com/questions/tagged/flutter-form-builder)
210+
211+
### Donations
212+
213+
Buy a coffe to [Danvick Miller](https://twitter.com/danvickmiller), creator of this awesome package
184214

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

217+
## Roadmap
218+
219+
- [Solve open issues](https://github.com/flutter-form-builder-ecosystem/form_builder_validators/issues), [prioritizing bugs](https://github.com/flutter-form-builder-ecosystem/form_builder_validators/labels/bug)
220+
221+
222+
## Ecosystem
223+
224+
Take a look to [our awesome ecosystem](https://github.com/flutter-form-builder-ecosystem) and all packages in there
225+
226+
## Thanks to
227+
228+
### Contributors
229+
230+
<a href="https://github.com/flutter-form-builder-ecosystem/form_builder_validators/graphs/contributors">
231+
<img src="https://contrib.rocks/image?repo=flutter-form-builder-ecosystem/form_builder_validators" />
232+
</a>
233+
234+
Made with [contrib.rocks](https://contrib.rocks).

0 commit comments

Comments
 (0)