function drupal_execute

Retrieves a form using a form_id, populates it with $form_values, processes it, and returns any validation errors encountered. This function is the programmatic counterpart to drupal_get_form().

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 building function. Examples may be found in node_forms(), search_forms(), and user_forms().

$form_values: An array of values mirroring the values returned by a given form when it is submitted by a user.

...: Any additional arguments needed by the form building function.

Return value

Any form validation errors encountered.

For example:

// register a new user $values['name'] = 'robo-user'; $values['mail'] = 'robouser@example.com'; $values['pass'] = 'password'; drupal_execute('user_register', $values);

// Create a new node $node = array('type' => 'story'); $values['title'] = 'My node'; $values['body'] = 'This is the body text!'; $values['name'] = 'robo-user'; drupal_execute('story_node_form', $values, $node);

Related topics

File

includes/form.inc, line 152

Code

function drupal_execute($form_id, $form_values) {
  $args = func_get_args();
  $form_id = array_shift($args);
  $form_values = array_shift($args);
  array_unshift($args, $form_id);
  if (isset($form_values)) {
    $form = call_user_func_array('drupal_retrieve_form', $args);
    $form['#post'] = $form_values;
    return drupal_process_form($form_id, $form);
  }
}