Class ActionActiveForm

CActiveForm provides a set of methods that can help to simplify the creation of complex and interactive HTML forms that are associated with data models.

The 'beginWidget' and 'endWidget' call of CActiveForm widget will render the open and close form tags. Most other methods of CActiveForm are wrappers of the corresponding 'active' methods in CHtml. Calling them in between the 'beginWidget' and 'endWidget' calls will render text labels, input fields, etc. For example, calling CActiveForm::textField would generate an input field for a specified model attribute.

What makes CActiveForm extremely useful is its support for data validation. CActiveForm supports data validation at three levels:

• server-side validation: the validation is performed at server side after the whole page containing the form is submitted. If there is any validation error, CActiveForm will render the error in the page back to user.
• AJAX-based validation: when the user enters data into an input field, an AJAX request is triggered which requires server-side validation. The validation result is sent back in AJAX response and the input field changes its appearance accordingly.
• client-side validation (available since version 1.1.7): when the user enters data into an input field, validation is performed on the client side using JavaScript. No server contact will be made, which reduces the workload on the server.

All these validations share the same set of validation rules declared in the associated model class. CActiveForm is designed in such a way that all these validations will lead to the same user interface changes and error message content.

To ensure data validity, server-side validation is always performed. By setting CActiveForm::$enableAjaxValidation to true, one can enable AJAX-based validation; and by setting CActiveForm::$enableClientValidation to true, one can enable client-side validation. Note that in order to make the latter two validations work, the user's browser must has its JavaScript enabled. If not, only the server-side validation will be performed.

The AJAX-based validation and client-side validation may be used together or separately. For example, in a user registration form, one may use AJAX-based validation to check if the user has picked a unique username, and use client-side validation to ensure all required fields are entered with data. Because the AJAX-based validation may bring extra workload on the server, if possible, one should mainly use client-side validation.

The AJAX-based validation has a few limitations. First, it does not work with file upload fields. Second, it should not be used to perform validations that may cause server-side state changes. Third, it is not designed to work with tabular data input for the moment.

Support for client-side validation varies for different validators. A validator will support client-side validation only if it implements CValidator::clientValidateAttribute and has its CValidator::enableClientValidation property set true. At this moment, the following core validators support client-side validation:

• CBooleanValidator
• CCaptchaValidator
• CCompareValidator
• CEmailValidator
• CNumberValidator
• CRangeValidator
• CRegularExpressionValidator
• CRequiredValidator
• CStringValidator
• CUrlValidator

CActiveForm relies on CSS to customize the appearance of input fields which are in different validation states. In particular, each input field may be one of the four states: initial (not validated), validating, error and success. To differentiate these states, CActiveForm automatically assigns different CSS classes for the last three states to the HTML element containing the input field. By default, these CSS classes are named as 'validating', 'error' and 'success', respectively. We may customize these CSS classes by configuring the CActiveForm::$clientOptions property or specifying in the CActiveForm::error() method.

The following is a piece of sample view code showing how to use CActiveForm:

<?php $form = $this->beginWidget('CActiveForm', array(
    'id'=>'user-form',
    'enableAjaxValidation'=>true,
    'enableClientValidation'=>true,
    'focus'=>array($model,'firstName'),
)); ?>

<?php echo $form->errorSummary($model); ?>

<div class="row">
    <?php echo $form->labelEx($model,'firstName'); ?>
    <?php echo $form->textField($model,'firstName'); ?>
    <?php echo $form->error($model,'firstName'); ?>
</div>
<div class="row">
    <?php echo $form->labelEx($model,'lastName'); ?>
    <?php echo $form->textField($model,'lastName'); ?>
    <?php echo $form->error($model,'lastName'); ?>
</div>

<?php $this->endWidget(); ?>

To respond to the AJAX validation requests, we need the following class code:

public function actionCreate()
{
    $model=new User;
    $this->performAjaxValidation($model);
    if(isset($_POST['User']))
    {
        $model->attributes=$_POST['User'];
        if($model->save())
            $this->redirect('index');
    }
    $this->render('create',array('model'=>$model));
}

protected function performAjaxValidation($model)
{
    if(isset($_POST['ajax']) && $_POST['ajax']==='user-form')
    {
        echo CActiveForm::validate($model);
        Yii::app()->end();
    }
}

In the above code, if we do not enable the AJAX-based validation, we can remove the performAjaxValidation method and its invocation.