You are here

README.txt in Modal Frame API 7

Same filename and directory in other branches
  1. 6 README.txt
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Modal Frame API module for Drupal 6
;;
;; Original author: markus_petrux (http://drupal.org/user/39593)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

CONTENTS OF THIS FILE
=====================
- OVERVIEW
- REQUIREMENTS
- INSTALLATION
- API REFERENCE


OVERVIEW
========

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) [1] 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.

[1] http://drupal.org/project/popups


REQUIREMENTS
============

- jQuery UI module (with jQuery UI library 1.7.x).
  http://drupal.org/project/jquery_ui

  * Note that you also need jQuery 1.3.x, currently provided by the jQuery
    Update module 6.x-2.x. See http://drupal.org/project/jquery_update

- The onBeforeUnload API is not required but recommended. It enhances
  synchronization of parent/child windows.

  http://drupal.org/project/onbeforeunload

- The Dirty Forms module is not required, but supported. It warns users
  if they are about to close a modal dialog with unsaved changes.

  http://drupal.org/project/dirtyforms


INSTALLATION
============

- Be sure to install all dependent modules.

- Copy all contents of this package to your modules directory preserving
  subdirectory structure.

- Go to Administer -> Site building -> Modules to install module.

- Done.


API REFERENCE
=============

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 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:

  o 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.

  o width and height (Optional)

    The size in pixels of the dialog.

  o 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.

  o draggable (Optional)

    This option is enabled by default. Use false to disable.

  o onOpen (Optional)

    This is a callback to invoke when the modal frame is opened.

  o onLoad (Optional)

    This is a callback to invoke when the the child document in the modal frame
    is fully loaded.

  o 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).

  o 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.

File

README.txt
View source
  1. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2. ;; Modal Frame API module for Drupal 6
  3. ;;
  4. ;; Original author: markus_petrux (http://drupal.org/user/39593)
  5. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  6. CONTENTS OF THIS FILE
  7. =====================
  8. - OVERVIEW
  9. - REQUIREMENTS
  10. - INSTALLATION
  11. - API REFERENCE
  12. OVERVIEW
  13. ========
  14. This module provides an API to render an iframe within a modal dialog based on
  15. the jQuery UI Dialog plugin. You should not install this module unless another
  16. module requires you to, or you wish to use it for your own custom modules.
  17. It is an alternative to Popups API (Ajax Dialogs) [1] which implements its own
  18. library and API to manage popup dialogs. On the other hand, the Modal Frame API
  19. is based on the jQuery UI Dialog plugin and it is specially built to deal with
  20. iframe elements with very little effort (and no particular AJAX requirements).
  21. For themers, this module provides a default template for rendering child pages
  22. within modal frames (modalframe-page.tpl.php) that can be copied to the theme
  23. directory and customized to suit the particular needs of the site. It is also
  24. pretty easy to adapt the provided stylesheets to match the look of the site.
  25. [1] http://drupal.org/project/popups
  26. REQUIREMENTS
  27. ============
  28. - jQuery UI module (with jQuery UI library 1.7.x).
  29. http://drupal.org/project/jquery_ui
  30. * Note that you also need jQuery 1.3.x, currently provided by the jQuery
  31. Update module 6.x-2.x. See http://drupal.org/project/jquery_update
  32. - The onBeforeUnload API is not required but recommended. It enhances
  33. synchronization of parent/child windows.
  34. http://drupal.org/project/onbeforeunload
  35. - The Dirty Forms module is not required, but supported. It warns users
  36. if they are about to close a modal dialog with unsaved changes.
  37. http://drupal.org/project/dirtyforms
  38. INSTALLATION
  39. ============
  40. - Be sure to install all dependent modules.
  41. - Copy all contents of this package to your modules directory preserving
  42. subdirectory structure.
  43. - Go to Administer -> Site building -> Modules to install module.
  44. - Done.
  45. API REFERENCE
  46. =============
  47. Modal Frame API is pretty simple, but powerful at the same time.
  48. The server-side API looks as follows:
  49. * modalframe_parent_js()
  50. Adds the Modal Frame javascript and stylesheets to the parent page. You
  51. should use this when you wish to use the client-side API to manage frames
  52. within a modal dialog.
  53. * modalframe_child_js()
  54. Adds the Modal Frame javascript and stylesheets to the child page. This is
  55. necessary for pages and/or forms that are rendered within a modal frame.
  56. * modalframe_close_dialog($args)
  57. When a form is rendered within a modal frame (what we would call the child
  58. window), you can use this function from your form submit handler to close
  59. the client-side dialog. You can also give it arguments that will be passed
  60. to an optional onSubmit callback that you can provide when opening the modal
  61. frame from the parent window.
  62. The client-side API looks as follows:
  63. * Drupal.modalFrame.open(options)
  64. Use this method to open a modal frame. The argument is a javascript object
  65. that may contain the following elements:
  66. o url (Required)
  67. The URL of the page you wish to render within the modal frame. Note that
  68. this feature is restricted by browser security contexts, so you can only
  69. open child pages from the same domain where the parent page is located.
  70. o width and height (Optional)
  71. The size in pixels of the dialog.
  72. o autoFit (Optional, enabled by default)
  73. This option activates an onResize handler that will automatically resize
  74. and center the modal frame whenever the browser window is resized or when
  75. the child document is fully loaded.
  76. o draggable (Optional)
  77. This option is enabled by default. Use false to disable.
  78. o onOpen (Optional)
  79. This is a callback to invoke when the modal frame is opened.
  80. o onLoad (Optional)
  81. This is a callback to invoke when the the child document in the modal frame
  82. is fully loaded.
  83. o onSubmit (Optional)
  84. A function that will be called when the dialog is closed by the server-side
  85. response to a form submit request. See modalframe_close_dialog($args).
  86. o customDialogOptions (Optional)
  87. An object with custom jQuery UI Dialog options.
  88. * There's also a close() method and a few others, but these are used internally.
  89. You don't need to care about them. Just open a modal dialog and everything
  90. should be fine as long as the server-side menu callback invokes the function
  91. modalframe_child_js() when generating pages for the modal dialog.
  92. The package also contains an optional module that can be used as an example. It
  93. is also recommended to check out the inline code documentation as it has a lot
  94. of information on how it all works.