Documentation

for code documentation please go here
List of content :

• Introduction
• Main features
• Usage (Simple)
• Usage (Advanced)
• Defining new field type
• Custom Validation (Under construction)
• Fields generic parameters reference
• Field Types and parameters reference
• To-do
• Change log

Introduction : [top]

Author : Sina Salek (http://sina.salek.ws)
Website : http://combovalidation.sourceforge.net

This class is meant to validate HTML forms via PHP and also JavaScript  in the simplest possible way. all you need to do is to create an array of form fields information with require parameters and then call few methods.

Notice : As i mentioned before, this class works pretty fine in most of the circumstances unless you define a wrong array. Unfortunately there is no validation for the options you pass to the class so when you set a wrong parameter, all you see is a wrong behavior. Therefore,  please check the array structure with the bundled working examples and also this manual and make sure that you defined it correctly. and if the problem still remains then report it as bug.

Notice : This document currently only covers the basic features of this class, for the advanced features such as defining a new field type, customizing error display and validation functions check out bounded examples , inside "examples" folder.

Main features : [top]

• Customizable
• Validation : (defining new field types, overriding validation functions , using regex , etc...)
• View : ability to choose between various ways of showing errors. currently "alert,div , nearFields, pageCenterDiv, formCenterDiv ,customizedDiv" are supported out of the box. and it's also possible to override the display function and show errors in the way you want.
• Cross browser (IE6+, Firefox2+, Opera7+, Safari3+, All Mozilla based browsers)
• Very well tested. More than 30 projects are currently using it
• Easily integrate able , All of the PHP functions used in the class have prefix and also accepts prefix for JavaScript for preventing conflict with other JavaScript in the application
• Ajax support : No official Ajax support at the moment  but since you can completely overwrite the built in validation functions and error display functions you can do the validation with your own Ajax framework
• Light weight : Because it does not use any JavaScript framework.
• Extensible : Some design patterns like factory and chain of commands have been used in both JavaScript and PHP sides for ease of extensibility. Code is documented and also name of all of the methods and functions are self described.
• PHP 4 & 5 compatible
• Multilingual
• XHML Valid

Usage (Simple) : [top]

• Step 1 : including require files
  

  <?php
  require_once('lib/PEAR.php');
  require_once('lib/common.inc.php');
  require_once('lib/classesCore.class.inc.php');
  require_once('lib/compatibility.inc.php');
  require_once('validation.class.inc.php');
?>

• Step 2 : Initializing class and defining an array about all the form fields that need validation and set require parameters for each one of them
  

  <?php
$validation=cmfcValidation::factory('v1',array(
    'formName'=>'myForm',
    'displayMethod'=>'alert',//possible values : alert,div,nearFields,pageCenterDiv,formCenterDiv,customizedDiv
    'fieldsInfo'=>array(
        "contactInfo[name]"=>array(
            'title'=>'Name',
            'type'=>'string',
            'param'=>array(
                'notEmpty'=>true
            )
        ),
        "contactInfo[email]"=>array(
            'title'=>'Email',
            'type'=>'email',
            'param'=>array(
                'notEmpty'=>true
            )
        ),
        "contactInfo[subject]"=>array(
            'title'=>'Subject',
            'type'=>'string',
            'param'=>array(
                'notEmpty'=>true,                           
                'lengthMin'=>10,
                'lengthMax'=>100,
                'regexp'=>'/agreed/i',//php regex with preg_match
                'jsRegexp'=>'/agreed/i',//javascript regex with preg_match
                'regexpDescription'=>' : should contains "agreed" word',
            )
        ),
        "contactInfo[description]"=>array(
            'title'=>'Description',
            'type'=>'string',
            'param'=>array(
                'notEmpty'=>true
            )
        ),
        "contactInfo[tel]"=>array(
            'title'=>'Tel',
            'type'=>'number',
            'param'=>array(
                'notEmpty'=>true,
                'countMin'=>5,
                'countMax'=>7
            )
        ),
        "contactInfo[age]"=>array(
            'title'=>'Age',
            'type'=>'number',
            'param'=>array(
                'notEmpty'=>true,
                'countMin'=>2, //min number of characters
                'countMax'=>2, //max number of characters
                'min'=>18, //min value
                'max'=>60 //max value
            )
        ),
        "contactInfo[website]"=>array(
            'title'=>'Website',
            'type'=>'url',
            'param'=>array(
            )
        ),
        "contactInfo[subscription]"=>array(
            'title'=>'Subscription',
            'type'=>'checkBox',
            'param'=>array(
                'notEmpty'=>true,
            )
        )
        
    )
));
?>

• Step 3 : customizing error messages value which is useful if your application supports other languages (optional)
  

  <?php
$validation->setOption('messagesValue',array(
    CMF_ValidationV1_Error=>'Unknown error',
    CMF_ValidationV1_Is_Not_Valid_Email=>'"__value__" in __title__ is not valid email',
    CMF_ValidationV1_Is_Not_Valid_Url=>'"__value__" in __title__ is not valid url',
    CMF_ValidationV1_Is_Not_Number=>'"__value__" in __title__ is not number',
    CMF_ValidationV1_Is_Not_Within_Range=>'"__value__" of __title__ is not within this range (__min__,__max__)',
    CMF_ValidationV1_Is_Not_Within_Count_Range=>'"__value__" of __title__ is not within this count range (__min__,__max__)',
    CMF_ValidationV1_Is_Empty=>'__title__ value should not be empty',
    CMF_ValidationV1_Is_Not_Selected=>'__title__ is not selected',
    CMF_ValidationV1_Is_Not_Within_Length_Range=>'"__value__" of __title__ is not within this length range (__min__,__max__)',
    CMF_ValidationV1_Is_Not_String=>'__title__ is not string',
    CMF_ValidationV1_Is_Not_Match_With_Pattern=>'__title__ is not match with __desc__',
    CMF_ValidationV1_Field_Does_No_Exists=>'__title__ field "__fieldName__" does not exists'
));
?>
• Step 4 : calling require methods for javascript validation inside page body tag
  
  <body>
<?php
  $validation->printJsClass();
  $validation->printJsInstance();
?>
<form> ...
• Step 5 : validating submitted form via PHP
  
  
  <?php
  /**
   * validating form via package
   */
  $validateResult = $validation->validate($_POST);
  
  if (empty($validateResult)) {
      $messages[] = 'Bingo!';
  } else {
      foreach ($validateResult as $r) {
          $messages[] = $r->getMessage();
          $successfulSubmit = 0;
      }
  }
?>


Usage (Advanced) : [top]

• Defining new field type
  

  <?php  
$validation=cmfcValidation::factory('v1',array(
    'formName'=>'myForm',
    'fieldTypesInfo'=>array(
        'age'=>array(
            'validationHandler'=>array(
                'function'=>'validateAge' //name of the function or array of the object method array(&obj,'methodName')
            ),
            'jsValidationHandler'=>array(
                'function'=>'validateAge' //name of the function or array of the object method array(&obj,'methodName')
            )
        )
    ),
    ...
?>
  Require PHP function :
  <?php  
function validateAge($validation,$fieldsValues,$fieldInfo,$patternName) {
    $fieldValue=$fieldsValues[$fieldInfo['headName']];
    $isValid=false;
    if (is_numeric($fieldValue))
        if ($fieldValue>=1 and $fieldValue<=100)
            $isValid=true;
    if (!$isValid)
        return $validation->raiseError('Age should be number and between 1-100' ,'', PEAR_ERROR_RETURN, NULL, array('title'=>$fieldInfo['title'],'value'=>$fieldValue));
}  
?>
  Require Javascript function : 
  <script>  
/**
* function for validating new field type
 */
function validateAge(validation,fieldInfo,fieldValue) {
    if (fieldValue>=1 && fieldValue<=100)
       return '';
    else
       return validation.raiseError('__title__ should be number and between 1-100','','ERROR_RETURN',null, {'title':fieldInfo['title']} );
}  
</script>

  You can now use "age" as field type for any of fields you want :)

Fields generic parameters reference : [top]

• title //string , title of the field that will be use in error messages
• type //string , field type name. can be name of a custom field type
• likeType //string, base field type name. when you have a custom field type you can choose its base type. for example when type is "age" base type can be number
• jsMessageBoardId //string, id of the field message holder html element (can be a DIV), useful if display method is nearfields
• type //string, field type name
• param //array, field type specific parameters

Field Types and parameters reference : [top]

• string
• notEmpty //Boolean : prevent field value from being empty
• lengthMin //integer : minimum acceptable number of string characters
• lengthMax //integer : maximum acceptable number of string characters
• regexp //string : PHP preg_match compatible regular expression. sample (/agreed/i)
• jsRegexp //string : JavaScript compatible regular expression. sample (/agreed/i)
• regexpDescription //string : message describing conditions defined in regex for showing to user ,sample (should contains "agreed" word')
• email
• notEmpty //boolean : prevent field value from being empty
• number
• notEmpty //boolean : prevent field value from being empty
• countMin //integer : minimum acceptable number of numbers , similar to lengthMin but only for numbers
• countMax //integer : maximum acceptable number of numbers , similar to lengthMax but only for numbers
• min  //integer : smallest acceptable number
• max //integer : biggest acceptable number
• url
• notEmpty //boolean : prevent field value from being empty
• checkbox (for checking HTML input checkboxes)
• notEmpty //boolean : prevent field value from being empty
• dropDownDate //currently only this structure can be validated : fieldName[year] , fieldName[month], fieldName[day]
• notEmpty //boolean : prevent field value from being empty
• password
• notEmpty //boolean : prevent field value from being empty
• confirmationFieldName //string : name of the password confirmation field
• array
• notEmpty //boolean : prevent field value from being empty

To-do : [top]

• Better error reporting for class methods and options
• Validation for fields info and parameters
• Making it Jquery compatible (optional)
• Validation should work with multiply forms in one page (by adding formName item to each fieldInfo)
• Single JavaScript class in web page with multiply instance, validation instances should be connected
• Special methods for ease of validation via Ajax
• Support three type of messages , warning , information , error
• Compress JavaScript's

Change log : [top]

• in Firefox when form defines in non w3c way, Firefox can't find the fields inside it. it should throw an error
• getElementsByName() issue with multiRadioBoxes and multiCheckBoxes solved 
• supporting for new type "array"
• optimizing getFormFieldObject() for large forms
• if formName does not define, it will for the fields in the whole document
• support finding the field value via only field name without pattern name
• tested with PHP 4.x and PHP 5.2.x
• completely tested with IE 6.x,7.x , Firefox 2.x , Opera 9.x , Safari 3.x
• Ajax support via completely overriding object display or validation function
• custom field type
• customizing error messages
• override display function
• custom new display modes
• overriding or extending validation functions (validate, validateAfter, validateBefore)
• limited custom validation for fields which have need regular validations like notEmpty and also some more
• chain of commands pattern support for JavaScript and PHP
• validate fields with regular expression (JavaScript & PHP)
  

Hope you enjoy it, any kind of contributions are welcome :)
This document has been created with Kompozer  (Great open source HTML editor)