HTML_QuickForm::addGroupRule()

HTML_QuickForm::addGroupRule() -- Adds a validation rule for the given group

Synopsis

      require_once 'HTML/QuickForm.php';

void HTML_QuickForm::addGroupRule ( string $group , mixed $arg1 , string $type = '' , string $format = '' , int $howmany = 0 , string $validation = 'server' , bool $reset = FALSE )

Description

Adds a validation rule for the given group of elements

Only groups with a name can be assigned a validation rule. Use addGroupRule() when you need to validate elements inside the group. Also use addRule() if you need to validate the group as a whole.

Parameter

string $group: Form group name

mixed $arg1

Array for multiple elements or error message string for one element. If this is the array, its structure is the following:


array (
    'element name or index' => array(
        array(rule data),
        ...
        array(rule data)
    ),
    ...
    'element name or index' => array(
        array(rule data),
        ...
        array(rule data)
    )
)

rule data here matches the parameters' order and meaning for addRule() method.

Note: If this parameter is an array, all the subsequent parameters are ignored. You should pass all the modifiers for the rules being added within this array (see the example below).

string $type: (optional) Rule type. Use getRegisteredRules() to get types. You can also pass a classname for a descendant of HTML_QuickForm_Rule or an instance of such class.

string $format: (optional) Required for extra rule data

integer $howmany: (optional) How many valid elements should be in the group

string $validation: (optional)Where to perform validation: "server", "client"

boolean $reset: Client-side: whether to reset the element's value to its original state if validation failed.

Throws

Possible PEAR_Error values

Error code	Error message	Reason	Solution
QUICKFORM_NONEXIST_ELEMENT	Group '`$group` ' does not exist in HTML_QuickForm::addGroupRule()	Tried to add a rule for a non-existant group	Check the group name spelling
QUICKFORM_NONEXIST_ELEMENT	Element '`$elementIndex` ' not found in group '`$group` ' in HTML_QuickForm::addGroupRule()	`$arg1` is an array and contains an index for an element not present in a group	Check the element index spelling
QUICKFORM_INVALID_RULE	Rule '`$type` ' is not registered in HTML_QuickForm::addGroupRule()	Rule is not known to QuickForm	Check rule type spelling or use HTML_QuickForm::registerRule().

Note

since 2.5

This function can not be called statically.

Example

Using addGroupRule()


<?php
// a group of 4 checkboxes
$checkbox[] = &HTML_QuickForm::createElement('checkbox', 'A', null, 'A');
$checkbox[] = &HTML_QuickForm::createElement('checkbox', 'B', null, 'B');
$checkbox[] = &HTML_QuickForm::createElement('checkbox', 'C', null, 'C');
$checkbox[] = &HTML_QuickForm::createElement('checkbox', 'D', null, 'D');
$form->addGroup($checkbox, 'ichkABCD', 'ABCD:', array('&nbsp;', '<br />'));
// Simple rule: at least 2 checkboxes should be checked
$form->addGroupRule('ichkABCD', 'Please check at least two boxes', 'required', null, 2);

$idGrp[] = &HTML_QuickForm::createElement('text', 'lastname', 'Name', array('size' => 30));
$idGrp[] = &HTML_QuickForm::createElement('text', 'code', 'Code', array('size' => 5, 'maxlength' => 4));
$form->addGroup($idGrp, 'id', 'ID:', ',&nbsp');
// Complex rule for group's elements
$form->addGroupRule('id', array(
    'lastname' => array(
        array('Name is letters only', 'lettersonly'),
        array('Name is required', 'required', null, 'client')
    ),
    'code' => array(
        array('Code must be numeric', 'numeric')
    )
));
?>