Modal Frame API

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 (version 1.7.x). Note that 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). See reference: #669436: In search for alternatives to the unload event.

Builtin support for: Dirty Forms.

Modules using Modal Frame API: Modal Frame Contrib Package (includes mini-modules that implement the Modal Frame API to enhance the usability of a few day to day tasks in every Drupal site), Node Relationships, Modal Frame CCK Editor, 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. This option activates an onResize handler that will automatically resize and center the modal frame whenever the browser window is resized or when the child document is fully loaded.
  • draggable - Optional. Enabled by default.
  • onOpen - Optional. This is a callback to invoke when the modal frame is opened.
  • onLoad - Optional. This is a callback to invoke when the the child document in the modal frame is fully loaded.
  • 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).
  • customDialogOptions - Optional. An object with custom jQuery UI Dialog options.
• 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.

Known issues

• It seems like the draggable component in jQuery UI 1.6 fails in Safari. See #692324: Draggable doesn't work in Safari
  Recommened action: upgrade to jQuery 1.3.2 and jQuery UI 1.7.x (see requirements section above).

How can you get involved?

• Write a review for this module on drupalmodules.com
• Help translate this module at localize.drupal.org

This module has been sponsored by Gamefilia.