ht5ifv

$(document).ready(function(){
   $('form').ht5ifv();
});

• classes
  When the value is a map it associates (sub)states errors with CSS classes
  If the developer wishes to change how the flagged error is displayed it may be changed here, as exemplified:

  $(document).ready(function(){
     $('form').ht5ifv({
      classes:{
  	  valid:'',                            //it suppress any visual effect for valid fields
  	  invalid:'my-error-class',            //use my-error-class to flag the invalid fields
        //If you intend to add new restrictions you may define here how those errors look like
  	  myNewRestriction:'restrictionError' 
      }                
     });
  });
  

  Alternatively a function may be provided. It receives the restriction as a parameter and must return a string with class names that will be used to flag the fields non conforming with the restriction.

  $(document).ready(function(){
     $('form').ht5ifv({
      classes: function($r){ return 'my-class-for-'+$r}              
     });
  });
  

  By defaults this option is assumed to be classes: function($restriction){ return 'ht5ifv-show-' + $restriction}
• targets
  The targets option defines where the flags should be raised. It may be defined in a compact form or detailed by restriction. In both cases the developer should provide functions which must return a set of jQuery DOM elements
  In the compact form it is a function which receives two parameters. The first one is the jQuery object representing the form field and the second is a string representing the type of error

  $(document).ready(function(){
   $('form').ht5ifv({
     targets:function($field,$type){return $field}              
   });
  });
  

  Alternatively it may be specified restriction by restriction as a map where the keys are the restriction names. In this case the function only receives one parameter, the jQuery object representing the field where the error occurs.

  $(document).ready(function(){
   $('form').ht5ifv({
      targets:{
          required:function($field){return $field},
          type:function($field){return $field.parent()},
          min:function($field){return $field},
          max:function($field){return $field},
          pattern:function($field){return $field},
          valid:function($field){return $field.parent()},
          invalid:function($field){return $field.parent()}        
      };
   });
  });
  

  The default is targets:function($field,$restriction){return $field}
• callbacks
  This option allows us to define callback functions which may be invoked every time a validate or check is performed or when a (sub)state transition occurs.
  Like targets it may be defined as an unique, two parameters, function or a map of restrictions and one parameter functions

  $(document).ready(function(){
   $('form').ht5ifv({
     callbacks:{
      valid: function($field){alert('The field is now valid.Thank you')},              
      invalid: function($field){alert('The field is invalid.Please fixe it')},              
      pattern: function($field){alert('The field does not very the pattern')},
      type: function($field){     //implicit restriction associated to the type in input elements 
          alert('The value in the field ' + $field.attr('name') 
          + ' is invalid for the type ' + $field.attr('type'))
      }
     }     
   });
  });
  

  By default it is a null function:callbacks:function($field,$restriction){}
  The definitions in this option have a global scope
• events
  The events option defines when the validate (test restrictions) or check (compute valid or invalid state) will be performed.
  This option is a map of only two keys, validate and check. The values must be a list of events in a space separated string. Each event should be defined in ht5ifv namespace. This is not strictly required but if omitted the ht5ifv won't unbind them when it is destroyed

  $(document).ready(function(){
   $('form').ht5ifv({
      events:{  
          validate: 'mouseover.ht5ifv focus.ht5ifv', 
          check: 'blur.ht5ifv mouseout.ht5ifv',
      }     
   });
  });
  

  The values by default are:

  events:{  
    validate: 'focus.ht5ifv keyup.ht5ifv', //validate every time a key is released or get the focus
    check: 'blur.ht5ifv'                   //only check status on blur 
  } 
  

  Note: By default this won't be applied to the fields select, radio and checkbox, as these fields have, also by default, local definitions. It means that if the developer needs to change the events for those fields she must define them in the correspondent local scope, not at global scope
• restrictions
  In a first form it (re)defines handlers to validate the field against a named restriction. It is a map where the keys are the restriction names and the values are functions which must return a boolean value.

  Those handlers receive two parameters, the first to identify the form field and the second is a boolean to flag if the empty fields should be ignored or not

  $(document).ready(function(){
   $('form').ht5ifv({
      restrictions:{  
          required: function($field){ //redefine the HTML5 required constraint/restriction
              var $v = $field.val();
              return $v && /^[^\s]*$/.test($v) //returns true if not empty and haven't white spaces
          }, 
          data-size: function($field,$ignoreEmpty){ 
            //New restriction, ex: < input type="text" data-size="9" name="tel"/ >
            var $v = $node.val();
            var $l = $v.length;
            var $m = $v.data('size');    
            return ($v =='' && $ignoreEmpty ) || $l == $m        
          }
      }     
   });
  });
  

  By default only two restrictions are defined globally, the required and the pattern. All others restrictions (type, min, max) are locally defined. Besides, the fields radio and checkbox also redefines the restriction required. That means, if the developer wants to redefine them, she must do it locally
  In order to simplify the definitions of new restrictions an alternative format is possible. Instead of associating the restriction name with a handler the developer may associate it with a map with following keys:

  • handler: Specify the handler to be invoked to determine if the restriction is satisfied or not
  • classe: The CSS classes to be applied when in error. The key is 'classe' with 'e' in the end to avoid the javascript reserved word 'class'
  • target: Where the error should be flagged
  • callback: A callback function to be invoked when a (sub)state transition occur

  $(document).ready(function(){
      restrictions:{
          data-size:{
              handler: function($field,$ignoreEmpty){ 
                var $v = $node.val();
                var $l = $v.length;
                var $m = $v.data('size');    
                return ($v =='' && $ignoreEmpty ) || $l == $m        
              }
              classe: 'my-class-for-size',
              target: function($field){return $('#errorMsg')}
              callback: function($field){
                  $('#errorMsg').html('The value in the fiel ' + 
                      $field.attr('name') + ' should be ' + 
                      $field.data('size') + 
                      ' caracters in length');
              }
          }
      }
  })
  

• filter
  This option gives more control over the fields on which the validation process occurs
  It receives, as a parameter, a set of all inputs, selects and textareas fields present in the form (or other selector) except inputs of type button, reset, submit and images. In the end it should return a set of inputs, selects or textareas. It could be a subset, the same set, or even a completely new set of elements of the received one.

  $(document).ready(function(){
      filter:function($fields){return $fields.not('[readonly]');}
  },      

  The filter by default is function($inputs){return $inputs.not('[type="hidden"]');}

• radio
  This element defines a local scope for definitions for inputs of type radio

  $(document).ready(function(){
   $('form').ht5ifv({
     radio:{  //the target option bellow will be used only by inputs of type radio
      targets: function($field,$r){return $field.parent()}
     }
   });
  });
  

  Notice that by default errors are flagged on the field itself. However for radios and checkboxes this doesn't produce any visual effects on browsers.
  We faced the temptation of defining the parent as the target for these two kinds of inputs but that could produce undesirable effects in situations where those inputs are not aggregated in an exclusive wrap element
  As so we left it to the developer to decide where she wants to see the errors. By default they won't be visually flagged. A code as the above example could be enough
  By default this option assumes the following values:

  radio:{
      restrictions:{
          required:function ($radioGroup,$node){
              return $radioGroup.filter(':checked').length  0
          }
      },
      events:{
          validate: 'change.ht5ifv',
          check: 'change.ht5ifv'
      }
  }
  

  Also notice that for radio inputs the validation invokes the handler not with the field itself as first parameter but with a set of all inputs of type radio sharing the same name within the same form.
• checkbox
  Similar to radio but for ckeckboxes
  By default this option assumes the following values:

  checkbox:{
      restrictions:{
          required: function($node){
              return $node.is(':checked')
          }
      },
      events:{
          validate: 'change.ht5ifv',
          check: 'change.ht5ifv'
      }		
  }
  

• select
  Similar to radio but for selects
  By default this option assumes the following values:

  select:{
      restrictions:{
          required:function ($node){
              return $node.val() != null;
          }
      },
      events:{
          validate: 'change.ht5ifv',
          check: 'change.ht5ifv'
      }
  }
  

• textarea
  This element defines a local scope for definitions for textarea form elements
  By default this element is empty
• types
  Defines local scopes for each input type. It is a map of following input types:

  • color
  • date
  • datetime
  • datetime-local
  • email
  • month
  • number
  • password
  • range
  • search
  • tel
  • text
  • time
  • url
  • week

  Additional the type _defaults is also used to define a local scope for unknown types.
  For each type above the implicit restriction is defined by default according to the W3C specifications. The restrictions min and max are defined to these types: date, datetime, datetime-local, month, number, range, time and week
  If the developer needs to add a new type it should be defined here
  Some examples

  • Add restricton min-length to password fields

    $(document).ready(function(){
     $('form').ht5ifv({
       types:{
        password:{
          restrictions:{
            'data-min-length':function($node,$ignoreEmpty){
              var $v = $node.val();
              var $l = $v.length;
              var $m = $v.data('minLength');    //see jquery 1.6 .data() method
              return ($v =='' && $ignoreEmpty ) || $l = $m        
            },
          }
        }
       }
     });
    });
    

  • Define the type city

    $(document).ready(function(){
     $('form').ht5ifv({
       types:{
        city:{
            restrictions:{
                type:function($node,$ignoreEmpty){
                    var $v = $node.val();
                    return ($v =='' && $ignoreEmpty ) || /^[a-z\-\s'.]+$/.test($v)       
                }
            }
        }
       }
     });
    });
    

  • Change date format to be mm/dd/yyyy (Simplified! See the function checkDateFormat in ht5ifv code )

    $(document).ready(function(){
     $('form').ht5ifv({
       types:{
        date:{
          restrictions:{
            type:function($node,$ignoreEmpty){
              return $node.val().match(/^(\d{2})\/(\d{2})\/(\d{4})$/)
            }
          }
        }
       }
     });
    });
    

callbackOnlyStatusTransitions: true, callbackOnlyErrorTransitions: true, ignoreEmptyFields: true, safeValidate: true, checkDisable:true
• browserValidate
  By default the ht5ifv turns off browser validation. Set this value to true if you want to use the browser internal validation cumulatively
• callbackOnlyStatusTransitions
  The callback function for (in)valid state is only invoked when a state transition occurs. Set this option to false if you need to receive a callback every time a check action is performed
• callbackOnlyErrorTransitions
  The callback function for any restriction is only invoked when, as result of a validation, the field enters into the correspondent error sub-state. Set this option to false if you need to receive a callback every time a validation is performed and the field enters or stays in error.
• ignoreEmptyFields
  By default empty fields are not validated, except for the required restriction. Set this option to false if you don't want to ignore it
• safeValidate
  A check action computes the state (valid or invalid) of a field as the result of a validation action for each restriction. A field is invalid if at least one validation evaluates to false.

  Normally a validation action must have a higher frequency of running than a check action. For example, a validation may occur every time a key is pressed and the check only occurs when the field loses the focus. However, as this is configurable it may happen that a check is performed without a previous validate action. This can leave the field in an incorrect situation where it is invalid and is not flagged as so.

  For that reason, by default, a check action triggers a validation event before computing the field state.

  This behaviour could be disabled by setting this option to false. It will be safe to do that if it is ensured that a validate event occurs always before a check event.
• checkDisable
  By default the disabled fields are not flagged. Set this option to false to also validate and check disabled fields
• validateOnSubmit
  Set this option to false if you don't want to perform validation on submit.
  Setting validateOnSubmit: false and browserValidate: true allows using ht5ifv to perform inline validation and the builtin browser validation to perform validation on submit

$.ht5ifv('extend',{        
    classes: function($restriction){return 'my-class-'+$restriction;}
}, true); //With third parameter true it overlap the global defaults