Dialog API

Opening a link in a dialog window

In the most simple use-case, any page served by Backdrop can be opened in a dialog just by adding an HTML attribute to the link that should open the dialog. First, make sure that the ajax.js file is loaded on the page:

backdrop_add_library('system', 'backdrop.ajax');

The line above could the added in many ways; for example by implementing template_preprocess_page() or template_preprocess_layout() in your theme's template.php file.

/**
 * Implements hook_preprocess_page().
 */
function mytheme_preprocess_page(&$variables) {
  // Load the AJAX library
  backdrop_add_library('system', 'backdrop.ajax');
}

Then in the HTML, include two things, the class use-ajax on the link, and a data attribute data-dialog="true" telling Backdrop that the response should load in a dialog:

<a href="/node/1" class="use-ajax" data-dialog="true" />

Clicking this link will now load the content of the URL /node/1 into the dialog without the surrounding header, footer, or sidebars. You can also specify any jQuery UI dialog options in a second data-dialog-options attribute:

<a href="/node/1" class="use-ajax" data-dialog="true" data-dialog-options='{"classes":{"ui-dialog" : "my-dialog"},"width" : 600}' />

The full list of options can be found at the jQuery UI Dialog documentation.

Manipulating a dialog from the server

Server-side requests can open dialogs, or manipulate open dialogs to set their title, change their options, and close them. To do this, a form may specify a #ajax property, or a link may use the use-ajax class to a callback path. This callback path can then return a set of commands back to dialog via AJAX.

For example a form submit button for a form displayed within the dialog could save the form and then close the dialog. The button includes the property #ajax that specifies a callback function. That callback function is invoked after the normal submit handler for the form. The callback typically returns an array that contains the key/value '#type' => 'ajax'  and the key '#commands' with a subarray of ajax commands. These commands are sent back to the browser's dialog API javascript, which executes them. 

function my_module_form($form, &$form_state) {
 $form['option'] = array(
   '#type' => 'textfield',
   '#title' => t('Option to save'),
 );
 $form['actions']['#type'] = 'actions';
 $form['actions']['submit'] = array(
   '#type' => 'submit',
   '#value' => t('Close and save'),
   '#ajax' => array(
     'callback' => 'my_module_dialog_close',
   ),
 );
}

/**
 * Submit handler.
 */
function my_module_form_submit($form, &$form_state) {
  // Save the $form_state['values']['option'] value here.
}

/**
 * AJAX callback for the form. Invoked after the submit handler.
 *
 * This callback should return an array of ajax commands. These commands are
 * sent to the browser, and are executed in the browser by the dialog API Javascript framework.
 *
 */
function my_module_dialog_close($form, &$form_state) {
  $commands = array(
    '#type' => 'ajax',
    '#commands' => array(),
  );
  $commands['#commands'][] = ajax_command_close_modal_dialog();
  return $commands;
}