franck@0:   This module gives Drupal the ability to easily change links into popup dialog boxes.
franck@0: 
franck@0:   IMPORTANT INSTRUCTIONS
franck@0:   ------------------------------------------------------------------------------------
franck@0:   Ajax updating only works with themes that have selectable content areas. 
franck@0:   If you are not using garland, you will need to figure out the selector for your theme, 
franck@0:   and enter it into the "Content Selector" field on the admin/build/themes/settings page
franck@0:   for your theme. Open the page.tpl.php file for your theme, and search for "print $content".
franck@0:   The $content should be surrounded by a div with an id. Ex:
franck@0:     <div id="content-content">
franck@0:       <?php print $content; ?>
franck@0:     </div> <!-- /content-content -->
franck@0:   In this case, just enter '#content-content' into the Content Selector field.
franck@0:   Unfortunately, a lot of themes do not have well defined content areas.  Just add the div yourself,
franck@0:   and then complain on the issue queue for the theme.  It is important that there are no other
franck@0:   print statements inside the div.
franck@0: 
franck@0:   LIMITATIONS
franck@0:   ------------------------------------------------------------------------------------  
franck@1:   Does not work with tinymce. Unlikely to work with other WYSIWYG's. (Is this still true?)
franck@1:   Conflicts with: 
franck@1:     Devel Theme Developer module.
franck@0: 
franck@0:   HOW TO USE THE POPUPS API
franck@0:   ------------------------------------------------------------------------------------  
franck@0:   If you just want to use the built in admin links, just enable the Popups: Admin Links
franck@0:   module and you are good to go.
franck@0:   If you want to add popups behavior to new links, or incorporate popups into your module,
franck@0:   there are a couple of ways to do it.
franck@0:   
franck@0:   #1) Attach popup behavior to a link with popups_add_popups() call.
franck@0:   ----------------------------------------------------------------  
franck@0:   <!-- In html or theme -->
franck@0:   <a href="popups/test/response" id="mylink"> 
franck@0:   <a href="popups/test/response" id="mylink2"> 
franck@0:   
franck@0:   // In your module
franck@0:   popups_add_popups(array('#mylink', '#mylink2=>array('width'=>'200px')));  
franck@0:   This is the simplest method if you want to pass in per-link options.
franck@0:   The first key is a jQuery selector. It should select an 'a' element (unless you 
franck@0:   are using the 'href' option). See http://docs.jquery.com/Selectors to learn more 
franck@0:   about jQuery selectors.
franck@0:   The array is a set of Options. See below for the list of options.
franck@0:   No array means just use the defualts. 
franck@0:   
franck@0:   #2) Add the class="popup" to an existing link.
franck@0:   -------------------------------------------
franck@0:   And then either be sure popups_add_popups() is called sometime for the page,
franck@0:   or use the "Scan all pages for popup links" checkbox on the popups settings page. 
franck@0:   
franck@0:   Example on the theme level ("Scan all pages for popups links" must be checked):
franck@0:     <a href="popups/test/response" class="popups">
franck@0: 
franck@0:   Example in code:
franck@0:     popups_add_popups();
franck@0:     $output .= l("Pop up entire local page.", 'popups/test/response', array('attributes'=>array('class' => 'popups')));
franck@0:   
franck@0:   Here are the classes that you can use:
franck@0:   class="popups" requests an informational popup (or a form that doesn't want ajax processing).
franck@0:   class="popups-form" requests a popup with a form that modifies the content of the original page.
franck@0:   class="popups-form-reload" requests a popup with a form, and reloads the entire page when done.
franck@0:   class="popups-form-noupdate" requests a popup with a form, and leaves the original page as-is.
franck@0:   
franck@0:   You can use the pseudo-attribute, "on-popups-options" to send options, if you don't mind having non-validating HTML.
franck@0:   Note: this attribute gets removed from user content by the HTML filter.
franck@0:   Example:
franck@0:     print l("Pop with options (width=200px).", 'popups/test/response', 
franck@0:              array('attributes'=>array(array('class' => 'popups', 'on-popups-options' => '{width: "200px"}'))))
franck@0:   See popups_test.module for more examples.    
franck@0:   
franck@0:   #3) Add a custom module that implements hook_popups().
franck@0:   ---------------------------------------------------------------------
franck@0:   hook_popups() returns an array of popup rules, keyed by the id of a form, 
franck@0:   or the url of a page (which can use the wildcard '*').
franck@0:   Each rule is an array of options, keyed by a jQuery selector.  
franck@0:   Leaving off the options array is equal to a link with class="popup-form".
franck@0:   This is equivent to using a series of popup_add_popups() calls.
franck@0:   
franck@0:   Rule Format Example:
franck@0:     'admin/content/taxonomy' => array( // Act only on the links on this page. 
franck@0:       'div#tabs-wrapper a:eq(1)',  // No options, so use defaults.
franck@0:       'table td:nth-child(2) a' => array( 
franck@0:         'noUpdate' => true, // Popup will not modify original page.
franck@0:       ),
franck@0:     );
franck@0:   
franck@0:   #4) Make your module alter the default popup rules with hook_popups_alter().
franck@0:   ----------------------------------------------------------------------------
franck@0:   hook_popups_alter() allows you to modify how the popup rules are
franck@0:   registered. This is useful to modify the default behavior of some
franck@0:   already existing popup rules.
franck@0: 
franck@0:   See hook_popups_alter() in popups.api.php for an example.
franck@0: 
franck@0: 
franck@0:   LIST OF POPUP OPITIONS
franck@0:   ------------------------------------------------------------------------------------ 
franck@0:   DEPRECATED OPTIONS
franck@0: //   noUpdate: Does the popup NOT modify the original page (Default: FALSE).
franck@0: //   reloadWhenDone: Force the entire page to reload after the popup form is submitted (Default: FALSE)
franck@0: //   nonModel: Not working.
franck@0: //   forceReturn: url to force a stop to work flow (Advanced. Use in conjunction with noUpdate or targetSelectors).  
franck@0: //   afterSubmit: function to call when updating after successful form submission.   
franck@0:    
franck@0:    doneTest: how do we know when the multiform flow is done?
franck@0:      null: flow is done when returned path = original path (default).
franck@0:      *path*: 
franck@0:      *regexp*: done when returned path matches regexp.
franck@0:    updateMethod:
franck@0:      none: do not update the initial page 
franck@0:      ajax: targeted replacement of parts of the initial page (default).
franck@0:      reload: full replacement of initial page with new page.
franck@0:      callback: use onUpdate(data, options, element).
franck@0:    updateSource (only used if updateMethod is not none):
franck@0:      initial: use the initial page (default).
franck@0:      final: use the path returned at the end of the multiform flow.
franck@0:    href: Override the href in the a element, or attach an href to a non-link element.
franck@0:    width: Override the width specified in the css.
franck@0:    targetSelectors: Hash of jQuery selectors that define the content to be swapped out.
franck@0:    titleSelectors: Array of jQuery selectors to place the new page title.
franck@0:    reloadOnError: Force the entire page to reload if the popup href is unaccessable (Default: FALSE)
franck@0:    noMessage: Don't show drupal_set_message messages.
franck@0:    onUpdate: function to call when updating after successful form submission.   
franck@0:    skipDirtyCheck: If true, this popup will not check for edits on the originating page.  
franck@0:                    Often used with custom target selectors. Redundant is noUpdate is true. (Default: FALSE)
franck@0:    hijackDestination: Use the destiination param to force a form submit to return to the originating page.
franck@0:                       Overwrites any destination already set one the link (Default: TRUE)
franck@0:    
franck@0: