form_set_error
- Versions
- mediamosa-21
form_set_error($name = NULL, $message = '', $limit_validation_errors = NULL)
Files an error against a form element.
Parameters
$name The name of the form element. If the #parents property of your form element is array('foo', 'bar', 'baz') then you may set an error on 'foo' or 'foo][bar][baz'. Setting an error on 'foo' sets an error for every element where the #parents array starts with 'foo'.
$message The error message to present to the user.
$limit_validation_errors Internal use only. The #limit_validation_errors property of the clicked button if it exists. Multistep forms not wanting to validate the whole form can set the #limit_validation_errors property on buttons to avoid validation errors of some elements preventing the button's submit handlers from running. For example, pressing the "Previous" button should not fire validation errors just because the current step has invalid values. AJAX is another typical example. If this property is set on the clicked button, the button must also define its #submit property and those handlers will be executed even if there is invalid input, so extreme care should be taken with respect to what is performed by them. This is typically not a problem with buttons like "Previous" or "Add more" that do not invoke persistent storage of the submitted form values. Do not use the #limit_validation_errors property on buttons that trigger saving of form values to the database. The #limit_validation_errors property is a list of "sections" within $form_state['values'] that must contain valid values. Each "section" is an array with the ordered set of keys needed to reach that part of $form_state['values'] (i.e., the #parents property of the element). For example:
<?php
$form['actions']['previous']['#limit_validation_errors'] = array(
array('step1'),
array('foo', 'bar'),
);
?>This will require $form_state['values']['step1'] and everything within it (for example, $form_state['values']['step1']['choice']) to be valid, so calls to form_set_error('step1', $message) or form_set_error('step1][choice', $message) will prevent the submit handlers from running, and result in the error message being displayed to the user. However, calls to form_set_error('step2', $message) and form_set_error('step2][groupX][choiceY', $message) will be suppressed, resulting in the message not being displayed to the user, and the submit handlers will run despite $form_state['values']['step2'] and $form_state['values']['step2']['groupX']['choiceY'] containing invalid values. Errors for an invalid $form_state['values']['foo'] will be suppressed, but errors for invalid values for $form_state['values']['foo']['bar'] and everything within it will be recorded. If the button doesn't need any user input to be valid, then the #limit_validation_errors can be set to an empty array, in which case, all calls to form_set_error() will be suppressed. Partial form validation is implemented by suppressing errors rather than by skipping the input processing and validation steps entirely, because some forms have button-level submit handlers that call Drupal API functions that assume that certain data exists within $form_state['values'], and while not doing anything with that data that requires it to be valid, PHP errors would be triggered if the input processing and validation steps were fully skipped. @see http://drupal.org/node/370537.
Return value
Return value is for internal use only. To get a list of errors, use form_get_errors() or form_get_error().
Related topics
Code
includes/form.inc, line 1096
<?php
function form_set_error($name = NULL, $message = '', $limit_validation_errors = NULL) {
$form = &drupal_static(__FUNCTION__, array());
$sections = &drupal_static(__FUNCTION__ . ':limit_validation_errors');
if (isset($limit_validation_errors)) {
$sections = $limit_validation_errors;
}
if (isset($name) && !isset($form[$name])) {
$record = TRUE;
if (isset($sections)) {
// #limit_validation_errors is an array of "sections" within which user
// input must be valid. If the element is within one of these sections,
// the error must be recorded. Otherwise, it can be suppressed.
// #limit_validation_errors can be an empty array, in which case all
// errors are suppressed. For example, a "Previous" button might want its
// submit action to be triggered even if none of the submitted values are
// valid.
$record = FALSE;
foreach ($sections as $section) {
// Exploding by '][' reconstructs the element's #parents. If the
// reconstructed #parents begin with the same keys as the specified
// section, then the element's values are within the part of
// $form_state['values'] that the clicked button requires to be valid,
// so errors for this element must be recorded.
if (array_slice(explode('][', $name), 0, count($section)) === $section) {
$record = TRUE;
break;
}
}
}
if ($record) {
$form[$name] = $message;
if ($message) {
drupal_set_message($message, 'error');
}
}
}
return $form;
}
?>MediaMosa API
Search Mediamosa 2.1
Developer links
  |
This work is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported License |  |