Class: HTMLForm_control

void disable_xss_filters( )

Disables XSS filtering for the value of the control

By default, all values are filtered for XSS (Cross Site Scripting) injections (that is, the script removes event handlers, some javascript code, etc). While in 99% that's the right thing to do, it might happen that sometimes you don't want that - i.e. if you are building a fancy CMS and your prefered WYSIWYG editor also inserts some javascript, etc.

array getAttributes( mixed $attributes)

Returns the values of requested HTML attributes of the control

1.   /*
2.   create a text field named "name"
3.   (notice the use of the "&" symbol -> it's how we make it work in PHP 4, too!)
4.   */
5.  
6.   $obj = & $form->add('text', 'name');
7.  
8.   /*
9.   set some HTML attributes for the text control
10.   more specifically set it's "size" attribute to 2
11.   and it's "readonly" attribute
12.   */
13.  
14.   $obj->setAttributes(array('size' => 2, 'readonly' => 'readonly'));
15.  
16.   /*
17.   now read the attributes
18.   */
19.  
20.   $attributes = $obj->getAttributes(array('size', 'readonly'));
21.  
22.   /*
23.   The result will be an associative array
24.  
25.   $attributes = Array(
26.       [size]      => 2,
27.       [readonly]  => "readonly"
28.   )
29.   */

Tags:

Parameters:

void setAttributes( array $attributes)

Sets one or more HTML attributes of the control

1.   /*
2.   create a text field named "name"
3.   (notice the use of the "&" symbol -> it's how we make it work in PHP 4, too!)
4.   */
5.  
6.   $obj = & $form->add('text', 'name');
7.  
8.   /*
9.   set some HTML attributes for the text control
10.   more specifically set it's "size" attribute to 2
11.   and it's "readonly" attribute
12.   */
13.  
14.   $obj->setAttributes(array('size' => 2, 'readonly' => 'readonly'));

Parameters:

void setRule( array $rules)

Sets validation rules for the control

Here are the available rules:

• mandatory

Specified as 'mandatory' => array($errorMessageContainerBlock, $errorMessage)

Validates only if the control has a value

Available for HTMLForm_checkbox, HTMLForm_password, HTMLForm_radio, HTMLForm_select, HTMLForm_text, HTMLForm_textarea

1.           $obj->setRule('mandatory' => array('errorBlock1', 'This field is required'));

• minlength

Specified as 'minlength' => array($minimumLength, $errorMessageContainerBlock, $errorMessage)

Validates only if entered text's length is greater than $minimumLength

Available for HTMLForm_password, HTMLForm_text, HTMLForm_textarea

1.           $obj->setRule('minlength' => array('6', 'errorBlock1', '6 characters is minimum!'));

• maxlength

Specified as 'maxlength' => array($maximumLength, $errorMessageContainerBlock, $errorMessage)

Validates only if entered text's length is shorter than $maximumLength

Available for HTMLForm_password, HTMLForm_text, HTMLForm_textarea

1.           $obj->setRule('maxlength' => array('12', 'errorBlock1', '12 Characters is maximum', ));

• email

Specified as 'email' => array($errorMessageContainerBlock, $errorMessage)

Validates only if entered text is a valid email address

Available for HTMLForm_password, HTMLForm_text, HTMLForm_textarea

1.           $obj->setRule('email' => array('errorBlock1', 'Not a valid email address!'));

• emails

Specified as 'emails' => array($errorMessageContainerBlock, $errorMessage)

Validates only if entered text is a valid list of comma separated email addresses

Available for HTMLForm_password, HTMLForm_text, HTMLForm_textarea

1.           $obj->setRule('emails' => array('errorBlock1', 'Invalid email address/addresses!'));

• digitsonly

Specified as 'digitsonly' => array($errorMessageContainerBlock, $errorMessage)

Validates only if entered characters are all digits

Available for HTMLForm_password, HTMLForm_text, HTMLForm_textarea

1.           $obj->setRule('digitsonly' => array('errorBlock1', 'Only numbers allowed!'));

• compare

Specified as 'compare' => array($controlIDToCompareWith, $errorMessageContainerBlock, $errorMessage)

Validates only if control's value is equal with the value of the control indicated by $controlIDToCompareWith

Useful for when you want to check password confirmation

Available for HTMLForm_password, HTMLForm_text, HTMLForm_textarea

1.           $obj->setRule('compare' => array('password', 'errorBlock1', 'Password not confirmed correctly!'));

• captcha

Specified as 'captcha' => array($errorMessageContainerBlock, $errorMessage)

Validates only if control's value is the same as the characters seen in the HTMLForm_captcha control on the form

...therefore, you must also have a HTMLForm_captcha control on your form!

Available for HTMLForm_text

1.           $obj->setRule('captcha' => array('errorBlock1', 'Password not confirmed correctly!'));

• custom

This rule allows you to define custom rules.

Custom rules allow you to do customized validations within the $form->validate() method (as opposed to doing your custom validations after the $form->validate() method and thus giving feedback to the user only after validating for standard rules which would be awkward for the user because it will look like after passing all validation rules he will get error messages that did not showed up earlier)

It must be specified as 'custom' => array($callbackFunctionName, [optional arguments to be passed to the function], $errorMessageContainerBlock, $errorMessage)

Note that the custom function's first parameter will ALWAYS be the control's submitted value and the optional arguments to be passed to the function will start as of second argument!

Also note that the custom validation function MUST return TRUE on success or FALSE on failure!

Note that multiple custom rules can also be set:

It must be specified as

'custom' => array(

array($callbackFunctionName1, [optional arguments to be passed to the function], $errorMessageContainerBlock, $errorMessage), array($callbackFunctionName2, [optional arguments to be passed to the function], $errorMessageContainerBlock, $errorMessage)

)

1.           /*
2.               custom function that checks if a control's value is equal
3.               to a defined value
4.           */
5.           function textIs($controlsSubmittedValue, $valueToCompareTo)
6.           {
7.               if ($controlsSubmittedValue != $valueToCompareTo) {
8.                   return false;
9.               }
10.               return true;
11.           }
12.  
13.           /*
14.               add a text box control to the form
15.           */
16.           $obj = & $form->add('text', 'control_id');
17.  
18.           /*
19.               set the custom rule which will compare weather the text box control's submitted value
20.               is 'admin' and display the error message in specified error block if is not
21.           */
22.           $obj->setRule('custom' => array('textIs', 'admin', 'errorBlock', 'Text must be 'admin'!'));

Parameters: