PEAR Manual
Prev |  | Next

# 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

Table 41-1. 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

Example 41-1. 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 one box', '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')
        )
    ));
    ?>

Prev | Home | Next
HTML_QuickForm::addRule() | Up | HTML_QuickForm::addFormRule()