JFormValidate is a Yii extension dedicated to provide Javascript Form Validation feature, for the Yii framework. This extension relies on an existing JQuery plugin that provides all the logic and functionnalities for the actual client-side Form validation. It is a powerful plugin, with plenty of intresting features that are described in its official documentation.
The released archive contains following files and folders :
'jformvalidate' => array (
'class' => 'application.extensions.jformvalidate.EJFValidate',
'enable' => true
),
'import'=>array(
...
'application.extensions.jformvalidate.EHtml',
...
)
Now, the extension will be loaded the first time it is needed, but of course it is also possible to add it
to the preload sequence.
The 'enable' initialization argument (default to true) can be used to
easely enable/disable the jformvalidate extension.
For more information on extensions, please refer to the
Yii Documentation.
Ok, let's see it in action ! For this first example, and assuming that the extension is correctly installed, we'll add Javascript validation
to the Contact form that is automatically created with Yii skeleton application.
This only requires to modify the corresponding view file, as describes below :
CHtmlwith
EHtml
That's it ! The contact form is now validated on the client side, according to the rules defined by the corresponding Yii model. Of course there are some configuration and CSS to set up in order to get a nice design, but the form validation is up and ready.
The EHtml class wraps all helper static methods from the CHtml Yii core class, and by doing so, collects information on the form that is being built. When the endForm() method is invoked, all this information is used to generate a javascript initialisation object for the JQuery Plugin validation. Therefore, this extension can be considered as some sort of adaptater/converter between validation rules defined by a Yii model, and validation rules implemented by the JQuery Validate plugin.
This version supports Yii 1.1 Branch but very few changes (if not no changes at all) must be done on your forms to be able to work fine with it.
Yii::app()->jformvalidate->activeTextField($model,'username');that is you were using the application component and not the EHtml class, you must now call :
EHtml::activeTextField($model,'username');and use the EHtml class !
Please note that method and class based validators are not supported by this extension, as it is not possible to automatically produce a JS code from a specific piece of PHP code (if you know how to do it, be my guess).
In this version, the following set of Yii built-in validators is supported :
If you need to validate user inputs on the client side, with a rule that is not (yet) implemented by this extension
you can do so, by using the pseudo validator provided with the extension.
This validator is a standard Yii validator class (it inherits from CValidator) but it is describes as pseudo
because its only goal is to wrap calls to Javascript validators which are part of the underlying JQuery plugin.
Therefore, when the pseudo validator is called by the Yii framework to validate an attribute, it always return true.
Let's take a look at an example. The JQuery Plugin has a validator rule called remote which
is used to validate a user entry through an ajax call to the server. So, let's say we want the user to enter his/her email, and that this email must not be already in use (this
rule is equivalent of the Yii unique rule). The initialisation value for the remote validator, is the url that is in charge of testing email unicity.
In the model, we add the following rule :
array('custom1', 'application.extensions.jquery-form-validator.ECustomJsValidator',
'rules' => array(
'remote' => 'index.php?r=Jsvform/remoteValidate'
),
'messages' => array(
'remote' => '{attribute} already registred'
)
),
..and that's it. Ok, you have to add the actionRemoteValidate() method to the JsvformController, but that's an easy task.
As you can see in the example above, the ECustomJsValidator class accepts a rule and a messages parameters, as described by the JQuery Plugin documentation.
Implementing ajax submition with client-side validation is simple, as it doesn't require anything else
than what is required by Yii ! A call to EHtml::ajaxSubmitButton() is enough to inform the Extension that
ajax submition is needed. When this function is invoked, the JFormValidate extension will handle javascript
creation and event handler registration instead of Yii.
For a complete example, take a look at sample form13 and form14.
In case an input field is not valid on the client-side, an error message is displayed. This error message comes from :
In the configuration file, it is possible to set some initialization parameters.
In this version of the extension, only a reduced set of the Yii CHtml helpers methods have been wraped.
The JFormValidate extension provides also specific methods to perform specific tasks.
The JQuery Validate plugin allows to overload the submit default handler (see related documentation). If you choose to do so, you must include a call to $.fn.EJFValidate.restoreName() in your own submit hanlder. This javascript function is provided with the extension because a call to some CHtml helpers method, generates HTML input elements with duplicated names. The problem is that the JQuery Validate Plugin works with input elements names, and duplicates name are not welcomed. The Extension will temporary remove duplicate name, and they must be restores before form submition. That's what the restoreName javascript function does. Below is an example of how is it possible to overload the submit handler :
<?php
echo EHtml::beginForm();
EHtml::setOptions(array(
// ... put other options here ...
'submitHandler' => 'function(form){
$.fn.EJFValidate.restoreName();
alert("submting the form");
}'
));
?>
Check the sample form7 and form8 for live examples.
Note that starting from version 1.0.4, all customizable hanlders available in the JQuery Validate Plugin options, can be overloaded with the same principle. This can be done at the form level (like in the example above) and of course at the configuration level, in your application configuration file, when declaring the EJFValidate extension.
Copyright (c) 2009-2010 by Raoul All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Raoul nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE