Content:
What’s supported?
- It supports these annotations
InFuture, Equals, InPast, Match, Max, MaxSize, Min, MinSize, Required , URL, Email, Range
- It supports JPA Models.
- It supports Siena Module & Models. (NEW)
- It Works fine on Google App Engine (or any server that doesn’t support writing to local file system Deploy To GAE ) (NEW)
About
This module interfaces client side validation (jquery library used: Jqvuery Validation Engine)
This module is aimed at simplifying things for developers to be more productive and for those who didn’t work with js before to do client side validation easily. It’s also intended to support a lot of validation needs and make it easier for developers to use validation. The module works as follows:
- There’s a startup plugin called StartUp and the method onApplicationStartup() is overriden. It searches the
models
directory and returns all the file names ending with.class
. - It filters these files to get only models annotated with
Entity
orsiena.Table
and the fields annotated withsiena.Column
. Then it loads the classes and retrieves all the fields. - It checks for the validation annotations on the fields returned and map them to their corresponding validation strings ,that will be used in html, in a hashmap singleton in the
MapSignleton.java
.- The Map is paired this way
Map<Model_Name<Field_Name,Validation>>
. Then this map will be used in the attched fast tags to validate the inputs.
- The Map is paired this way
The supported annotations can be extended and more annotations can be added (I wish so). The validation library used is very flexible and can be extended easily. Also the module supports ajax validations per form or per field and custom functions. If anyone has anymore suggestions, ideas or whatever feel free to comment or suggest.
There’s a tag for every input under namespace jqv
#{jqv.Vform /}
#{jqv.text /}
#{jqv.textarea /}
and has optional closing tag#{jqv.checkbox /}
#{jqv.select /}
#{jqv.radio /}
#{jqv.date /}
for inputs that will be mapped to dates.#{jqv.checkboxList /}
#{jqv.radioList /}
#{jqv.pass /}
for password inputs.#{jqv.file /}
Inspired from the already existing validation module there’s an attribute that is called for
which will be in this form Model.field
as if you are calling it.The for
attribute’s required to validate the inputs, 'cause this is the only way to add valiadtions to the inputs so far(most of them). So I made it optional field.
You’re encouraged to Suggest more validations, enhancments or report bugs
Usage
There’re 2 javascript files jquery.validationEngine.js
, jquery.validationEngine-en.js
and 1 styleSheet file validationEngine.jquery.css
in the public folder in the module. These are the validation engine i’m using so You’ll need to add them to the to the head tag in your html page.
And you add this script to activate the Validation Engine and attach it to the Forms:
<script> jQuery(document).ready(function(){
// binds form submission and fields to the validation engine
$.each(jQuery(".TBV"), function(){
$(this).validationEngine();
});
});</script>@
To add the needed scripts & stylesheets just call these tags:
*#{validation-css /}
for the style sheets
*#{validation-scripts /}
for the scripts needed.
Now We Start with The available tags. h5. There’re generic attributes for all the tags except for check boxes and radio buttons:
- Required
for
attribute: Should be in this formfor:"Model.Field"
. for examplefield:'User.name'
. - Optional
group
attribute sets the name of the group which one of them will be required. - Any other attribute given will be unserialized to the html tag the same as done in the built-in form tag. For example
style:'display:none'
will be unserialized and the output will be sth like this <input type=“text” ...... style="display:none" />. Yet there’re attributes which will be used by the tags:- Optional
id
attribute sets an ID to the input element. If not provided then thename
attribute is checked, if it’s given then theid
will be given the same value, otherwise a default id will be given to the html element which is the field’s name. - Optional
name
attribute sets a name to the input element. If not provided then theid
attribute is checked, if it’s given then thename
will be given the same value, otherwise a default name will be given to the html element generated which is the field’s name. - Optional
class
attribute sets a class to the input element. If not provided then the model’s name will be assigned to it (and other classes will be added depending on the input tag).
- Optional
All the tags' names describe what they generate, but there’re some tags that have special attributes.
#{jqv.vform } #{/}
: It’s exactly the same as the regular Form Tag and it adds a class attribute to the form if not provided like class=‘TBV’ and if the class attribute is already given then it adds another class to it likeclass='{class provided by you} TBV'
.#{jqv.date /}
: It’ll output an html input of type text but validated with regex to be a date.- Optional
type
attribute sets one of the validations to this text field to match a date, datetime, or time formats . The default value will be date. The allowed types are: date, dateTime, time. the formats supported so far are, {HH:mm:ss} *24hrs mode*
. and you can use*'-' or '/'*
as separator for date. - ‘datepicker’ class will be added by default to the class attribute.
- Adding datepicker is To Be Implemeneted.
- Optional
#{jqv.textarea } #{/}
: It’ll output an html input in this format<textarea></textarea>
. It has optional closing tag#{/}
.#{jqv.file /}
: It’ll output an html input in this format<input type="file" {class} {id} {name}/>
- Optional
min
attribute sets the minimum size required for the path of the file. - Optional
max
attribute sets the maximum size allowed for the path of the file. - Optional
accept
attribute sets the allowed extensions for this file. - Optional
reject
attribute sets the forbidden extensions for this file.
- Optional
#{jqv.checkbox /}
: It’ll output an html input in this format<input type="checkbox" {class} {id} {name}/>
and group of checkboxes are defined by giving them the samename
attribute.- Optional
min
attribute sets the minimum number of checkboxes required to be checked. - Optional
max
attribute sets the maximum number of checkboxes allowed to be checked. - Optional
required
attribute shows that this checkbox must be checked. - Optional
group
attribute sets the name of the group of checkboxes which one of them should be checked. (can be replaced by min:1).
- Optional
#{jqv.checkboxList /}
: It outputs a list of check boxes in this form<label {class+Lbl}{for}>String</label><input type="checkbox" {class} {id} {name} {title} {value} />
.- Required
items
attribute which is a list of typejava.utils.List
. - Required
value
attribute which is the name of certain field of objects in the items list. It sets thevalue
attribute in the html element. - Required
title
attribute which is the name of certain field of objects in the items list. It sets the String in the label. - Optional
class
attribute sets the class attribute in the HTML element. If not provided then it’ll be assigned thetitle
attribute. - Optional
id
attribute sets theid
attribute in the HTML element. If not provided then it’ll be assigned thetitle
attribute. - Optional
name
attribute sets thename
attribute in the HTML element. If not provided then it’ll be assigned thetitle
attribute. - Optional
min
attribute sets the minimum number of checkboxes required to be checked. - Optional
max
attribute sets the maximum number of checkboxes allowed to be checked. - Optional
horizontal
attribute sets the direction of repetition to be horizontal. If not provided then a vertical repetition is implied.
- Required
#{jqv.radioList /}
: It outputs a list of check boxes in this form<label {class+Lbl}{for} >String</label> <input type="radio" {class} {id} {name} {title} {value} />
.- Required
items
attribute which is a list of typejava.utils.List
. - Required
value
attribute which is the name of certain field of objects in the items list. It sets thevalue
attribute in the html element. - Required
title
attribute which is the name of certain field of objects in the items list. It sets the String in the label. - Optional
class
attribute sets the class attribute in the HTML elements. If not provided then it’ll be assigned thetitle
attribute. - Optional
id
attribute sets the id attribute in the HTML elements. If not provided then it’ll be assigned thetitle
attribute. And it will be appended with each element’s index starting from 0. - Optional
name
attribute sets the name attribute in the HTML element. If not provided then it’ll be assigned the class name of the items. - Optional
required
attribute shows that this radio buttons are requierd to choose from them(you write{required:' '}
is enough). - Optional
horizontal
attribute sets the direction of repetition to be horizontal. If not provided then a vertical repetition is implied.
- Required
Edit Mode
What’s Edit Mode?
It’s a mode where you give the Validation form an object and then use the tags in the namespace jqv the edit mode makes use of the ‘for’ attribute in the tags to get the value of this field of this object and puts it as a default value for this input.
Usage
You give the #{jqv.vform /}{/}
an attribute edit:the-object-to-be-edited
. For example if there’s a user which is an object rendered from the controller and has the following attributes {name, email, pass} & values {“name-string”, “[email protected]”, “123456”}
the controller method
public static void editUser(long id){
User user = User.findById(id);
render(user);
}
the html tag
#{jqv.vform @Application.blala(), edit:user /}
#{jqv.text for:'User.name' /}
#{jqv.pass for:'User.pass' /}
#{jqv.email for:'User.email' /}
#{/}
The output will be (Without the dots)
<input type="text" id="name" name="name" value="name-string" />
<input type="password" id="name" name="pass" value="123456" />
@@
and so on.
AutoGenerated Confirm Elements
About
Sometimes we need to confirm some inputs so instead of writing tags for the input itself and the repeating yourself to write the confirm too. The confirm input will be generated Automatically and will be placed where you specify. It’s Available only for #{jqv.date /}
#{jqv.text /}
#{jqv.pass /}
Usage
All what you need to do is to write your tag normally but with body. For example,
<tr>
<td><label for="Useremail">Email</label></td>
<td>#{jqv.text for:'User.email'}</td>
</tr>
<tr><td>Confirm Email: </td> <td>%s</td></tr>
#{/}
Instead of
you can use whatever you want. The most important thing is that you need to put the %s where you want to place your confirm element.This should be written in the body of the tag you wnat to confirm it.* The previous example will produce input html element with the same attributes and values for the email tag but the id will be changed to
id="{the id specified in the tag}Confirm"
andname="{the name specified in the tag}Confirm"
Any comments, suggestions, or contributions are welcome
Ajax Validation
about
The module now supports ajax validation for Form or Field. Here are the attributes you provide to use ajax validation.
For Field Ajax Validation
Validating Fields using ajax is easy and simple. First, all client side validations are processed (like
required
and so on). If there’s an error and the validation failed, then no need to continue to ajax validation! Otherwise (meaning the validations passed) then a validation request is sent to the server using ajax and response status will be cached. If the form is submitted then no ajax field validations will occur, it’ll just check the last cached result if it was true or false.The protocol goes as follows.
- Client sends GET request with query string paramters
url?{fieldId}={fieldValue}
to the Server.- Then Server responds with an array:
[fieldid, status, errorMsg]
.
- The status can be true or false to indicate if the validation passed or not.
- The errorMsg that will be shown to the user. If the status is true then It’ll be shown in green prompt. If the status is false then it’ll be shown in red prompt.
- the fieldid is id of html element was validated.
NOTE: The following attributes are valid for all text inputs (pass, date, textarea, text, and file)
- Required
ajax
it’sboolean
attribute and should be set to true to enable ajax validation for this field. For example (ajax:true
orajax:false
)- Required
ajaxUrl
it’sString
attribute and this is the url to which the validation request will be sent. For example (ajaxUrl:'url/url'
)- Optional
ajaxExtraData
it’sString
attribute and this to hold extra data that will be sent beside the value of this field and should be given in the form of Query String. For example (ajaxExtraData:'id=1&s=5'
)- Optional
ajaxLoad
it’sString
attribute and should holds the msg to be shown to the user while waiting for a response from the server.- Optional
ajaxError
it’sString
attribute and should holds the msg to be shown to the user when the validation fails (meaning that the validation status in the server response is false). For example (ajaxError:'already used name'
)- Optional
ajaxOK
it’sString
attribute and should holds the msg to be shown to the user when the validation passes (meaning that the validation status in the server response is true). For example (ajaxOK:'Valid Name'
)For Form Ajax Validation
Validating Forms using ajax is now easy and simple. All what you need to do is to specify some attributes to enable the ajax validations, provide url, and even some callback functions. If you didn’t provide
ajaxUrl
then the action url of the form will be used for sendingGET
method to valiadte the form andPOST
for the actual submission. if theajaxUrl
is provided then this url will be used but withGET
method to validate only.The protocol goes as follows:
Since the form validation is asynchronously delegated to the form action, we provide two callback methods:
- Client sends GET request with query string paramters
url?{fieldId1}={fieldValue1}&...etc
to the Server.- Then Server responds with an array of arrays:
]
.
- For example
,["fieldId2", false, "there is an error "],["fieldId3", true, "this field is good"]]
onBeforeAjaxFormValidation(form, options)
is called before the ajax form validation call, it may return false to stop the request
onAjaxFormComplete: function(form, status, json_response_from_server, options)
is called after the ajax form validation callHere are the attributes to be add these options to the form tag
- Required
ajax
it’sboolean
attribute to enable ajax validation for this form.- Optional
ajaxUrl
it’sString
attribute and it’ll be used to send theGET
validation request.- Optional
onAjaxBefore
it’sString
attribute and it should contains the name of a java script function with 2 parameters which will be like thisfunction(form, options)
whereoptions
will hold the validations options for this form andform
will contain the form html element.- Optional
onajaxAfter
it’sString
attribute and it should contains a callback javascript function with 4 parameters like thisfunction(form, status, json_response_from_server, options)
which will be called after the server sends its response.Status
is the status of the validation whether it passed or failed.json_response_from_server
is speaking itself.The default behavior if this callback is not provided is to submit the form after it passes the validation.
Deploy To GAE
Google app Engine caused some problems when I tried to deploy the siena module because it doesn’t allow the web app to write to local file system. The module needs to update the validation rules file called “jquery.ValidationEngine-en.js”. So now I just check if the app iss allowed to write to the file system or not. You’ll just need to run the project at least once directly before Deploying so the module updates the validation rules file and it’ll be deployed updated.