Skip to content

Commit a87b7d8

Browse files
crsanticrsanti
committed
Added samples to README.md
1 parent a9a0e45 commit a87b7d8

1 file changed

Lines changed: 29 additions & 147 deletions

File tree

‎README.md‎

Lines changed: 29 additions & 147 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
# lcFormValidation Library ![build status](https://travis-ci.org/Lemoncode/lcFormValidation.svg?branch=master "Build Status")
1+
# lcFormValidation
2+
![build status](https://travis-ci.org/Lemoncode/lcFormValidation.svg?branch=master "Build Status")
23

3-
lcFormValidation is a form library validation:
4+
LcFormValidation is a small JavaScript library that provides you form validation. Validate your viewmodel either on client or server side with Node.js.
5+
It is third party / framework agnostic, so you can easily add it in your stack, but it integrates quite well with libraries like React / Redux.
46

5-
* Heavily based on JavaScript (no html attributes annotations).
6-
* Full async, all validations are processed as async.
7-
8-
lc-FormValidation is third party / framework agnostic, although it will integrate quite well with libraries like React / Redux.
7+
- Heavily based on JavaScript (no html attributes annotations).
8+
- Full async, all validations are processed as async using native [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) (LcFormValidation already gives you a polyfill for browsers that do not support promises).
99

1010
# Why another form library? #
1111

@@ -17,161 +17,43 @@ Form validation is a complex issue, usually we can find solutions that cover the
1717

1818
* Validations are tightly coupled to e.g. directives or markup is not easy to reuse this validation code in e.g. server side (universal javascript).
1919

20-
# Approach #
21-
22-
In a form validation we can find features / code that can be placed in a base class (baseFormValidation):
23-
24-
* ValidateField: Validates a single field (e.g. call this when controls content change or the control looses the focus).
25-
* ValidateForm: Validates the whole form (all fields, plus global validations).
26-
27-
28-
Then we can inherit from that base class and define our own specific form validations:
29-
30-
* Add in the constructor of the inherited class the mappings between form field Id's and form and entity field Id, plus defining the validations per field to be executed.
31-
32-
The idea is to encapsulate all the common functionality in a base class, and create independent classes that will inherit from this base class to implement the validation of each individual form.
33-
34-
![validation class diagram](./ReadmeResources/validation.png "validation class diagram")
35-
36-
By following this approach:
37-
38-
* We encapsulate all the generic validation plumbing in a base class.
39-
* We can implement real world form validation in the specific classes.
40-
* We can benefit from external validation libraries (validate emails, url, iban ...), wihtout having to implement additional scaffolding (e.g. create a directive for this validation).
41-
* We can easily test (plain javascript framework agnostic):
42-
* The formValidationBase.
43-
* Each specific form validation class.
44-
* The generic validator helpers.
45-
* We can just run this javascript code in the client and serverside (e.g. node solution) ** (NOTE) We expect to create a sample showing how this could be implemented soon.
46-
47-
48-
# FormBaseValidation + Sample Form #
49-
50-
FormBaseValidation implementation (already implemented by the library):
51-
52-
53-
```
54-
export class BaseFormValidation {
55-
_validationEngine: IValidationEngine;
56-
57-
constructor() {
58-
this._validationEngine = new ValidationEngine();
59-
}
60-
61-
public validateField(vm: any, key: string, value: any, filter : any = consts.defaultFilter): Promise<FieldValidationResult> {
62-
return this._validationEngine.triggerFieldValidation(vm, key, value, filter);
63-
}
64-
65-
public validateForm(vm: any): Promise<FormValidationResult> {
66-
return this._validationEngine.validateFullForm(vm);
67-
}
68-
}
69-
```
70-
71-
Let's say we want to add validation support for a login form (validations to be performed: name field is required).
72-
73-
![login form](./ReadmeResources/loginForm.png "login form")
20+
## Overview
7421

75-
Login form validation implementation
22+
## Examples
7623

24+
### React examples
7725

78-
```
79-
public constructor() {
80-
super();
26+
#### Simple form
8127

82-
this._validationEngine.initialize([
83-
{formFieldName: 'fullname', vmFieldName: 'fullname'},
84-
{formFieldName: 'password', vmFieldName: 'password'}
85-
]);
28+
A simple form with fullname and password fields. Applied validations:
8629

87-
this._validationEngine.addValidationRuleToField('fullname',
88-
(vm, value) : Promise<FieldValidationResult> => {
89-
// Required field
90-
let isFieldInformed : boolean = (value && value.length > 0);
91-
// We could use string ID's if multilanguage is required
92-
let errorInfo : string = (isFieldInformed) ? "" : "Mandatory field";
30+
- Both fullname and password fields are mandatory (required validator + custom validator).
31+
[View source code](./samples/react/00%20SimpleForm)
9332

94-
const validationResult : FieldValidationResult = new FieldValidationResult();
95-
validationResult.type = "REQUIRED";
96-
validationResult.succeeded = isFieldInformed;
97-
validationResult.errorMessage = errorInfo;
33+
#### Signup form
9834

99-
return Promise.resolve(validationResult);
100-
}
101-
)
102-
}
103-
}
35+
A sign up form with username, password and confirm password fields with the next validation constraints:
10436

105-
```
37+
- username is mandatory and has to not exist on GitHub (required validator + custom validator).
38+
- password is mandatory and has to be minimum 4 characters length (minLength validator).
39+
- confirm password is mandatory and has to be the same value as password field (custom validator).
40+
[View source code](./samples/react/01%20SignupForm)
10641

42+
#### Quiz form
10743

108-
# How to run a sample #
44+
A simple quiz with three options where there has to be at least one checked option to pass the validation (custom global validation).
45+
[View source code](./samples/react/02%20QuizForm)
10946

110-
To install the stable version:
11147

112-
```
113-
npm install --save lc-form-validation
114-
```
48+
### jQuery examples
11549

116-
This assumes you are using [npm](https://www.npmjs.com/) as your package manager.
117-
If you don’t, you can [access these files on unpkg](https://unpkg.com/lc-form-validation/), download them, or point your package manager to them.
50+
#### Shopping form
11851

119-
Prerequisites: In order to get these examples up and running you will have to get installed typings and webpack node modules globally.
52+
A little shopping form where the user has to select a product with a version and optionally apply a discount code and enter its NIF. Validations applied:
12053

121-
```
122-
npm install typings -g
123-
```
124-
125-
If you want to start from the source code, follow this steps:
126-
127-
First download the source code from Git.
128-
129-
* Navigate to the lib folder (Note: this process will be less painful and added to preinstall when the following [bug](https://github.com/npm/npm/issues/10379) gets fixed on npm.
130-
131-
* Execute npm install
132-
133-
```
134-
lcFormValidation\lib> npm install
135-
```
136-
137-
* Execute build
138-
139-
```
140-
lcFormValidation\lib> npm run build
141-
```
142-
143-
* Navigate to one the samples folders, e.g. "samples/react/00 Simple Form".
144-
145-
```
146-
lcFormValidation> cd "samples/react/00 SimpleForm"
147-
```
148-
149-
* Execute npm install (this is connected to the local lib folder).
150-
151-
```
152-
lcFormValidation\lib\samples\react\00 SimpleForm> npm install
153-
```
154-
155-
* Execute npm start
156-
157-
```
158-
lcFormValidation\lib\samples\react\00 SimpleForm> npm start
159-
```
160-
161-
* Open your favourite browser and navigate to http://localhost/8080
162-
163-
If you want to run the unit tests that are located under the lib folder from the command line you will need to install karma-cli globally (npm install karma-cli -g), in order to run them, type from your command line "karma start".
164-
165-
# Samples forms implemented #
166-
167-
Samples running with React + Redux:
168-
* Basic login.
169-
* Signup form (including async validation against GitHub user api).
170-
* Quiz form.
54+
- The brand and product fields are mandatory (required validator).
55+
- The discount code is optional but needs to have a valid format if fulfilled (pattern validator).
56+
- NIF field is mandatory with a valid format (required validator + custom validator
57+
[View source code](./samples/jquery/Shopping%20form)
17158

17259
We are looking for contributors to implement samples and support for libraries such as Angularjs, Ember... if you would like to cooperate don't hesitate contacting us.
173-
174-
# Future Enhancements #
175-
176-
* Allow connecting with array fields / table like scenario.
177-
* Allow this to be easily be used outside the context of a web form (e.g. rest api server side)

0 commit comments

Comments
 (0)