What is the difference between drupal_get_form and drupal_retrieve_form?

Question

What is the difference between drupal_get_form() and drupal_retrieve_form()? Can someone explain the difference? I look at the API, but the description seems similar to me.

Answer 1

The difference is that drupal_get_form() handles retrieving, processing, and displaying a rendered HTML form for modules automatically, while drupal_retrieve_form() returns the structured array that defines a form.

Retrieving the form

drupal_get_form() first checks if the form is present in the form cache with form_get_cache(); if it isn't present, it calls drupal_retrieve_form(), and drupal_prepare_form().

Processing the form

drupal_get_form() calls drupal_process_form(), which is the function that calls drupal_validate_form(), and that invokes the submission handlers with form_execute_handlers().

Rendering the form

The rendering is done from drupal_process_form(), which calls form_builder().

In most of the cases, drupal_get_form() is the function to use, such as in the following code.

function node_menu() {
  $items['admin/content'] = array(
    'title' => 'Content', 
    'description' => 'Find and manage content.', 
    'page callback' => 'drupal_get_form', 
    'page arguments' => array('node_admin_content'), 
    'access arguments' => array('access content overview'), 
    'weight' => -10, 
    'file' => 'node.admin.inc',
  );

  // …

  return $items;
}

The only module I found that is calling drupal_retrieve_form() directly is the Mollom module in mollom_moderate(), which uses it for automatically submitting a form. The code could use drupal_form_submit(), but (as a comment says), "Programmatic form submissions are not able to automatically use the primary form submit button/action, so we need to resemble drupal_form_submit()."

  $form_id = $form_info['delete form'];
  $form_state = form_state_defaults();
  // We assume that all delete confirmation forms take the fully loaded
  // entity as (only) argument.
  $messages[] = "Attempt to load $form_info[entity] entity via entity_load().";
  $entities = entity_load($data->entity, array($data->id));
  $form_state['build_info']['args'][] = $entities[$data->id];
  $form = drupal_retrieve_form($form_id, $form_state);

  $form_state['values'] = array();
  $form_state['values']['mollom']['feedback'] = '';
  // Take over the primary submit button of confirm_form().
  $form_state['values']['op'] = $form['actions']['submit']['#value'];

  $form_state['input'] = $form_state['values'];
  $form_state['programmed'] = TRUE;
  // Programmed forms are always submitted.
  $form_state['submitted'] = TRUE;

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

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

  $result = $form_state['executed'];