ajax_deliver

Versions

mediamosa-21

ajax_deliver($page_callback_result)

Package and send the result of a page callback to the browser as an AJAX response.

Parameters

$page_callback_result The result of a page callback. Can be one of:

• NULL: to indicate no content.
• An integer menu status constant: to indicate an error condition.
• A string of HTML content.
• A renderable array of content.

Related topics

AJAX framework

Drupal's AJAX framework is used to dynamically update parts of a page's HTML based on data from the server. Upon a specified event, such as a button click, a callback function is triggered which performs server-side logic and may return...

Code

includes/ajax.inc, line 332

<?php
function ajax_deliver($page_callback_result) {
  $commands = array();
  $header = TRUE;

  // Normalize whatever was returned by the page callback to an AJAX commands
  // array.
  if (!isset($page_callback_result)) {
    // Simply delivering an empty commands array is sufficient. This results
    // in the AJAX request being completed, but nothing being done to the page.
  }
  elseif (is_int($page_callback_result)) {
    switch ($page_callback_result) {
      case MENU_NOT_FOUND:
        $commands[] = ajax_command_alert(t('The requested page could not be found.'));
        break;

      case MENU_ACCESS_DENIED:
        $commands[] = ajax_command_alert(t('You are not authorized to access this page.'));
        break;

      case MENU_SITE_OFFLINE:
        $commands[] = ajax_command_alert(filter_xss_admin(variable_get('maintenance_mode_message',
          t('@site is currently under maintenance. We should be back shortly. Thank you for your patience.', array('@site' => variable_get('site_name', 'Drupal'))))));
        break;
    }
  }
  elseif (is_array($page_callback_result) && isset($page_callback_result['#type']) && ($page_callback_result['#type'] == 'ajax')) {
    // Complex AJAX callbacks can return a result that contains an error message
    // or a specific set of commands to send to the browser.
    $page_callback_result += element_info('ajax');
    $header = $page_callback_result['#header'];
    $error = $page_callback_result['#error'];
    if (isset($error) && $error !== FALSE) {
      if ((empty($error) || $error === TRUE)) {
        $error = t('An error occurred while handling the request: The server received invalid input.');
      }
      $commands[] = ajax_command_alert($error);
    }
    else {
      $commands = $page_callback_result['#commands'];
    }
  }
  else {
    // Like normal page callbacks, simple AJAX callbacks can return html
    // content, as a string or renderable array, to replace what was previously
    // there in the wrapper. In this case, in addition to the content, we want
    // to add the status messages, but inside the new wrapper, so that they get
    // replaced on subsequent AJAX calls for the same wrapper.
    $html = is_string($page_callback_result) ? $page_callback_result : drupal_render($page_callback_result);
    $commands[] = ajax_command_replace(NULL, $html);
    $commands[] = ajax_command_prepend(NULL, theme('status_messages'));
  }

  // This function needs to do the same thing that drupal_deliver_html_page()
  // does: add any needed http headers, print rendered output, and perform
  // end-of-request tasks. By default, $header=TRUE, and we add a
  // 'text/javascript' header. The page callback can override $header by
  // returning an 'ajax' element with a #header property. This can be set to
  // FALSE to prevent the 'text/javascript' header from being output, necessary
  // when outputting to an IFRAME. This can also be set to 'multipart', in which
  // case, we don't output JSON, but JSON content wrapped in a textarea, making
  // a 'text/javascript' header incorrect.
  if ($header && $header !== 'multipart') {
    drupal_add_http_header('Content-Type', 'text/javascript; charset=utf-8');
  }
  $output = ajax_render($commands);
  if ($header === 'multipart') {
    // jQuery file uploads: http://malsup.com/jquery/form/#code-samples
    $output = '<textarea>' . $output . '</textarea>';
  }
  print $output;
  ajax_footer();
}
?>