-
Notifications
You must be signed in to change notification settings - Fork 2
Project's core documentation
This wiki page covers the functional part of this validation API, with code examples. This will not be thorough. For a full API documentation, please check the [Technical Documentation] (http://ippontech.github.io/JSV_API/JSDoc)
This page explains each functionality with a code example. Though, in order to minimise the overall output, we'll use the following HTML for all code snippets :
<html>
<head>
<title>JSV Documentation</title>
<head>
<body>
<form action="/send" method="POST">
<div>
<label for="firstname">Firstname: </label>
<input type="text" name="firstname" />
</div>
<div>
<label for="sex">Sex: </label>
<select name="sex">
<option value="M">Male</option>
<option value="F">Female</option>
</select>
</div>
<div>
Choose 2 interests:
<label><input type="checkbox" name="interest" /> Sport</label>
<label><input type="checkbox" name="interest" /> Computer science</label>
<label><input type="checkbox" name="interest" /> Music</label>
</div>
<div>
<input type="submit" value="Send" />
</div>
</form>
<script type="text/javascript" src="jsv.js"></script>
<!-- Example code should be placed here -->
</body>
</html>In this code, right after the "form" part, you can see a Javascript import :
<script type="text/javascript" src="jsv.js"></script>This imports our validation engine. Once it's done, we need to instantiate it :
<script type="text/javascript">
jsValidator = new JSValidator('myFormId',
new Array(
new JSValidator.Rule('firstname', 'NotNull', {'message': 'Firstname should not be empty'}),
new JSValidator.Rule('interest', 'ChooseSome', {
'message': 'You cannot choose more than 2 interests at once',
'max': 2
})
)
);
</script>In this constructor, you'll need to provide the HTML form's id, and an array of Validation Rules. Those contain 3 parts :
- the name of the element they're related to
- the constraint name (can be whatever you want)
- an array of related properties (message, size, min, max, etc.), i.e. whatever extra information used in the validation process
From now on, our validator will be available in any of our JS code using the "jsValidator" variable.
In order for the validation to take place, you'll need two more steps :
- Write the validation rule's implementation, if it doesn't exist already (See Write validation code section)
- Define events on which validation should take place (See Bind Events section)
Your validation rules contain a constraint name, that should match a validation method. Out-of-box, the most common already exist :
- NotBlank: Checks for not null or empty value
- NotEmpty: Checks for empty value
- NotNull: Checks for null value
- Length: Checks for a value length, given a "min" and/or "max" size
- // TODO
The above validation rules should be sufficient for most of your need. For more complex scenarii, here's the way to implement your own :
- Create a new Javascript file, with a friendly name (we'll use "jsv-custom-rules.js" in this article")
- Put the file in the place it can be accessed by clients (the same folder as the "jsv.js" one should be good)
- In your HTML page, import you new file, like you did for the "jsv.js" one
<script type="text/javascript" src="jsv-custom-rules.js"></script>- Assuming your custom validation rule is name "ChooseSome", here's the code would write in the "jsv-custom-rules.js" :
JSValidator.Rule.prototype.ChooseSome = function(value, params, fieldName, validator) {
/*
Validate the field (i.e. return "true") only if number of checked values is
lower or equals to the "max" attribute
*/
return value.length <= params.max;
};There you go ! You now have a validation rule for your "ChooseSome" constraint. Now's the fun part : binding the field's validation to an event.
At this point, you have initialized the validator, defined your rules, and written you custom validation rules. Now, you need to tell the application when to actually validate your field. For instance :
<script type="text/javascript">
jsValidator.getFieldWithName("firstname").bindValidationToEvent("change")
.addPreValidationProcess(function(event, field){
console.log("Value has changed. Wait for the validation...");
})
.addPostValidationAfterMessageProcess(function(event, field, ruleViolations){
console.log("Validation done. See the result")
});
</script>The first line gets the "firstname" field using the validator. Then it binds the "change" event on it. This method returns an objet you can add behaviour to. In this example, we choose to execute some code before and after the validation takes place.
In other words, each time the firstname's value changes, the application will execute your pre-validation code, execute the validation, and execute your post-validation code.
There is a lot more this API can do, but this example should be straightforward enough to be well understood.
In this part, we'll see all the API's possibilities, and go over them with some code example.
There are 3 levels you can interact with :
- Application : functions are accessible through the "JSValidator" object
- Field : functions are available through a combination of an element of your form that should be validated, and the event you bind it to
- Element : functions are available through a combination of an element that trigger the validation of other elements and the event you bind it to
Although "Field" and "Element" level look very similar, this distinction allows you to go factories amounts of javascript code. For example, at the field level, what we would tell our application is : "given a field and an event, do this", whereas at the element level, it would be : "When you click this button over there, launch the validation on those elements". With the latter example, the custom code you write will be executed for each element that has to be validated with this rule.