h1. Content:

# "What's supported?":#Support
# "About how the module works":#About
# "Edit Mode":#EditMode
# "Auto Generated Confirm Elements":#ConfirmElements
# "Ajax Validations":#Ajax

h1(#Support). 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":#DeployToGAE )  _**(NEW)**_


h1(#About). About

_This module interfaces client side validation (jquery library used: "Jqvuery Validation Engine":https://github.com/posabsolute/jQuery-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@ or @siena.Table@ and the fields annotated with @siena.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 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._

h4. 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*


h2. 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:

bc. <script> jQuery(document).ready(function(){
 // binds form submission and fields to the validation engine
 $.each(jQuery(".TBV"), function(){
	 $(this).validationEngine();
 });
 });</script>@


bq. To add the needed scripts & stylesheets just call these tags: 
* @#{validation-css /}@ for the style sheets 
* @#{validation-scripts /}@ for the scripts needed.  

h3. 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 form @for:"Model.Field"@. for example @field:'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 the @name@ attribute is checked, if it's given then the @id@ 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 the @id@ attribute is checked, if it's given then the @name@ 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).

h5. 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 like @class='{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 @{yyyy-mm-dd}, {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.

# @#{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.
# @#{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 same @name@ 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).
# @#{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 type @java.utils.List@.
** Required @value@ attribute which is the name of certain field of objects in the items list. It sets the @value@ 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 the @title@ attribute.
** Optional @id@ attribute sets the @id@ attribute in the HTML element. If not provided then it'll be assigned the @title@ attribute.
** Optional @name@ attribute sets the @name@ attribute in the HTML element. If not provided then it'll be assigned the @title@ 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.
# @#{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 type @java.utils.List@.
** Required @value@ attribute which is the name of certain field of objects in the items list. It sets the @value@ 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 the @title@ attribute.
** Optional @id@ attribute sets the id attribute in the HTML elements. If not provided then it'll be assigned the @title@ 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.

h1(#EditMode). Edit Mode

h4. 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.

h3. 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@email.com", "123456"}



the controller method

bc. public static void editUser(long id){
	User user = User.findById(id);
	render(user);
}

the html tag

bc. #{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" />@
@<input type="text" id="name" name="email" value="email@email.com" />@

and so on.

h1(#ConfirmElements). AutoGenerated Confirm Elements

h3. 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 /}@*

h3. Usage

All what you need to do is to write your tag normally but with body. For example,

bc.  <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>
	#{/}


bq. Instead of <td> 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"@ and @name="{the name specified in the tag}Confirm"@

**Any comments, suggestions, or contributions are welcome**


h1(#Ajax). Ajax Validation

h3. about

The module now supports ajax validation for Form or Field. Here are the attributes you provide to use ajax validation.

h4. 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's @boolean@ attribute and should be set to true to enable ajax validation for this field. For example (@ajax:true@ or @ajax:false@)
* Required @ajaxUrl@ it's @String@ attribute and this is the url to which the validation request will be sent. For example (@ajaxUrl:'url/url'@)
* Optional @ajaxExtraData@ it's @String@ 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's @String@ attribute and should holds the msg to be shown to the user while waiting for a response from the server.
* Optional @ajaxError@ it's @String@ 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's @String@ 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'@)

h4. 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 sending @GET@ method to valiadte the form and @POST@ for the actual submission. if the @ajaxUrl@ is provided then this url will be used but with @GET@ method to validate only.

*The protocol goes as follows:*
# *Client* sends GET request with query string paramters @url?{fieldId1}={fieldValue1}&...etc@ to the  *Server*.
# Then *Server* responds with an array of arrays: @[[fieldid, status, errorMsg]]@. 
** For example @[["fieldId1", boolean,"errorMsg"],["fieldId2", false, "there is an error "],["fieldId3", true, "this field is good"]]@
  
_Since the form validation is asynchronously delegated to the form action, we provide two callback methods:_

@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 call

*Here are the attributes to be add these options to the form tag*

* Required @ajax@ it's @boolean@ attribute to enable ajax validation for this form.
* Optional @ajaxUrl@ it's @String@ attribute and it'll be used to send the @GET@ validation request.
* Optional @onAjaxBefore@ it's @String@ attribute and it should contains the name of a java script function with 2 parameters which will be like this @function(form, options)@ where @options@ will hold the validations options for this form and @form@ will contain the form html element.
* Optional @onajaxAfter@ it's @String@ attribute and it should contains a callback javascript function with 4 parameters like this @function(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.
bq. The default behavior if this callback is not provided is to submit the form after it passes the validation.

h1(#DeployToGAE). 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.*