Gentics Portal.Node PHP API
 All Classes Namespaces Functions Variables Pages
system\web\widgets Namespace Reference

Detailed Description

CActiveForm class file.

Author
Qiang Xue qiang.nosp@m..xue.nosp@m.@gmai.nosp@m.l.co.nosp@m.m Copyright © 2008-2010 Yii Software LLC http://www.yiiframework.com/license/ CActiveForm provides a set of methods that can facilitate creating a form associated with some data models. CActiveForm implements a set of wrapper methods that call the corresponding 'active' methods in CHtml}. For example, the textField} method is a wrapper of CHtml::activeTextField}. The 'beginWidget' and 'endWidget' call of CActiveForm widget will render the open and close form tags. Anything in between are rendered as form content (such as input fields, labels). We can call the wrapper methods of CActiveForm to generate these form contents. For example, calling CActiveForm::textField}, which is a wrapper of CHtml::activeTextField}, would generate an input field for a specified model attribute. Besides the wrapper methods, CActiveForm also implements an important feature known as AJAX validation. This feature may be turned on setting enableAjaxValidation} to be true. When the user enters some value in an input field, the AJAX validation feature would trigger an AJAX request to the server to call for validating the model with the current user inputs. If there are any validation errors, the corresponding error messages will show up next to the input fields immediately. The AJAX validation feature may greatly improve the user experience at entering data into a form. Because the validation is done on the server side using the rules defined in the data model, no extra javascript code needs to be written. More importantly, and the validation result is consistent with the server-side validation. And in case when the user turns off javascript in his browser, it automatically falls back to traditional validation via whole page submission. To use CActiveForm with AJAX validation, one needs to write both the view code and the controller action code. The following is a piece of sample view code: <?php $form = $this->beginWidget('CActiveForm', array( 'id'=>'user-form', 'enableAjaxValidation'=>true, )); ?> <?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(); } } The method performAjaxValidation is the main extra code we add to our traditional model creation action code. In this method, we check if the request is submitted via AJAX by the 'user-form'. If so, we validate the model and return the validation results. We may call the same method in model update action. On the client side, an input field may be in 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. They may be changed by configuring the options} property or specifying in the error} method. Sometimes, we may want to limit the AJAX validation to certain model attributes only. This can be achieved by setting the model with a scenario that is specific for AJAX validation. Then only list those attributes that need AJAX validation in the scenario in CModel::rules()} declaration. There are some limitations of CActiveForm regarding to its AJAX validation support. First, it does not validate with file upload fields. Second, it should not be used to perform validations that may cause server-side state change. For example, it is not suitable to perform CAPTCHA validation done by CCaptchAction} because each validation request will increase the number of tests by one. Third, it is not designed to work with tabular data input for the moment. Because CActiveForm relies on submitting the whole form in AJAX mode to perform the validation, if the form has a lot of data to submit, the performance may not be good. In this case, you should design your own lightweight AJAX validation. Qiang Xue qiang.nosp@m..xue.nosp@m.@gmai.nosp@m.l.co.nosp@m.m 1.1.1