overlay.module

You are here

Displays the Drupal administration interface in an overlay.

Functions

Namesort descending Description
overlay_admin_paths Implements hook_admin_paths().
overlay_ajax_render_region Prints the markup obtained by rendering a single region of the page.
overlay_batch_alter Implements hook_batch_alter().
overlay_block_list_alter Implements hook_block_list_alter().
overlay_close_dialog Requests that the overlay closes when the page is displayed.
overlay_deliver_empty_page Prints an empty page.
overlay_disable_message Returns a renderable array representing a message for disabling the overlay.
overlay_display_empty_page Stores and returns whether an empty page override is needed.
overlay_drupal_goto_alter Implements hook_drupal_goto_alter().
overlay_exit Implements hook_exit().
overlay_form_user_profile_form_alter Implements hook_form_FORM_ID_alter().
overlay_get_mode Gets the current overlay mode.
overlay_get_regions_to_render Returns a list of page regions that rendering should be limited to.
overlay_get_rendered_content Returns any rendered content that was stored earlier in the page request.
overlay_help Implements hook_help().
overlay_init Implements hook_init().
overlay_library Implements hook_library().
overlay_menu Implements hook_menu().
overlay_overlay_child_initialize Implements hook_overlay_child_initialize().
overlay_overlay_parent_initialize Implements hook_overlay_parent_initialize().
overlay_page_alter Implements hook_page_alter().
overlay_page_delivery_callback_alter Implements hook_page_delivery_callback_alter().
overlay_permission Implements hook_permission().
overlay_preprocess_html Implements hook_preprocess_html().
overlay_preprocess_maintenance_page Implements hook_preprocess_maintenance_page().
overlay_preprocess_page Implements hook_preprocess_page().
overlay_regions Returns a list of page regions that appear in the overlay.
overlay_render_region Renders an individual page region.
overlay_request_page_refresh Requests that the entire parent window is reloaded when the overlay closes.
overlay_request_refresh Requests that the parent window refreshes a particular page region.
overlay_set_mode Sets the overlay mode and adds proper JavaScript and styles to the page.
overlay_set_regions_to_render Sets the regions of the page that rendering will be limited to.
overlay_store_rendered_content Stores strings representing rendered HTML content.
overlay_supplemental_regions Returns a list of supplemental page regions for the overlay.
overlay_system_info_alter Implements hook_system_info_alter().
overlay_theme Implements hook_theme().
overlay_trigger_refresh Checks if the parent window needs to be refreshed on this page load.
overlay_user_dismiss_message Page callback: Dismisses the overlay accessibility message for this user.
overlay_user_presave Implements hook_user_presave().
template_preprocess_overlay Implements template_preprocess_HOOK() for overlay.tpl.php
template_process_overlay Implements template_process_HOOK() for overlay.tpl.php
theme_overlay_disable_message Returns the HTML for the message about how to disable the overlay.
_overlay_region_list Returns a list of page regions related to the overlay.

File

modules/overlay/overlay.module
View source
  1. <?php
  2. /**
  3. * @file
  4. * Displays the Drupal administration interface in an overlay.
  5. */
  6. /**
  7. * Implements hook_help().
  8. */
  9. function overlay_help($path, $arg) {
  10. switch ($path) {
  11. case 'admin/help#overlay':
  12. $output = '';
  13. $output .= '<h3>' . t('About') . '</h3>';
  14. $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>';
  15. return $output;
  16. }
  17. }
  18. /**
  19. * Implements hook_menu().
  20. */
  21. function overlay_menu() {
  22. $items['overlay-ajax/%'] = array(
  23. 'title' => '',
  24. 'page callback' => 'overlay_ajax_render_region',
  25. 'page arguments' => array(1),
  26. 'access arguments' => array('access overlay'),
  27. 'type' => MENU_CALLBACK,
  28. );
  29. $items['overlay/dismiss-message'] = array(
  30. 'title' => '',
  31. 'page callback' => 'overlay_user_dismiss_message',
  32. 'access arguments' => array('access overlay'),
  33. 'type' => MENU_CALLBACK,
  34. );
  35. return $items;
  36. }
  37. /**
  38. * Implements hook_admin_paths().
  39. */
  40. function overlay_admin_paths() {
  41. $paths = array(
  42. // This is marked as an administrative path so that if it is visited from
  43. // within the overlay, the user will stay within the overlay while the
  44. // callback is being processed.
  45. 'overlay/dismiss-message' => TRUE,
  46. );
  47. return $paths;
  48. }
  49. /**
  50. * Implements hook_permission().
  51. */
  52. function overlay_permission() {
  53. return array(
  54. 'access overlay' => array(
  55. 'title' => t('Access the administrative overlay'),
  56. 'description' => t('View administrative pages in the overlay.'),
  57. ),
  58. );
  59. }
  60. /**
  61. * Implements hook_theme().
  62. */
  63. function overlay_theme() {
  64. return array(
  65. 'overlay' => array(
  66. 'render element' => 'page',
  67. 'template' => 'overlay',
  68. ),
  69. 'overlay_disable_message' => array(
  70. 'render element' => 'element',
  71. ),
  72. );
  73. }
  74. /**
  75. * Implements hook_form_FORM_ID_alter().
  76. */
  77. function overlay_form_user_profile_form_alter(&$form, &$form_state) {
  78. if ($form['#user_category'] == 'account') {
  79. $account = $form['#user'];
  80. if (user_access('access overlay', $account)) {
  81. $form['overlay_control'] = array(
  82. '#type' => 'fieldset',
  83. '#title' => t('Administrative overlay'),
  84. '#weight' => 4,
  85. '#collapsible' => TRUE,
  86. );
  87. $form['overlay_control']['overlay'] = array(
  88. '#type' => 'checkbox',
  89. '#title' => t('Use the overlay for administrative pages.'),
  90. '#description' => t('Show administrative pages on top of the page you started from.'),
  91. '#default_value' => isset($account->data['overlay']) ? $account->data['overlay'] : 1,
  92. );
  93. }
  94. }
  95. }
  96. /**
  97. * Implements hook_user_presave().
  98. */
  99. function overlay_user_presave(&$edit, $account, $category) {
  100. if (isset($edit['overlay'])) {
  101. $edit['data']['overlay'] = $edit['overlay'];
  102. }
  103. }
  104. /**
  105. * Implements hook_init().
  106. *
  107. * Determine whether the current page request is destined to appear in the
  108. * parent window or in the overlay window, and format the page accordingly.
  109. *
  110. * @see overlay_set_mode()
  111. */
  112. function overlay_init() {
  113. global $user;
  114. $mode = overlay_get_mode();
  115. // Only act if the user has access to the overlay and a mode was not already
  116. // set. Other modules can also enable the overlay directly for other uses.
  117. $use_overlay = !isset($user->data['overlay']) || $user->data['overlay'];
  118. if (empty($mode) && user_access('access overlay') && $use_overlay) {
  119. $current_path = current_path();
  120. // After overlay is enabled on the modules page, redirect to
  121. // <front>#overlay=admin/modules to actually enable the overlay.
  122. if (isset($_SESSION['overlay_enable_redirect']) && $_SESSION['overlay_enable_redirect']) {
  123. unset($_SESSION['overlay_enable_redirect']);
  124. drupal_goto('<front>', array('fragment' => 'overlay=' . $current_path));
  125. }
  126. if (isset($_GET['render']) && $_GET['render'] == 'overlay') {
  127. // If a previous page requested that we close the overlay, close it and
  128. // redirect to the final destination.
  129. if (isset($_SESSION['overlay_close_dialog'])) {
  130. call_user_func_array('overlay_close_dialog', $_SESSION['overlay_close_dialog']);
  131. unset($_SESSION['overlay_close_dialog']);
  132. }
  133. // If this page shouldn't be rendered inside the overlay, redirect to the
  134. // parent.
  135. elseif (!path_is_admin($current_path)) {
  136. // Prevent open redirects by ensuring the current path is not an absolute URL.
  137. if (url_is_external($current_path)) {
  138. $current_path = '<front>';
  139. }
  140. overlay_close_dialog($current_path, array('query' => drupal_get_query_parameters(NULL, array('q', 'render'))));
  141. }
  142. // Indicate that we are viewing an overlay child page.
  143. overlay_set_mode('child');
  144. // Unset the render parameter to avoid it being included in URLs on the page.
  145. unset($_GET['render']);
  146. }
  147. // Do not enable the overlay if we already are on an admin page.
  148. elseif (!path_is_admin($current_path)) {
  149. // Otherwise add overlay parent code and our behavior.
  150. overlay_set_mode('parent');
  151. }
  152. }
  153. }
  154. /**
  155. * Implements hook_exit().
  156. *
  157. * When viewing an overlay child page, check if we need to trigger a refresh of
  158. * the supplemental regions of the overlay on the next page request.
  159. */
  160. function overlay_exit() {
  161. // Check that we are in an overlay child page. Note that this should never
  162. // return TRUE on a cached page view, since the child mode is not set until
  163. // overlay_init() is called.
  164. if (overlay_get_mode() == 'child') {
  165. // Load any markup that was stored earlier in the page request, via calls
  166. // to overlay_store_rendered_content(). If none was stored, this is not a
  167. // page request where we expect any changes to the overlay supplemental
  168. // regions to have occurred, so we do not need to proceed any further.
  169. $original_markup = overlay_get_rendered_content();
  170. if (!empty($original_markup)) {
  171. // Compare the original markup to the current markup that we get from
  172. // rendering each overlay supplemental region now. If they don't match,
  173. // something must have changed, so we request a refresh of that region
  174. // within the parent window on the next page request.
  175. foreach (overlay_supplemental_regions() as $region) {
  176. if (!isset($original_markup[$region]) || $original_markup[$region] != overlay_render_region($region)) {
  177. overlay_request_refresh($region);
  178. }
  179. }
  180. }
  181. }
  182. }
  183. /**
  184. * Implements hook_library().
  185. */
  186. function overlay_library() {
  187. $module_path = drupal_get_path('module', 'overlay');
  188. // Overlay parent.
  189. $libraries['parent'] = array(
  190. 'title' => 'Overlay: Parent',
  191. 'website' => 'http://drupal.org/documentation/modules/overlay',
  192. 'version' => '1.0',
  193. 'js' => array(
  194. $module_path . '/overlay-parent.js' => array(),
  195. ),
  196. 'css' => array(
  197. $module_path . '/overlay-parent.css' => array(),
  198. ),
  199. 'dependencies' => array(
  200. array('system', 'ui'),
  201. array('system', 'jquery.bbq'),
  202. ),
  203. );
  204. // Overlay child.
  205. $libraries['child'] = array(
  206. 'title' => 'Overlay: Child',
  207. 'website' => 'http://drupal.org/documentation/modules/overlay',
  208. 'version' => '1.0',
  209. 'js' => array(
  210. $module_path . '/overlay-child.js' => array(),
  211. ),
  212. 'css' => array(
  213. $module_path . '/overlay-child.css' => array(),
  214. ),
  215. );
  216. return $libraries;
  217. }
  218. /**
  219. * Implements hook_drupal_goto_alter().
  220. */
  221. function overlay_drupal_goto_alter(&$path, &$options, &$http_response_code) {
  222. if (overlay_get_mode() == 'child') {
  223. // The authorize.php script bootstraps Drupal to a very low level, where
  224. // the PHP code that is necessary to close the overlay properly will not be
  225. // loaded. Therefore, if we are redirecting to authorize.php inside the
  226. // overlay, instead redirect back to the current page with instructions to
  227. // close the overlay there before redirecting to the final destination; see
  228. // overlay_init().
  229. if ($path == system_authorized_get_url() || $path == system_authorized_batch_processing_url()) {
  230. $_SESSION['overlay_close_dialog'] = array($path, $options);
  231. $path = current_path();
  232. $options = drupal_get_query_parameters();
  233. }
  234. // If the current page request is inside the overlay, add ?render=overlay
  235. // to the new path, so that it appears correctly inside the overlay.
  236. if (isset($options['query'])) {
  237. $options['query'] += array('render' => 'overlay');
  238. }
  239. else {
  240. $options['query'] = array('render' => 'overlay');
  241. }
  242. }
  243. }
  244. /**
  245. * Implements hook_batch_alter().
  246. *
  247. * If the current page request is inside the overlay, add ?render=overlay to
  248. * the success callback URL, so that it appears correctly within the overlay.
  249. *
  250. * @see overlay_get_mode()
  251. */
  252. function overlay_batch_alter(&$batch) {
  253. if (overlay_get_mode() == 'child') {
  254. if (isset($batch['url_options']['query'])) {
  255. $batch['url_options']['query']['render'] = 'overlay';
  256. }
  257. else {
  258. $batch['url_options']['query'] = array('render' => 'overlay');
  259. }
  260. }
  261. }
  262. /**
  263. * Implements hook_page_alter().
  264. */
  265. function overlay_page_alter(&$page) {
  266. // If we are limiting rendering to a subset of page regions, deny access to
  267. // all other regions so that they will not be processed.
  268. if ($regions_to_render = overlay_get_regions_to_render()) {
  269. $skipped_regions = array_diff(element_children($page), $regions_to_render);
  270. foreach ($skipped_regions as $skipped_region) {
  271. $page[$skipped_region]['#access'] = FALSE;
  272. }
  273. }
  274. $mode = overlay_get_mode();
  275. if ($mode == 'child') {
  276. // Add the overlay wrapper before the html wrapper.
  277. array_unshift($page['#theme_wrappers'], 'overlay');
  278. }
  279. elseif ($mode == 'parent' && ($message = overlay_disable_message())) {
  280. $page['page_top']['disable_overlay'] = $message;
  281. }
  282. }
  283. /**
  284. * Page callback: Dismisses the overlay accessibility message for this user.
  285. *
  286. * @return
  287. * A render array for a page containing a list of content.
  288. */
  289. function overlay_user_dismiss_message() {
  290. global $user;
  291. // It's unlikely, but possible that "access overlay" permission is granted to
  292. // the anonymous role. In this case, we do not display the message to disable
  293. // the overlay, so there is nothing to dismiss. Also, protect against
  294. // cross-site request forgeries by validating a token.
  295. if (empty($user->uid) || !isset($_GET['token']) || !drupal_valid_token($_GET['token'], 'overlay')) {
  296. return MENU_ACCESS_DENIED;
  297. }
  298. else {
  299. user_save(user_load($user->uid), array('data' => array('overlay_message_dismissed' => 1)));
  300. drupal_set_message(t('The message has been dismissed. You can change your overlay settings at any time by visiting your profile page.'));
  301. // Destination is normally given. Go to the user profile as a fallback.
  302. drupal_goto('user/' . $user->uid . '/edit');
  303. }
  304. }
  305. /**
  306. * Returns a renderable array representing a message for disabling the overlay.
  307. *
  308. * If the current user can access the overlay and has not previously indicated
  309. * that this message should be dismissed, this function returns a message
  310. * containing a link to disable the overlay. Nothing is returned for anonymous
  311. * users, because the links control per-user settings. Because some screen
  312. * readers are unable to properly read overlay contents, site builders are
  313. * discouraged from granting the "access overlay" permission to the anonymous
  314. * role.
  315. *
  316. * @see http://drupal.org/node/890284
  317. */
  318. function overlay_disable_message() {
  319. global $user;
  320. if (!empty($user->uid) && empty($user->data['overlay_message_dismissed']) && (!isset($user->data['overlay']) || $user->data['overlay']) && user_access('access overlay')) {
  321. $build = array(
  322. '#theme' => 'overlay_disable_message',
  323. '#weight' => -99,
  324. // Link to the user's profile page, where the overlay can be disabled.
  325. 'profile_link' => array(
  326. '#type' => 'link',
  327. '#title' => t('If you have problems accessing administrative pages on this site, disable the overlay on your profile page.'),
  328. '#href' => 'user/' . $user->uid . '/edit',
  329. '#options' => array(
  330. 'query' => drupal_get_destination(),
  331. 'fragment' => 'edit-overlay-control',
  332. 'attributes' => array(
  333. 'id' => 'overlay-profile-link',
  334. // Prevent the target page from being opened in the overlay.
  335. 'class' => array('overlay-exclude'),
  336. ),
  337. ),
  338. ),
  339. // Link to a menu callback that allows this message to be permanently
  340. // dismissed for the current user.
  341. 'dismiss_message_link' => array(
  342. '#type' => 'link',
  343. '#title' => t('Dismiss this message.'),
  344. '#href' => 'overlay/dismiss-message',
  345. '#options' => array(
  346. 'query' => drupal_get_destination() + array(
  347. // Add a token to protect against cross-site request forgeries.
  348. 'token' => drupal_get_token('overlay'),
  349. ),
  350. 'attributes' => array(
  351. 'id' => 'overlay-dismiss-message',
  352. // If this message is being displayed outside the overlay, prevent
  353. // this link from opening the overlay.
  354. 'class' => (overlay_get_mode() == 'parent') ? array('overlay-exclude') : array(),
  355. ),
  356. ),
  357. )
  358. );
  359. }
  360. else {
  361. $build = array();
  362. }
  363. return $build;
  364. }
  365. /**
  366. * Returns the HTML for the message about how to disable the overlay.
  367. *
  368. * @param $variables
  369. * An associative array with an 'element' element, which itself is an
  370. * associative array containing:
  371. * - profile_link: The link to this user's account.
  372. * - dismiss_message_link: The link to dismiss the overlay.
  373. *
  374. * @ingroup themeable
  375. */
  376. function theme_overlay_disable_message($variables) {
  377. $element = $variables['element'];
  378. // Add CSS classes to hide the links from most sighted users, while keeping
  379. // them accessible to screen-reader users and keyboard-only users. To assist
  380. // screen-reader users, this message appears in both the parent and child
  381. // documents, but only the one in the child document is part of the tab order.
  382. foreach (array('profile_link', 'dismiss_message_link') as $key) {
  383. $element[$key]['#options']['attributes']['class'][] = 'element-invisible';
  384. if (overlay_get_mode() == 'child') {
  385. $element[$key]['#options']['attributes']['class'][] = 'element-focusable';
  386. }
  387. }
  388. // Render the links.
  389. $output = drupal_render($element['profile_link']) . ' ' . drupal_render($element['dismiss_message_link']);
  390. // Add a heading for screen-reader users. The heading doesn't need to be seen
  391. // by sighted users.
  392. $output = '<h3 class="element-invisible">' . t('Options for the administrative overlay') . '</h3>' . $output;
  393. // Wrap in a container for styling.
  394. $output = '<div id="overlay-disable-message" class="clearfix">' . $output . '</div>';
  395. return $output;
  396. }
  397. /**
  398. * Implements hook_block_list_alter().
  399. */
  400. function overlay_block_list_alter(&$blocks) {
  401. // If we are limiting rendering to a subset of page regions, hide all blocks
  402. // which appear in regions not on that list. Note that overlay_page_alter()
  403. // does a more comprehensive job of preventing unwanted regions from being
  404. // displayed (regardless of whether they contain blocks or not), but the
  405. // reason for duplicating effort here is performance; we do not even want
  406. // these blocks to be built if they are not going to be displayed.
  407. if ($regions_to_render = overlay_get_regions_to_render()) {
  408. foreach ($blocks as $bid => $block) {
  409. if (!in_array($block->region, $regions_to_render)) {
  410. unset($blocks[$bid]);
  411. }
  412. }
  413. }
  414. }
  415. /**
  416. * Implements hook_system_info_alter().
  417. *
  418. * Add default regions for the overlay.
  419. */
  420. function overlay_system_info_alter(&$info, $file, $type) {
  421. if ($type == 'theme') {
  422. $info['overlay_regions'][] = 'content';
  423. $info['overlay_regions'][] = 'help';
  424. }
  425. }
  426. /**
  427. * Implements hook_preprocess_html().
  428. *
  429. * If the current page request is inside the overlay, add appropriate classes
  430. * to the <body> element, and simplify the page title.
  431. *
  432. * @see overlay_get_mode()
  433. */
  434. function overlay_preprocess_html(&$variables) {
  435. if (overlay_get_mode() == 'child') {
  436. // Add overlay class, so themes can react to being displayed in the overlay.
  437. $variables['classes_array'][] = 'overlay';
  438. }
  439. }
  440. /**
  441. * Implements hook_preprocess_maintenance_page().
  442. *
  443. * If the current page request is inside the overlay, add appropriate classes
  444. * to the <body> element, and simplify the page title.
  445. *
  446. * @see overlay_preprocess_maintenance_page()
  447. */
  448. function overlay_preprocess_maintenance_page(&$variables) {
  449. overlay_preprocess_html($variables);
  450. }
  451. /**
  452. * Implements template_preprocess_HOOK() for overlay.tpl.php
  453. *
  454. * If the current page request is inside the overlay, add appropriate classes
  455. * to the <body> element, and simplify the page title.
  456. *
  457. * @see template_process_overlay()
  458. * @see overlay.tpl.php
  459. */
  460. function template_preprocess_overlay(&$variables) {
  461. $variables['tabs'] = menu_primary_local_tasks();
  462. $variables['title'] = drupal_get_title();
  463. $variables['disable_overlay'] = overlay_disable_message();
  464. $variables['content_attributes_array']['class'][] = 'clearfix';
  465. }
  466. /**
  467. * Implements template_process_HOOK() for overlay.tpl.php
  468. *
  469. * Places the rendered HTML for the page body into a top level variable.
  470. *
  471. * @see template_preprocess_overlay()
  472. * @see overlay.tpl.php
  473. */
  474. function template_process_overlay(&$variables) {
  475. $variables['page'] = $variables['page']['#children'];
  476. }
  477. /**
  478. * Implements hook_preprocess_page().
  479. *
  480. * If the current page request is inside the overlay, hide the tabs.
  481. *
  482. * @see overlay_get_mode()
  483. */
  484. function overlay_preprocess_page(&$variables) {
  485. if (overlay_get_mode() == 'child') {
  486. unset($variables['tabs']['#primary']);
  487. }
  488. }
  489. /**
  490. * Stores and returns whether an empty page override is needed.
  491. *
  492. * This is used to prevent a page request which closes the overlay (for
  493. * example, a form submission) from being fully re-rendered before the overlay
  494. * is closed. Instead, we store a variable which will cause the page to be
  495. * rendered by a delivery callback function that does not actually print
  496. * visible HTML (but rather only the bare minimum scripts and styles necessary
  497. * to trigger the overlay to close), thereby allowing the dialog to be closed
  498. * faster and with less interruption, and also allowing the display of messages
  499. * to be deferred to the parent window (rather than displaying them in the
  500. * child window, which will close before the user has had a chance to read
  501. * them).
  502. *
  503. * @param $value
  504. * By default, an empty page will not be displayed. Set to TRUE to request
  505. * an empty page display, or FALSE to disable the empty page display (if it
  506. * was previously enabled on this page request).
  507. *
  508. * @return
  509. * TRUE if the current behavior is to display an empty page, or FALSE if not.
  510. *
  511. * @see overlay_page_delivery_callback_alter()
  512. */
  513. function overlay_display_empty_page($value = NULL) {
  514. $display_empty_page = &drupal_static(__FUNCTION__, FALSE);
  515. if (isset($value)) {
  516. $display_empty_page = $value;
  517. }
  518. return $display_empty_page;
  519. }
  520. /**
  521. * Implements hook_page_delivery_callback_alter().
  522. */
  523. function overlay_page_delivery_callback_alter(&$callback) {
  524. if (overlay_display_empty_page()) {
  525. $callback = 'overlay_deliver_empty_page';
  526. }
  527. }
  528. /**
  529. * Prints an empty page.
  530. *
  531. * This function is used to print out a bare minimum empty page which still has
  532. * the scripts and styles necessary in order to trigger the overlay to close.
  533. */
  534. function overlay_deliver_empty_page() {
  535. $empty_page = '<html><head><title></title>' . drupal_get_css() . drupal_get_js() . '</head><body class="overlay"></body></html>';
  536. print $empty_page;
  537. drupal_exit();
  538. }
  539. /**
  540. * Gets the current overlay mode.
  541. *
  542. * @see overlay_set_mode()
  543. */
  544. function overlay_get_mode() {
  545. return overlay_set_mode(NULL);
  546. }
  547. /**
  548. * Sets the overlay mode and adds proper JavaScript and styles to the page.
  549. *
  550. * Note that since setting the overlay mode triggers a variety of behaviors
  551. * (including hooks being invoked), it can only be done once per page request.
  552. * Therefore, the first call to this function which passes along a value of the
  553. * $mode parameter controls the overlay mode that will be used.
  554. *
  555. * @param $mode
  556. * To set the mode, pass in one of the following values:
  557. * - 'parent': This is used in the context of a parent window (a regular
  558. * browser window). If set, JavaScript is added so that administrative
  559. * links in the parent window will open in an overlay.
  560. * - 'child': This is used in the context of the child overlay window (the
  561. * page actually appearing within the overlay iframe). If set, JavaScript
  562. * and CSS are added so that Drupal behaves nicely from within the overlay.
  563. * - 'none': This is used to avoid adding any overlay-related code to the
  564. * page at all. Modules can set this to explicitly prevent the overlay from
  565. * being used. For example, since the overlay module itself sets the mode
  566. * to 'parent' or 'child' in overlay_init() when certain conditions are
  567. * met, other modules which want to override that behavior can do so by
  568. * setting the mode to 'none' earlier in the page request - e.g., in their
  569. * own hook_init() implementations, if they have a lower weight.
  570. * This parameter is optional, and if omitted, the current mode will be
  571. * returned with no action taken.
  572. *
  573. * @return
  574. * The current mode, if any has been set, or NULL if no mode has been set.
  575. *
  576. * @ingroup overlay_api
  577. * @see overlay_init()
  578. */
  579. function overlay_set_mode($mode = NULL) {
  580. global $base_path;
  581. $overlay_mode = &drupal_static(__FUNCTION__);
  582. // Make sure external resources are not included more than once. Also return
  583. // the current mode, if no mode was specified.
  584. if (isset($overlay_mode) || !isset($mode)) {
  585. return $overlay_mode;
  586. }
  587. $overlay_mode = $mode;
  588. switch ($overlay_mode) {
  589. case 'parent':
  590. drupal_add_library('overlay', 'parent');
  591. // Allow modules to act upon overlay events.
  592. module_invoke_all('overlay_parent_initialize');
  593. break;
  594. case 'child':
  595. drupal_add_library('overlay', 'child');
  596. // Allow modules to act upon overlay events.
  597. module_invoke_all('overlay_child_initialize');
  598. break;
  599. }
  600. return $overlay_mode;
  601. }
  602. /**
  603. * Implements hook_overlay_parent_initialize().
  604. */
  605. function overlay_overlay_parent_initialize() {
  606. // Let the client side know which paths are administrative.
  607. $paths = path_get_admin_paths();
  608. foreach ($paths as &$type) {
  609. $type = str_replace('<front>', variable_get('site_frontpage', 'node'), $type);
  610. }
  611. drupal_add_js(array('overlay' => array('paths' => $paths)), 'setting');
  612. $path_prefixes = array();
  613. if (module_exists('locale') && variable_get('locale_language_negotiation_url_part', LOCALE_LANGUAGE_NEGOTIATION_URL_PREFIX) == LOCALE_LANGUAGE_NEGOTIATION_URL_PREFIX) {
  614. // Get languages grouped by status and select only the enabled ones.
  615. $languages = language_list('enabled');
  616. $languages = $languages[1];
  617. $path_prefixes = array();
  618. foreach ($languages as $language) {
  619. if ($language->prefix) {
  620. $path_prefixes[] = $language->prefix;
  621. }
  622. }
  623. }
  624. drupal_add_js(array('overlay' => array('pathPrefixes' => $path_prefixes)), 'setting');
  625. // Pass along the Ajax callback for rerendering sections of the parent window.
  626. drupal_add_js(array('overlay' => array('ajaxCallback' => 'overlay-ajax')), 'setting');
  627. }
  628. /**
  629. * Implements hook_overlay_child_initialize().
  630. */
  631. function overlay_overlay_child_initialize() {
  632. // Check if the parent window needs to refresh any page regions on this page
  633. // request.
  634. overlay_trigger_refresh();
  635. // If this is a POST request, or a GET request with a token parameter, we
  636. // have an indication that something in the supplemental regions of the
  637. // overlay might change during the current page request. We therefore store
  638. // the initial rendered content of those regions here, so that we can compare
  639. // it to the same content rendered in overlay_exit(), at the end of the page
  640. // request. This allows us to check if anything actually did change, and, if
  641. // so, trigger an immediate Ajax refresh of the parent window.
  642. if (!empty($_POST) || isset($_GET['token'])) {
  643. foreach (overlay_supplemental_regions() as $region) {
  644. overlay_store_rendered_content($region, overlay_render_region($region));
  645. }
  646. // In addition, notify the parent window that when the overlay closes,
  647. // the entire parent window should be refreshed.
  648. overlay_request_page_refresh();
  649. }
  650. // Indicate that when the main page rendering occurs later in the page
  651. // request, only the regions that appear within the overlay should be
  652. // rendered.
  653. overlay_set_regions_to_render(overlay_regions());
  654. }
  655. /**
  656. * Requests that the overlay closes when the page is displayed.
  657. *
  658. * @param $redirect
  659. * (optional) The path that should open in the parent window after the
  660. * overlay closes. If not set, no redirect will be performed on the parent
  661. * window.
  662. *
  663. * @param $redirect_options
  664. * (optional) An associative array of options to use when generating the
  665. * redirect URL.
  666. */
  667. function overlay_close_dialog($redirect = NULL, $redirect_options = array()) {
  668. $settings = array(
  669. 'overlayChild' => array(
  670. 'closeOverlay' => TRUE,
  671. ),
  672. );
  673. // Tell the child window to perform the redirection when requested to.
  674. if (isset($redirect)) {
  675. $settings['overlayChild']['redirect'] = url($redirect, $redirect_options);
  676. }
  677. drupal_add_js($settings, array('type' => 'setting'));
  678. // Since we are closing the overlay as soon as the page is displayed, we do
  679. // not want to show any of the page's actual content.
  680. overlay_display_empty_page(TRUE);
  681. }
  682. /**
  683. * Returns a list of page regions that appear in the overlay.
  684. *
  685. * Overlay regions correspond to the entire contents of the overlay child
  686. * window and are refreshed each time a new page request is made within the
  687. * overlay.
  688. *
  689. * @return
  690. * An array of region names that correspond to those which appear in the
  691. * overlay, within the theme that is being used to display the current page.
  692. *
  693. * @see overlay_supplemental_regions()
  694. */
  695. function overlay_regions() {
  696. return _overlay_region_list('overlay_regions');
  697. }
  698. /**
  699. * Returns a list of supplemental page regions for the overlay.
  700. *
  701. * Supplemental overlay regions are those which are technically part of the
  702. * parent window, but appear to the user as being related to the overlay
  703. * (usually because they are displayed next to, rather than underneath, the
  704. * main overlay regions) and therefore need to be dynamically refreshed if any
  705. * administrative actions taken within the overlay change their contents.
  706. *
  707. * An example of a typical overlay supplemental region would be the 'page_top'
  708. * region, in the case where a toolbar is being displayed there.
  709. *
  710. * @return
  711. * An array of region names that correspond to supplemental overlay regions,
  712. * within the theme that is being used to display the current page.
  713. *
  714. * @see overlay_regions()
  715. */
  716. function overlay_supplemental_regions() {
  717. return _overlay_region_list('overlay_supplemental_regions');
  718. }
  719. /**
  720. * Returns a list of page regions related to the overlay.
  721. *
  722. * @param $type
  723. * The type of regions to return. This can either be 'overlay_regions' or
  724. * 'overlay_supplemental_regions'.
  725. *
  726. * @return
  727. * An array of region names of the given type, within the theme that is being
  728. * used to display the current page.
  729. *
  730. * @see overlay_regions()
  731. * @see overlay_supplemental_regions()
  732. */
  733. function _overlay_region_list($type) {
  734. // Obtain the current theme. We need to first make sure the theme system is
  735. // initialized, since this function can be called early in the page request.
  736. drupal_theme_initialize();
  737. $themes = list_themes();
  738. $theme = $themes[$GLOBALS['theme']];
  739. // Return the list of regions stored within the theme's info array, or an
  740. // empty array if no regions of the appropriate type are defined.
  741. return !empty($theme->info[$type]) ? $theme->info[$type] : array();
  742. }
  743. /**
  744. * Returns a list of page regions that rendering should be limited to.
  745. *
  746. * @return
  747. * An array containing the names of the regions that will be rendered when
  748. * drupal_render_page() is called. If empty, then no limits will be imposed,
  749. * and all regions of the page will be rendered.
  750. *
  751. * @see overlay_page_alter()
  752. * @see overlay_block_list_alter()
  753. * @see overlay_set_regions_to_render()
  754. */
  755. function overlay_get_regions_to_render() {
  756. return overlay_set_regions_to_render();
  757. }
  758. /**
  759. * Sets the regions of the page that rendering will be limited to.
  760. *
  761. * @param $regions
  762. * (Optional) An array containing the names of the regions that should be
  763. * rendered when drupal_render_page() is called. Pass in an empty array to
  764. * remove all limits and cause drupal_render_page() to render all page
  765. * regions (the default behavior). If this parameter is omitted, no change
  766. * will be made to the current list of regions to render.
  767. *
  768. * @return
  769. * The current list of regions to render, or an empty array if the regions
  770. * are not being limited.
  771. *
  772. * @see overlay_page_alter()
  773. * @see overlay_block_list_alter()
  774. * @see overlay_get_regions_to_render()
  775. */
  776. function overlay_set_regions_to_render($regions = NULL) {
  777. $regions_to_render = &drupal_static(__FUNCTION__, array());
  778. if (isset($regions)) {
  779. $regions_to_render = $regions;
  780. }
  781. return $regions_to_render;
  782. }
  783. /**
  784. * Renders an individual page region.
  785. *
  786. * This function is primarily intended to be used for checking the content of
  787. * supplemental overlay regions (e.g., a region containing a toolbar). Passing
  788. * in a region that is intended to display the main page content is not
  789. * supported; the region will be rendered by this function, but the main page
  790. * content will not appear in it. In addition, although this function returns
  791. * the rendered HTML for the provided region, it does not place it on the final
  792. * page, nor add any of its associated JavaScript or CSS to the page.
  793. *
  794. * @param $region
  795. * The name of the page region that should be rendered.
  796. *
  797. * @return
  798. * The rendered HTML of the provided region.
  799. */
  800. function overlay_render_region($region) {
  801. // Indicate the region that we will be rendering, so that other regions will
  802. // be hidden by overlay_page_alter() and overlay_block_list_alter().
  803. overlay_set_regions_to_render(array($region));
  804. // Do what is necessary to force drupal_render_page() to only display HTML
  805. // from the requested region. Specifically, declare that the main page
  806. // content does not need to automatically be added to the page, and pass in
  807. // a page array that has all theme functions removed (so that overall HTML
  808. // for the page will not be added either).
  809. $system_main_content_added = &drupal_static('system_main_content_added');
  810. $system_main_content_added = TRUE;
  811. $page = array(
  812. '#type' => 'page',
  813. '#theme' => NULL,
  814. '#theme_wrappers' => array(),
  815. );
  816. // Render the region, but do not cache any JavaScript or CSS associated with
  817. // it. This region might not be included the next time drupal_render_page()
  818. // is called, and we do not want its JavaScript or CSS to erroneously appear
  819. // on the final rendered page.
  820. $original_js = drupal_add_js();
  821. $original_css = drupal_add_css();
  822. $original_libraries = drupal_static('drupal_add_library');
  823. $js = &drupal_static('drupal_add_js');
  824. $css = &drupal_static('drupal_add_css');
  825. $libraries = &drupal_static('drupal_add_library');
  826. $markup = drupal_render_page($page);
  827. $js = $original_js;
  828. $css = $original_css;
  829. $libraries = $original_libraries;
  830. // Indicate that the main page content has not, in fact, been displayed, so
  831. // that future calls to drupal_render_page() will be able to render it
  832. // correctly.
  833. $system_main_content_added = FALSE;
  834. // Restore the original behavior of rendering all regions for the next time
  835. // drupal_render_page() is called.
  836. overlay_set_regions_to_render(array());
  837. return $markup;
  838. }
  839. /**
  840. * Returns any rendered content that was stored earlier in the page request.
  841. *
  842. * @return
  843. * An array of all rendered HTML that was stored earlier in the page request,
  844. * keyed by the identifier with which it was stored. If no content was
  845. * stored, an empty array is returned.
  846. *
  847. * @see overlay_store_rendered_content()
  848. */
  849. function overlay_get_rendered_content() {
  850. return overlay_store_rendered_content();
  851. }
  852. /**
  853. * Stores strings representing rendered HTML content.
  854. *
  855. * This function is used to keep a static cache of rendered content that can be
  856. * referred to later in the page request.
  857. *
  858. * @param $id
  859. * (Optional) An identifier for the content which is being stored, which will
  860. * be used as an array key in the returned array. If omitted, no change will
  861. * be made to the current stored data.
  862. * @param $content
  863. * (Optional) A string representing the rendered data to store. This only has
  864. * an effect if $id is also provided.
  865. *
  866. * @return
  867. * An array representing all data that is currently being stored, or an empty
  868. * array if there is none.
  869. *
  870. * @see overlay_get_rendered_content()
  871. */
  872. function overlay_store_rendered_content($id = NULL, $content = NULL) {
  873. $rendered_content = &drupal_static(__FUNCTION__, array());
  874. if (isset($id)) {
  875. $rendered_content[$id] = $content;
  876. }
  877. return $rendered_content;
  878. }
  879. /**
  880. * Requests that the parent window refreshes a particular page region.
  881. *
  882. * @param $region
  883. * The name of the page region to refresh. The parent window will trigger a
  884. * refresh of this region on the next page load.
  885. *
  886. * @see overlay_trigger_refresh()
  887. * @see Drupal.overlay.refreshRegions()
  888. */
  889. function overlay_request_refresh($region) {
  890. $class = drupal_region_class($region);
  891. $_SESSION['overlay_regions_to_refresh'][] = array($class => $region);
  892. }
  893. /**
  894. * Requests that the entire parent window is reloaded when the overlay closes.
  895. *
  896. * @see overlay_trigger_refresh()
  897. */
  898. function overlay_request_page_refresh() {
  899. $_SESSION['overlay_refresh_parent'] = TRUE;
  900. }
  901. /**
  902. * Checks if the parent window needs to be refreshed on this page load.
  903. *
  904. * If the previous page load requested that any page regions be refreshed, or
  905. * if it requested that the entire page be refreshed when the overlay closes,
  906. * pass that request via JavaScript to the child window, so it can in turn pass
  907. * the request to the parent window.
  908. *
  909. * @see overlay_request_refresh()
  910. * @see overlay_request_page_refresh()
  911. * @see Drupal.overlay.refreshRegions()
  912. */
  913. function overlay_trigger_refresh() {
  914. if (!empty($_SESSION['overlay_regions_to_refresh'])) {
  915. $settings = array(
  916. 'overlayChild' => array(
  917. 'refreshRegions' => $_SESSION['overlay_regions_to_refresh'],
  918. ),
  919. );
  920. drupal_add_js($settings, array('type' => 'setting'));
  921. unset($_SESSION['overlay_regions_to_refresh']);
  922. }
  923. if (!empty($_SESSION['overlay_refresh_parent'])) {
  924. drupal_add_js(array('overlayChild' => array('refreshPage' => TRUE)), array('type' => 'setting'));
  925. unset($_SESSION['overlay_refresh_parent']);
  926. }
  927. }
  928. /**
  929. * Prints the markup obtained by rendering a single region of the page.
  930. *
  931. * This function is intended to be called via Ajax.
  932. *
  933. * @param $region
  934. * The name of the page region to render.
  935. *
  936. * @see Drupal.overlay.refreshRegions()
  937. */
  938. function overlay_ajax_render_region($region) {
  939. print overlay_render_region($region);
  940. }

Comments

<?php
/**
* Like drupal_goto(), but tries to open the given path in the overlay.
*
* @param string $url
*   The destination url.
* @param array $options
*   Optional options that are passed to the url() function.
* @param string $parent
*   Optional url of the page that is displayed underneath the overlay. By
*   default the current page is shown.
*/
function MODULE_goto_overlay($url, $options = array(), $parent = NULL) {
  if (
module_exists('overlay')) {
   
$options['fragment'] = 'overlay=' . $url;
   
$url = $parent ? $parent : $_GET['q'];
  }
 
drupal_goto($url, $options);
}
?>