Retrieves, populates, and processes a form.

This function allows you to supply values for form elements and submit a form for processing. Compare to drupal_get_form(), which also builds and processes a form, but does not allow you to supply values.

There is no return value, but you can check to see if there are errors by calling form_get_errors().

// register a new user
$form_state = array();
$form_state['values']['name'] = 'robo-user';
$form_state['values']['mail'] = 'robouser@example.com';
$form_state['values']['pass']['pass1'] = 'password';
$form_state['values']['pass']['pass2'] = 'password';
$form_state['values']['op'] = t('Create new account');
drupal_execute('user_register', $form_state);

// Create a new node
$form_state = array();
module_load_include('inc', 'node', 'node.pages');
$node = array('type' => 'story');
$form_state['values']['title'] = 'My node';
$form_state['values']['body'] = 'This is the body text!';
$form_state['values']['name'] = 'robo-user';
$form_state['values']['op'] = t('Save');
drupal_execute('story_node_form', $form_state, (object)$node);

Parameters

$form_id: The unique string identifying the desired form. If a function with that name exists, it is called to build the form array. Modules that need to generate the same form (or very similar forms) using different $form_ids can implement hook_forms(), which maps different $form_id values to the proper form constructor function. Examples may be found in node_forms(), search_forms(), and user_forms().

$form_state: A keyed array containing the current state of the form. Most important is the $form_state['values'] collection, a tree of data used to simulate the incoming $_POST information from a user's form submission.

...: Any additional arguments are passed on to the functions called by drupal_execute(), including the unique form constructor function. For example, the node_edit form requires that a node object be passed in here when it is called. For example:

Related topics

File

drupal-6.x/includes/form.inc, line 300

Code

function drupal_execute($form_id, &$form_state) {
  $args = func_get_args();

  // Make sure $form_state is passed around by reference.
  $args[1] = &$form_state;

  $form = call_user_func_array('drupal_retrieve_form', $args);
  $form['#post'] = $form_state['values'];

  // Reset form validation.
  $form_state['must_validate'] = TRUE;
  form_set_error(NULL, '', TRUE);

  drupal_prepare_form($form_id, $form, $form_state);
  drupal_process_form($form_id, $form, $form_state);
}