Modal Frame API

markus_petrux - May 26, 2009 - 17:03

This module provides an API to render an iframe within a modal dialog based on the jQuery UI Dialog plugin. You should not install this module unless another module requires you to, or you wish to use it for your own custom modules.

It is an alternative to Popups API (Ajax Dialogs) which implements its own library and API to manage popup dialogs. On the other hand, the Modal Frame API is based on the jQuery UI Dialog plugin and it is specially built to deal with iframe elements with very little effort (and no particular AJAX requirements).

For themers, this module provides a default template for rendering child pages within modal frames (modalframe-page.tpl.php) that can be copied to the theme directory and customized to suit the particular needs of the site. It is also pretty easy to adapt the provided stylesheets to match the look of the site.

Requirements related to jQuery UI: jQuery UI (jQuery UI 1.6.x or 1.7.x). If you opt for jQuery UI 1.7.x, you also need jQuery 1.3.x, currently provided by jQuery Update 6.x-2.x.

Highly recommended: onBeforeUnload API (enhances synchronization of parent/child windows).

Builtin support for: Dirty Forms.

Modules using Modal Frame API: Node Relationships, Subnodes by Taxonomy.

Modal Frame API is pretty simple, but powerful at the same time.

The server-side API looks as follows:

modalframe_parent_js() - Adds the Modal Frame javascript and stylesheets to the parent page. You should use this when you wish to use the client-side API to manage frames within a modal dialog.
modalframe_child_js() - Adds the Modal Frame javascript and stylesheets to the child page. This is necessary for pages and/or forms that are rendered within a modal frame.
modalframe_close_dialog($args) - When a form is rendered within a modal frame (what we would call the child window), you can use this function from your form submit handler to close the client-side dialog. You can also give it arguments that will be passed to an optional onSubmit dialog callback that you can provide when opening the modal frame from the parent window.

The client-side API looks as follows:

Drupal.modalFrame.open(options) - Use this method to open a modal frame. The argument is a javascript object that may contain the following elements:
- url - Required. The URL of the page you wish to render within the modal frame. Note that this feature is restricted by browser security contexts, so you can only open child pages from the same domain where the parent page is located.
- width and height - Optional. The size in pixels of the dialog.
- autoFit - Optional. Enabled by default. When the child page is fully loaded, the modal dialog is automatically resized to avoid scrollbars.
- autoResize - Optional. Disabled by default. This option activates an onResize handler that will automatically resize and center the modal frame whenever the browser window is resized. Note though, that this feature may not work very well on some browsers.
- draggable - Optional. Enabled by default.
- onSubmit - Optional. A function that will be called when the dialog is closed by the server-side response to a form submit request. See modalframe_close_dialog($args).
There's also a close() method and a few others, but these are used internally. You don't need to care about them. Just open a modal dialog and everything should be fine as long as the server-side menu callback invokes the function modalframe_child_js() when generating pages for the modal dialog.

The package also contains an optional module that can be used as an example. It is also recommended to check out the inline code documentation as it has a lot of information on how it all works.

Note for those interested in Drupal 7 support for this module: It seems this feature is being included in Drupal core itself. So, probably there will be no stable release of this module for Drupal 7 because it will be already there. :-D See: #517688: Initial D7UX admin overlay.

This module has been sponsored by Gamefilia.