For the case if someone still needs info about this function, I share my findings. Actually, one can study its source code presented just inline the documentation. This is how I managed the case study below to work.
Suppose we have CActiveForm:
<?php $form = $this->beginWidget('CActiveForm', array(
'id' => 'login-form',
'enableClientValidation' => true,
'clientOptions' => array(
'validateOnSubmit' => true,
Also suppose we need additional submit button, performing and action which is different to normal submit (for example, this could be ‘Forgot your password?’ button in login form).
echo CHtml::submitButton(Yii::t('t', 'Send me a new password'), array('id' => 'forgotsbmt', 'submit' => CController::createUrl('user/forgot')));
It is ready to work for you, except for one important point: you would probably want to change validation rules on the client for this special case, because required password is apparently missing. Of course, you could do the same thing with server-side validation. But what if you want to do this on client?
Here clientChange comes in handy.
Before we can add it into the form, please note that clientChange is protected method, so you can’t use it straight away. Lets define a derived class helper:
class CustomCHtml extends CHtml
public static function clientChange($event, &$htmlOptions)
Now we can add the following line into the form:
$a = array('onclick' => 'prepare();',
'id' => 'forgotsbmt',
'live' => true,
'submit' => CController::createUrl('user/forgot')));
We define our own element ID, because otherwise Yii will play with its own sequence of IDs, which may be unpredictable (for example, change depending from element position in a page). It’s essential to specify ‘live’, because it’s the option instructing Yii make use of ‘id’. Also it’s important to specify ‘submit’ parameter, because it “notifies” Yii about our intention to change form submission. As ‘submit’ is now bound to the required element, we should remove it from submitButton itself.
echo CHtml::submitButton(Yii::t('t', 'Send me a new password'), array('id' => 'forgotsbmt'));
Please, note that prepare is invoked before standard code for form submission.
Finally you should register client script with prepare() function:
// for example, validate unimportant form fields
That’s all. Hope this helps.