overlay.module 31.4 KB
Newer Older
1 2 3 4 5 6 7
<?php

/**
 * @file
 * Displays the Drupal administration interface in an overlay.
 */

8
use Symfony\Component\HttpFoundation\RedirectResponse;
9
use Symfony\Component\HttpFoundation\Response;
10
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
11
use Drupal\block\Plugin\Core\Entity\Block;
12
use Drupal\Core\Session\AccountInterface;
13

14 15 16 17 18 19 20 21
/**
 * Implements hook_help().
 */
function overlay_help($path, $arg) {
  switch ($path) {
    case 'admin/help#overlay':
      $output = '';
      $output .= '<h3>' . t('About') . '</h3>';
22
      $output .= '<p>' . t('The Overlay module makes the administration pages on your site display in a JavaScript overlay of the page you were viewing when you clicked the administrative link, instead of replacing the page in your browser window. Use the close link on the overlay to return to the page you were viewing when you clicked the link. For more information, see the online handbook entry for <a href="@overlay">Overlay module</a>.', array('@overlay' => 'http://drupal.org/documentation/modules/overlay')) . '</p>';
23 24 25 26
      return $output;
  }
}

27
/**
28
 * Implements hook_menu()
29 30 31 32 33 34 35 36 37
 */
function overlay_menu() {
  $items['overlay-ajax/%'] = array(
    'title' => '',
    'page callback' => 'overlay_ajax_render_region',
    'page arguments' => array(1),
    'access arguments' => array('access overlay'),
    'type' => MENU_CALLBACK,
  );
38 39 40
  $items['overlay/dismiss-message'] = array(
    'title' => '',
    'page callback' => 'overlay_user_dismiss_message',
41
    'access callback' => 'overlay_user_dismiss_message_access',
42 43
    'type' => MENU_CALLBACK,
  );
44 45 46
  return $items;
}

47 48 49 50 51 52 53 54 55 56 57 58 59
/**
 * Implements hook_admin_paths().
 */
function overlay_admin_paths() {
  $paths = array(
    // This is marked as an administrative path so that if it is visited from
    // within the overlay, the user will stay within the overlay while the
    // callback is being processed.
    'overlay/dismiss-message' => TRUE,
  );
  return $paths;
}

60 61 62 63 64 65 66 67 68 69 70 71
/**
 * Implements hook_permission().
 */
function overlay_permission() {
  return array(
    'access overlay' => array(
      'title' => t('Access the administrative overlay'),
      'description' => t('View administrative pages in the overlay.'),
    ),
  );
}

72 73 74 75 76 77 78 79 80
/**
 * Implements hook_theme().
 */
function overlay_theme() {
  return array(
    'overlay' => array(
      'render element' => 'page',
      'template' => 'overlay',
    ),
81 82
    'overlay_disable_message' => array(
      'render element' => 'element',
83
      'template' => 'overlay-disable-message',
84
    ),
85 86 87
  );
}

88 89 90 91 92 93 94 95 96 97 98 99
/**
 * Implements hook_field_extra_fields().
 */
function overlay_field_extra_fields() {
  $fields['user']['user']['form']['overlay_control'] = array(
    'label' => t('Administrative overlay'),
    'description' => t('Overlay module form element.'),
    'weight' => 4,
  );
  return $fields;
}

100 101 102
/**
 * Implements hook_form_FORM_ID_alter().
 */
103
function overlay_form_user_form_alter(&$form, &$form_state) {
104
  $account = $form_state['controller']->getEntity();
105
  if (user_access('access overlay', $account)) {
106
    $account_data = Drupal::service('user.data')->get('overlay', $account->id(), 'enabled');
107
    $form['overlay_control'] = array(
108
      '#type' => 'details',
109 110 111 112 113 114 115
      '#title' => t('Administrative overlay'),
      '#weight' => 4,
    );
    $form['overlay_control']['overlay'] = array(
      '#type' => 'checkbox',
      '#title' => t('Use the overlay for administrative pages.'),
      '#description' => t('Show administrative pages on top of the page you started from.'),
116
      '#default_value' => isset($account_data) ? $account_data : 1,
117
    );
118 119 120 121
  }
}

/**
122
 * Implements hook_user_update().
123
 */
124
function overlay_user_update($account) {
125
  if (isset($account->overlay)) {
126
    Drupal::service('user.data')->set('overlay', $account->id(), 'enabled', (int) $account->overlay);
127 128 129
  }
}

130
/**
131
 * Implements hook_library_info().
132
 */
133
function overlay_library_info() {
134 135 136
  $module_path = drupal_get_path('module', 'overlay');

  // Overlay parent.
137
  $libraries['drupal.overlay.parent'] = array(
138
    'title' => 'Overlay: Parent',
139
    'website' => 'http://drupal.org/documentation/modules/overlay',
140 141 142 143 144
    'version' => '1.0',
    'js' => array(
      $module_path . '/overlay-parent.js' => array(),
    ),
    'css' => array(
145
      $module_path . '/css/overlay-parent.css' => array(),
146 147
    ),
    'dependencies' => array(
148 149
      array('system', 'jquery'),
      array('system', 'drupal'),
150
      array('system', 'drupalSettings'),
151
      array('system', 'drupal.displace'),
152
      array('system', 'drupal.tabbingmanager'),
153
      array('system', 'drupal.announce'),
154
      array('system', 'jquery.ui.core'),
155
      array('system', 'jquery.bbq'),
156 157 158
    ),
  );
  // Overlay child.
159
  $libraries['drupal.overlay.child'] = array(
160
    'title' => 'Overlay: Child',
161
    'website' => 'http://drupal.org/documentation/modules/overlay',
162 163 164 165
    'version' => '1.0',
    'js' => array(
      $module_path . '/overlay-child.js' => array(),
    ),
166
    'css' => array(
167
      $module_path . '/css/overlay-child.css' => array(),
168
    ),
169 170 171
    'dependencies' => array(
      array('system', 'jquery'),
      array('system', 'drupal'),
172
      array('system', 'drupalSettings'),
173 174
      array('system', 'jquery.once'),
    ),
175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210
  );

  return $libraries;
}

/**
 * Implements hook_batch_alter().
 *
 * If the current page request is inside the overlay, add ?render=overlay to
 * the success callback URL, so that it appears correctly within the overlay.
 *
 * @see overlay_get_mode()
 */
function overlay_batch_alter(&$batch) {
  if (overlay_get_mode() == 'child') {
    if (isset($batch['url_options']['query'])) {
      $batch['url_options']['query']['render'] = 'overlay';
    }
    else {
      $batch['url_options']['query'] = array('render' => 'overlay');
    }
  }
}

/**
 * Implements hook_page_alter().
 */
function overlay_page_alter(&$page) {
  // If we are limiting rendering to a subset of page regions, deny access to
  // all other regions so that they will not be processed.
  if ($regions_to_render = overlay_get_regions_to_render()) {
    $skipped_regions = array_diff(element_children($page), $regions_to_render);
    foreach ($skipped_regions as $skipped_region) {
      $page[$skipped_region]['#access'] = FALSE;
    }
  }
211

212 213
  $mode = overlay_get_mode();
  if ($mode == 'child') {
214 215 216
    // Add the overlay wrapper before the html wrapper.
    array_unshift($page['#theme_wrappers'], 'overlay');
  }
217 218 219 220 221
  elseif ($mode == 'parent' && ($message = overlay_disable_message())) {
    $page['page_top']['disable_overlay'] = $message;
  }
}

222
/**
223 224 225 226 227
 * Access callback: Determines access to dismiss the accessibility message.
 *
 * @return
 *   TRUE if the user has permission to dismiss the accessibility message or if
 *   the user is anonymous. FALSE if otherwise.
228 229 230 231 232 233 234 235 236
 *
 * @see overlay_user_dismiss_message()
 * @see overlay_menu()
 */
function overlay_user_dismiss_message_access() {
  global $user;
  if (!user_access('access overlay')) {
    return FALSE;
  }
237 238
  // It's unlikely, but possible that "access overlay" permission is granted to
  // the anonymous role. In this case, we do not display the message to disable
239 240 241
  // the overlay, so there is nothing to dismiss.
  if (empty($user->uid)) {
    return FALSE;
242
  }
243
  return TRUE;
244 245
}

246
/**
247 248 249 250
 * Page callback: Dismisses the overlay accessibility message for this user.
 *
 * @return
 *   A render array for a page containing a list of content.
251 252 253 254 255 256
 *
 * @see overlay_user_dismiss_message_access()
 * @see overlay_menu()
 */
function overlay_user_dismiss_message() {
  global $user;
257 258 259 260

  // @todo CSRF tokens are validated in page callbacks rather than access
  //   callbacks, because access callbacks are also invoked during menu link
  //   generation. Add token support to routing: http://drupal.org/node/755584.
261
  $token = Drupal::request()->query->get('token');
262
  if (!isset($token) || !drupal_valid_token($token, 'overlay')) {
263
    throw new AccessDeniedHttpException();
264 265
  }

266
  Drupal::service('user.data')->set('overlay', $user->uid, 'message_dismissed', 1);
267 268
  drupal_set_message(t('The message has been dismissed. You can change your overlay settings at any time by visiting your profile page.'));
  // Destination is normally given. Go to the user profile as a fallback.
269
  return new RedirectResponse(url('user/' . $user->uid . '/edit', array('absolute' => TRUE)));
270 271 272 273 274 275 276 277
}

/**
 * Returns a renderable array representing a message for disabling the overlay.
 *
 * If the current user can access the overlay and has not previously indicated
 * that this message should be dismissed, this function returns a message
 * containing a link to disable the overlay. Nothing is returned for anonymous
278 279 280 281 282 283
 * users, because the links control per-user settings. Because some screen
 * readers are unable to properly read overlay contents, site builders are
 * discouraged from granting the "access overlay" permission to the anonymous
 * role.
 *
 * @see http://drupal.org/node/890284
284 285 286 287
 */
function overlay_disable_message() {
  global $user;

288 289 290 291 292
  $build = array();
  if (empty($user->uid) || !user_access('access overlay')) {
    return $build;
  }

293
  $user_data = Drupal::service('user.data')->get('overlay', $user->uid);
294
  if (empty($user_data['message_dismissed']) && (!isset($user_data['enabled']) || $user_data['enabled'])) {
295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338
    $build = array(
      '#theme' => 'overlay_disable_message',
      '#weight' => -99,
      // Link to the user's profile page, where the overlay can be disabled.
      'profile_link' => array(
        '#type' => 'link',
        '#title' => t('If you have problems accessing administrative pages on this site, disable the overlay on your profile page.'),
        '#href' => 'user/' . $user->uid . '/edit',
        '#options' => array(
          'query' => drupal_get_destination(),
          'fragment' => 'edit-overlay-control',
          'attributes' => array(
            'id' => 'overlay-profile-link',
            // Prevent the target page from being opened in the overlay.
            'class' => array('overlay-exclude'),
          ),
        ),
      ),
      // Link to a menu callback that allows this message to be permanently
      // dismissed for the current user.
      'dismiss_message_link' => array(
        '#type' => 'link',
        '#title' => t('Dismiss this message.'),
        '#href' => 'overlay/dismiss-message',
        '#options' => array(
          'query' => drupal_get_destination() + array(
            // Add a token to protect against cross-site request forgeries.
            'token' => drupal_get_token('overlay'),
          ),
          'attributes' => array(
            'id' => 'overlay-dismiss-message',
            // If this message is being displayed outside the overlay, prevent
            // this link from opening the overlay.
            'class' => (overlay_get_mode() == 'parent') ? array('overlay-exclude') : array(),
          ),
        ),
      )
    );
  }

  return $build;
}

/**
339
 * Prepares variables for overlay disable message templates.
340
 *
341 342 343
 * Default template: overlay-disable-message.html.twig.
 *
 * @param array $variables
344 345 346 347
 *   An associative array with an 'element' element, which itself is an
 *   associative array containing:
 *   - profile_link: The link to this user's account.
 *   - dismiss_message_link: The link to dismiss the overlay.
348
 */
349
function template_preprocess_overlay_disable_message(&$variables) {
350 351 352 353 354 355 356
  $element = $variables['element'];

  // Add CSS classes to hide the links from most sighted users, while keeping
  // them accessible to screen-reader users and keyboard-only users. To assist
  // screen-reader users, this message appears in both the parent and child
  // documents, but only the one in the child document is part of the tab order.
  foreach (array('profile_link', 'dismiss_message_link') as $key) {
357
    $element[$key]['#options']['attributes']['class'][] = 'visually-hidden';
358
    if (overlay_get_mode() == 'child') {
359
      $element[$key]['#options']['attributes']['class'][] = 'focusable';
360 361 362
    }
  }

363 364
  $variables['profile_link'] = $element['profile_link'];
  $variables['dismiss_link'] = $element['dismiss_message_link'];
365 366 367
}

/**
368
 * Implements hook_block_access().
369
 */
370
function overlay_block_access(Block $block, $operation, AccountInterface $account, $langcode) {
371 372 373 374 375 376 377
  // If we are limiting rendering to a subset of page regions, hide all blocks
  // which appear in regions not on that list. Note that overlay_page_alter()
  // does a more comprehensive job of preventing unwanted regions from being
  // displayed (regardless of whether they contain blocks or not), but the
  // reason for duplicating effort here is performance; we do not even want
  // these blocks to be built if they are not going to be displayed.
  if ($regions_to_render = overlay_get_regions_to_render()) {
378
    if (!in_array($block->get('region'), $regions_to_render)) {
379
      return FALSE;
380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396
    }
  }
}

/**
 * Implements hook_system_info_alter().
 *
 * Add default regions for the overlay.
 */
function overlay_system_info_alter(&$info, $file, $type) {
  if ($type == 'theme') {
    $info['overlay_regions'][] = 'content';
    $info['overlay_regions'][] = 'help';
  }
}

/**
397
 * Implements hook_preprocess_HOOK() for html.tpl.php.
398 399 400 401 402 403 404 405 406
 *
 * If the current page request is inside the overlay, add appropriate classes
 * to the <body> element, and simplify the page title.
 *
 * @see overlay_get_mode()
 */
function overlay_preprocess_html(&$variables) {
  if (overlay_get_mode() == 'child') {
    // Add overlay class, so themes can react to being displayed in the overlay.
407
    $variables['attributes']['class'][] = 'overlay';
408 409 410
  }
}

411
/**
412
 * Implements hook_preprocess_HOOK() for maintenance-page.html.twig.
413 414 415 416 417 418 419 420
 *
 * If the current page request is inside the overlay, add appropriate classes
 * to the <body> element, and simplify the page title.
 */
function overlay_preprocess_maintenance_page(&$variables) {
  overlay_preprocess_html($variables);
}

421
/**
422 423 424 425
 * Implements template_preprocess_HOOK() for overlay.tpl.php
 *
 * If the current page request is inside the overlay, add appropriate classes
 * to the <body> element, and simplify the page title.
426 427 428 429
 *
 * @see overlay.tpl.php
 */
function template_preprocess_overlay(&$variables) {
430 431 432
  $variables['tabs'] = menu_primary_local_tasks();
  $variables['title'] = drupal_get_title();
  $variables['disable_overlay'] = overlay_disable_message();
433

434 435
  // Add attributes for the overlay container.
  $variables['attributes']['id'] = 'overlay';
436
  $variables['attributes']['class'][] = 'overlay';
437 438
  // Add attributes for the overlay title.
  $variables['title_attributes']['id'] = 'overlay-title';
439
  // Add attributes for the overlay content.
440
  $variables['content_attributes']['id'] = 'overlay-content';
441
  $variables['content_attributes']['class'][] = 'clearfix';
442 443 444
}

/**
445
 * Implements hook_preprocess_HOOK() for page.tpl.php.
446
 *
447
 * If the current page request is inside the overlay, hide the tabs.
448 449 450 451 452
 *
 * @see overlay_get_mode()
 */
function overlay_preprocess_page(&$variables) {
  if (overlay_get_mode() == 'child') {
453
    unset($variables['tabs']['#primary']);
454
  }
Dries's avatar
Dries committed
455 456
}

457
/**
458
 * Prints an empty page.
459 460 461
 *
 * This function is used to print out a bare minimum empty page which still has
 * the scripts and styles necessary in order to trigger the overlay to close.
462 463 464 465 466 467 468
 *
 * It can be used to prevent a page request which closes the overlay (for
 * example, a form submission) from being fully re-rendered before the overlay
 * is closed, thereby allowing the dialog to be closed faster and with less
 * interruption, and also allowing the display of messages to be deferred to
 * the parent window (rather than displaying them in the child window, which
 * will close before the user has had a chance to read them).
469 470 471
 *
 * @return \Symfony\Component\HttpFoundation\Response
 *   A Response object.
472 473 474
 */
function overlay_deliver_empty_page() {
  $empty_page = '<html><head><title></title>' . drupal_get_css() . drupal_get_js() . '</head><body class="overlay"></body></html>';
475
  return new Response($empty_page);
476 477
}

478
/**
479
 * Gets the current overlay mode.
480 481 482 483 484 485 486 487
 *
 * @see overlay_set_mode()
 */
function overlay_get_mode() {
  return overlay_set_mode(NULL);
}

/**
488
 * Sets the overlay mode and adds proper JavaScript and styles to the page.
489
 *
490 491 492 493
 * Note that since setting the overlay mode triggers a variety of behaviors
 * (including hooks being invoked), it can only be done once per page request.
 * Therefore, the first call to this function which passes along a value of the
 * $mode parameter controls the overlay mode that will be used.
494
 *
495 496 497 498 499 500 501 502 503 504 505
 * @param $mode
 *   To set the mode, pass in one of the following values:
 *   - 'parent': This is used in the context of a parent window (a regular
 *     browser window). If set, JavaScript is added so that administrative
 *     links in the parent window will open in an overlay.
 *   - 'child': This is used in the context of the child overlay window (the
 *     page actually appearing within the overlay iframe). If set, JavaScript
 *     and CSS are added so that Drupal behaves nicely from within the overlay.
 *   - 'none': This is used to avoid adding any overlay-related code to the
 *     page at all. Modules can set this to explicitly prevent the overlay from
 *     being used. For example, since the overlay module itself sets the mode
506 507 508 509
 *     to 'parent' or 'child' in the overlay event subscriber when certain
 *     conditions are met, other modules which want to override that behavior
 *     can do so by setting the mode to 'none' earlier in the page request -
 *     e.g., in their own event subscribers, if they have a higher priority.
510 511 512 513 514 515 516
 *   This parameter is optional, and if omitted, the current mode will be
 *   returned with no action taken.
 *
 * @return
 *   The current mode, if any has been set, or NULL if no mode has been set.
 *
 * @ingroup overlay_api
517
 * @see \Drupal\overlay\EventSubscriber\OverlaySubscriber::onRequest()
518 519 520 521 522 523 524 525 526 527 528 529 530 531
 */
function overlay_set_mode($mode = NULL) {
  global $base_path;
  $overlay_mode = &drupal_static(__FUNCTION__);

  // Make sure external resources are not included more than once. Also return
  // the current mode, if no mode was specified.
  if (isset($overlay_mode) || !isset($mode)) {
    return $overlay_mode;
  }
  $overlay_mode = $mode;

  switch ($overlay_mode) {
    case 'parent':
532
      drupal_add_library('overlay', 'drupal.overlay.parent');
533 534 535 536 537 538

      // Allow modules to act upon overlay events.
      module_invoke_all('overlay_parent_initialize');
      break;

    case 'child':
539
      drupal_add_library('overlay', 'drupal.overlay.child');
540 541 542 543 544 545 546 547 548 549 550 551 552 553 554

      // Allow modules to act upon overlay events.
      module_invoke_all('overlay_child_initialize');
      break;
  }
  return $overlay_mode;
}

/**
 * Implements hook_overlay_parent_initialize().
 */
function overlay_overlay_parent_initialize() {
  // Let the client side know which paths are administrative.
  $paths = path_get_admin_paths();
  foreach ($paths as &$type) {
555
    $type = str_replace('<front>', config('system.site')->get('page.front'), $type);
556 557
  }
  drupal_add_js(array('overlay' => array('paths' => $paths)), 'setting');
558
  $path_prefixes = array();
559 560
  if (module_exists('language')) {
    language_negotiation_include();
561
    if (config('language.negotiation')->get('url.source') == LANGUAGE_NEGOTIATION_URL_PREFIX) {
562 563 564 565 566
      // Skip the empty string indicating the default language. We always accept
      // paths without a prefix.
      $path_prefixes = language_negotiation_url_prefixes();
      $path_prefixes = array_values(array_filter($path_prefixes));
    }
567 568
  }
  drupal_add_js(array('overlay' => array('pathPrefixes' => $path_prefixes)), 'setting');
569
  // Pass along the Ajax callback for rerendering sections of the parent window.
570 571 572 573 574 575 576 577 578
  drupal_add_js(array('overlay' => array('ajaxCallback' => 'overlay-ajax')), 'setting');
}

/**
 * Implements hook_overlay_child_initialize().
 */
function overlay_overlay_child_initialize() {
  // Check if the parent window needs to refresh any page regions on this page
  // request.
579
  overlay_trigger_refresh();
580 581 582 583
  // If this is a POST request, or a GET request with a token parameter, we
  // have an indication that something in the supplemental regions of the
  // overlay might change during the current page request. We therefore store
  // the initial rendered content of those regions here, so that we can compare
584 585 586 587
  // it to the same content rendered in OverlaySubscriber::onResponse(),
  // at the end of the page request. This allows us to check if anything
  // actually did change, and, if so, trigger an immediate Ajax refresh
  // of the parent window.
588
  $token = Drupal::request()->query->get('token');
589 590
  $post = Drupal::request()->request->count();
  if (!empty($post) || isset($token)) {
591 592 593
    foreach (overlay_supplemental_regions() as $region) {
      overlay_store_rendered_content($region, overlay_render_region($region));
    }
594 595 596
    // In addition, notify the parent window that when the overlay closes,
    // the entire parent window should be refreshed.
    overlay_request_page_refresh();
597 598 599 600 601 602 603 604
  }
  // Indicate that when the main page rendering occurs later in the page
  // request, only the regions that appear within the overlay should be
  // rendered.
  overlay_set_regions_to_render(overlay_regions());
}

/**
605
 * Immediately returns HTML to to the browser and closes the overlay.
606 607
 *
 * @param $redirect
608 609 610
 *   (optional) The path that should open in the parent window after the
 *   overlay closes. If not set, no redirect will be performed on the parent
 *   window.
611
 *
612 613 614
 * @param $redirect_options
 *   (optional) An associative array of options to use when generating the
 *   redirect URL.
615
 *
616 617 618
 * @return \Symfony\Component\HttpFoundation\Response
 *   A Response object.
 *
619 620
 * @todo This function should only request that the overlay close when the page
 *   is displayed (as it did in Drupal 7), not immediately end the request.
621
 */
622
function overlay_close_dialog($redirect = NULL, $redirect_options = array()) {
623 624 625 626 627
  $settings = array(
    'overlayChild' => array(
      'closeOverlay' => TRUE,
    ),
  );
628 629 630 631 632 633

  // Tell the child window to perform the redirection when requested to.
  if (isset($redirect)) {
    $settings['overlayChild']['redirect'] = url($redirect, $redirect_options);
  }

634
  drupal_add_js($settings, array('type' => 'setting'));
635 636 637

  // Since we are closing the overlay as soon as the page is displayed, we do
  // not want to show any of the page's actual content.
638
  return overlay_deliver_empty_page();
639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680
}

/**
 * Returns a list of page regions that appear in the overlay.
 *
 * Overlay regions correspond to the entire contents of the overlay child
 * window and are refreshed each time a new page request is made within the
 * overlay.
 *
 * @return
 *   An array of region names that correspond to those which appear in the
 *   overlay, within the theme that is being used to display the current page.
 *
 * @see overlay_supplemental_regions()
 */
function overlay_regions() {
  return _overlay_region_list('overlay_regions');
}

/**
 * Returns a list of supplemental page regions for the overlay.
 *
 * Supplemental overlay regions are those which are technically part of the
 * parent window, but appear to the user as being related to the overlay
 * (usually because they are displayed next to, rather than underneath, the
 * main overlay regions) and therefore need to be dynamically refreshed if any
 * administrative actions taken within the overlay change their contents.
 *
 * An example of a typical overlay supplemental region would be the 'page_top'
 * region, in the case where a toolbar is being displayed there.
 *
 * @return
 *   An array of region names that correspond to supplemental overlay regions,
 *   within the theme that is being used to display the current page.
 *
 * @see overlay_regions()
 */
function overlay_supplemental_regions() {
  return _overlay_region_list('overlay_supplemental_regions');
}

/**
681
 * Returns a list of page regions related to the overlay.
682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713
 *
 * @param $type
 *   The type of regions to return. This can either be 'overlay_regions' or
 *   'overlay_supplemental_regions'.
 *
 * @return
 *   An array of region names of the given type, within the theme that is being
 *   used to display the current page.
 *
 * @see overlay_regions()
 * @see overlay_supplemental_regions()
 */
function _overlay_region_list($type) {
  // Obtain the current theme. We need to first make sure the theme system is
  // initialized, since this function can be called early in the page request.
  drupal_theme_initialize();
  $themes = list_themes();
  $theme = $themes[$GLOBALS['theme']];
  // Return the list of regions stored within the theme's info array, or an
  // empty array if no regions of the appropriate type are defined.
  return !empty($theme->info[$type]) ? $theme->info[$type] : array();
}

/**
 * Returns a list of page regions that rendering should be limited to.
 *
 * @return
 *   An array containing the names of the regions that will be rendered when
 *   drupal_render_page() is called. If empty, then no limits will be imposed,
 *   and all regions of the page will be rendered.
 *
 * @see overlay_page_alter()
714
 * @see overlay_block_access()
715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735
 * @see overlay_set_regions_to_render()
 */
function overlay_get_regions_to_render() {
  return overlay_set_regions_to_render();
}

/**
 * Sets the regions of the page that rendering will be limited to.
 *
 * @param $regions
 *   (Optional) An array containing the names of the regions that should be
 *   rendered when drupal_render_page() is called. Pass in an empty array to
 *   remove all limits and cause drupal_render_page() to render all page
 *   regions (the default behavior). If this parameter is omitted, no change
 *   will be made to the current list of regions to render.
 *
 * @return
 *   The current list of regions to render, or an empty array if the regions
 *   are not being limited.
 *
 * @see overlay_page_alter()
736
 * @see overlay_block_access()
737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753
 * @see overlay_get_regions_to_render()
 */
function overlay_set_regions_to_render($regions = NULL) {
  $regions_to_render = &drupal_static(__FUNCTION__, array());
  if (isset($regions)) {
    $regions_to_render = $regions;
  }
  return $regions_to_render;
}

/**
 * Renders an individual page region.
 *
 * This function is primarily intended to be used for checking the content of
 * supplemental overlay regions (e.g., a region containing a toolbar). Passing
 * in a region that is intended to display the main page content is not
 * supported; the region will be rendered by this function, but the main page
754 755 756
 * content will not appear in it. In addition, although this function returns
 * the rendered HTML for the provided region, it does not place it on the final
 * page, nor add any of its associated JavaScript or CSS to the page.
757 758 759 760 761 762 763 764 765
 *
 * @param $region
 *   The name of the page region that should be rendered.
 *
 * @return
 *   The rendered HTML of the provided region.
 */
function overlay_render_region($region) {
  // Indicate the region that we will be rendering, so that other regions will
766
  // be hidden by overlay_page_alter() and overlay_block_access().
767 768 769 770 771 772 773 774 775 776 777 778 779
  overlay_set_regions_to_render(array($region));
  // Do what is necessary to force drupal_render_page() to only display HTML
  // from the requested region. Specifically, declare that the main page
  // content does not need to automatically be added to the page, and pass in
  // a page array that has all theme functions removed (so that overall HTML
  // for the page will not be added either).
  $system_main_content_added = &drupal_static('system_main_content_added');
  $system_main_content_added = TRUE;
  $page = array(
    '#type' => 'page',
    '#theme' => NULL,
    '#theme_wrappers' => array(),
  );
780 781 782 783 784 785
  // Render the region, but do not cache any JavaScript or CSS associated with
  // it. This region might not be included the next time drupal_render_page()
  // is called, and we do not want its JavaScript or CSS to erroneously appear
  // on the final rendered page.
  $original_js = drupal_add_js();
  $original_css = drupal_add_css();
786
  $original_libraries = drupal_static('drupal_add_library');
787 788
  $js = &drupal_static('drupal_add_js');
  $css = &drupal_static('drupal_add_css');
789
  $libraries = &drupal_static('drupal_add_library');
790
  $markup = drupal_render_page($page);
791 792
  $js = $original_js;
  $css = $original_css;
793
  $libraries = $original_libraries;
794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846
  // Indicate that the main page content has not, in fact, been displayed, so
  // that future calls to drupal_render_page() will be able to render it
  // correctly.
  $system_main_content_added = FALSE;
  // Restore the original behavior of rendering all regions for the next time
  // drupal_render_page() is called.
  overlay_set_regions_to_render(array());
  return $markup;
}

/**
 * Returns any rendered content that was stored earlier in the page request.
 *
 * @return
 *   An array of all rendered HTML that was stored earlier in the page request,
 *   keyed by the identifier with which it was stored. If no content was
 *   stored, an empty array is returned.
 *
 * @see overlay_store_rendered_content()
 */
function overlay_get_rendered_content() {
  return overlay_store_rendered_content();
}

/**
 * Stores strings representing rendered HTML content.
 *
 * This function is used to keep a static cache of rendered content that can be
 * referred to later in the page request.
 *
 * @param $id
 *   (Optional) An identifier for the content which is being stored, which will
 *   be used as an array key in the returned array. If omitted, no change will
 *   be made to the current stored data.
 * @param $content
 *   (Optional) A string representing the rendered data to store. This only has
 *   an effect if $id is also provided.
 *
 * @return
 *   An array representing all data that is currently being stored, or an empty
 *   array if there is none.
 *
 * @see overlay_get_rendered_content()
 */
function overlay_store_rendered_content($id = NULL, $content = NULL) {
  $rendered_content = &drupal_static(__FUNCTION__, array());
  if (isset($id)) {
    $rendered_content[$id] = $content;
  }
  return $rendered_content;
}

/**
847
 * Requests that the parent window refreshes a particular page region.
848 849 850 851 852
 *
 * @param $region
 *   The name of the page region to refresh. The parent window will trigger a
 *   refresh of this region on the next page load.
 *
853
 * @see overlay_trigger_refresh()
854 855 856
 * @see Drupal.overlay.refreshRegions()
 */
function overlay_request_refresh($region) {
857
  $class = drupal_html_class("region-$region");
858 859 860 861
  $_SESSION['overlay_regions_to_refresh'][] = array($class => $region);
}

/**
862
 * Requests that the entire parent window is reloaded when the overlay closes.
863
 *
864 865 866 867 868 869 870
 * @see overlay_trigger_refresh()
 */
function overlay_request_page_refresh() {
  $_SESSION['overlay_refresh_parent'] = TRUE;
}

/**
871
 * Checks if the parent window needs to be refreshed on this page load.
872 873 874 875 876
 *
 * If the previous page load requested that any page regions be refreshed, or
 * if it requested that the entire page be refreshed when the overlay closes,
 * pass that request via JavaScript to the child window, so it can in turn pass
 * the request to the parent window.
877 878
 *
 * @see overlay_request_refresh()
879
 * @see overlay_request_page_refresh()
880 881
 * @see Drupal.overlay.refreshRegions()
 */
882
function overlay_trigger_refresh() {
883 884 885 886 887 888 889 890 891
  if (!empty($_SESSION['overlay_regions_to_refresh'])) {
    $settings = array(
      'overlayChild' => array(
        'refreshRegions' => $_SESSION['overlay_regions_to_refresh'],
      ),
    );
    drupal_add_js($settings, array('type' => 'setting'));
    unset($_SESSION['overlay_regions_to_refresh']);
  }
892 893 894 895
  if (!empty($_SESSION['overlay_refresh_parent'])) {
    drupal_add_js(array('overlayChild' => array('refreshPage' => TRUE)), array('type' => 'setting'));
    unset($_SESSION['overlay_refresh_parent']);
  }
896 897 898 899 900
}

/**
 * Prints the markup obtained by rendering a single region of the page.
 *
901
 * This function is intended to be called via Ajax.
902 903 904 905 906 907 908
 *
 * @param $region
 *   The name of the page region to render.
 *
 * @see Drupal.overlay.refreshRegions()
 */
function overlay_ajax_render_region($region) {
909
  return new Response(overlay_render_region($region));
910
}