|
franck@0
|
1 This module gives Drupal the ability to easily change links into popup dialog boxes.
|
|
franck@0
|
2
|
|
franck@0
|
3 IMPORTANT INSTRUCTIONS
|
|
franck@0
|
4 ------------------------------------------------------------------------------------
|
|
franck@0
|
5 Ajax updating only works with themes that have selectable content areas.
|
|
franck@0
|
6 If you are not using garland, you will need to figure out the selector for your theme,
|
|
franck@0
|
7 and enter it into the "Content Selector" field on the admin/build/themes/settings page
|
|
franck@0
|
8 for your theme. Open the page.tpl.php file for your theme, and search for "print $content".
|
|
franck@0
|
9 The $content should be surrounded by a div with an id. Ex:
|
|
franck@0
|
10 <div id="content-content">
|
|
franck@0
|
11 <?php print $content; ?>
|
|
franck@0
|
12 </div> <!-- /content-content -->
|
|
franck@0
|
13 In this case, just enter '#content-content' into the Content Selector field.
|
|
franck@0
|
14 Unfortunately, a lot of themes do not have well defined content areas. Just add the div yourself,
|
|
franck@0
|
15 and then complain on the issue queue for the theme. It is important that there are no other
|
|
franck@0
|
16 print statements inside the div.
|
|
franck@0
|
17
|
|
franck@0
|
18 LIMITATIONS
|
|
franck@0
|
19 ------------------------------------------------------------------------------------
|
|
franck@1
|
20 Does not work with tinymce. Unlikely to work with other WYSIWYG's. (Is this still true?)
|
|
franck@1
|
21 Conflicts with:
|
|
franck@1
|
22 Devel Theme Developer module.
|
|
franck@0
|
23
|
|
franck@0
|
24 HOW TO USE THE POPUPS API
|
|
franck@0
|
25 ------------------------------------------------------------------------------------
|
|
franck@0
|
26 If you just want to use the built in admin links, just enable the Popups: Admin Links
|
|
franck@0
|
27 module and you are good to go.
|
|
franck@0
|
28 If you want to add popups behavior to new links, or incorporate popups into your module,
|
|
franck@0
|
29 there are a couple of ways to do it.
|
|
franck@0
|
30
|
|
franck@0
|
31 #1) Attach popup behavior to a link with popups_add_popups() call.
|
|
franck@0
|
32 ----------------------------------------------------------------
|
|
franck@0
|
33 <!-- In html or theme -->
|
|
franck@0
|
34 <a href="popups/test/response" id="mylink">
|
|
franck@0
|
35 <a href="popups/test/response" id="mylink2">
|
|
franck@0
|
36
|
|
franck@0
|
37 // In your module
|
|
franck@0
|
38 popups_add_popups(array('#mylink', '#mylink2=>array('width'=>'200px')));
|
|
franck@0
|
39 This is the simplest method if you want to pass in per-link options.
|
|
franck@0
|
40 The first key is a jQuery selector. It should select an 'a' element (unless you
|
|
franck@0
|
41 are using the 'href' option). See http://docs.jquery.com/Selectors to learn more
|
|
franck@0
|
42 about jQuery selectors.
|
|
franck@0
|
43 The array is a set of Options. See below for the list of options.
|
|
franck@0
|
44 No array means just use the defualts.
|
|
franck@0
|
45
|
|
franck@0
|
46 #2) Add the class="popup" to an existing link.
|
|
franck@0
|
47 -------------------------------------------
|
|
franck@0
|
48 And then either be sure popups_add_popups() is called sometime for the page,
|
|
franck@0
|
49 or use the "Scan all pages for popup links" checkbox on the popups settings page.
|
|
franck@0
|
50
|
|
franck@0
|
51 Example on the theme level ("Scan all pages for popups links" must be checked):
|
|
franck@0
|
52 <a href="popups/test/response" class="popups">
|
|
franck@0
|
53
|
|
franck@0
|
54 Example in code:
|
|
franck@0
|
55 popups_add_popups();
|
|
franck@0
|
56 $output .= l("Pop up entire local page.", 'popups/test/response', array('attributes'=>array('class' => 'popups')));
|
|
franck@0
|
57
|
|
franck@0
|
58 Here are the classes that you can use:
|
|
franck@0
|
59 class="popups" requests an informational popup (or a form that doesn't want ajax processing).
|
|
franck@0
|
60 class="popups-form" requests a popup with a form that modifies the content of the original page.
|
|
franck@0
|
61 class="popups-form-reload" requests a popup with a form, and reloads the entire page when done.
|
|
franck@0
|
62 class="popups-form-noupdate" requests a popup with a form, and leaves the original page as-is.
|
|
franck@0
|
63
|
|
franck@0
|
64 You can use the pseudo-attribute, "on-popups-options" to send options, if you don't mind having non-validating HTML.
|
|
franck@0
|
65 Note: this attribute gets removed from user content by the HTML filter.
|
|
franck@0
|
66 Example:
|
|
franck@0
|
67 print l("Pop with options (width=200px).", 'popups/test/response',
|
|
franck@0
|
68 array('attributes'=>array(array('class' => 'popups', 'on-popups-options' => '{width: "200px"}'))))
|
|
franck@0
|
69 See popups_test.module for more examples.
|
|
franck@0
|
70
|
|
franck@0
|
71 #3) Add a custom module that implements hook_popups().
|
|
franck@0
|
72 ---------------------------------------------------------------------
|
|
franck@0
|
73 hook_popups() returns an array of popup rules, keyed by the id of a form,
|
|
franck@0
|
74 or the url of a page (which can use the wildcard '*').
|
|
franck@0
|
75 Each rule is an array of options, keyed by a jQuery selector.
|
|
franck@0
|
76 Leaving off the options array is equal to a link with class="popup-form".
|
|
franck@0
|
77 This is equivent to using a series of popup_add_popups() calls.
|
|
franck@0
|
78
|
|
franck@0
|
79 Rule Format Example:
|
|
franck@0
|
80 'admin/content/taxonomy' => array( // Act only on the links on this page.
|
|
franck@0
|
81 'div#tabs-wrapper a:eq(1)', // No options, so use defaults.
|
|
franck@0
|
82 'table td:nth-child(2) a' => array(
|
|
franck@0
|
83 'noUpdate' => true, // Popup will not modify original page.
|
|
franck@0
|
84 ),
|
|
franck@0
|
85 );
|
|
franck@0
|
86
|
|
franck@0
|
87 #4) Make your module alter the default popup rules with hook_popups_alter().
|
|
franck@0
|
88 ----------------------------------------------------------------------------
|
|
franck@0
|
89 hook_popups_alter() allows you to modify how the popup rules are
|
|
franck@0
|
90 registered. This is useful to modify the default behavior of some
|
|
franck@0
|
91 already existing popup rules.
|
|
franck@0
|
92
|
|
franck@0
|
93 See hook_popups_alter() in popups.api.php for an example.
|
|
franck@0
|
94
|
|
franck@0
|
95
|
|
franck@0
|
96 LIST OF POPUP OPITIONS
|
|
franck@0
|
97 ------------------------------------------------------------------------------------
|
|
franck@0
|
98 DEPRECATED OPTIONS
|
|
franck@0
|
99 // noUpdate: Does the popup NOT modify the original page (Default: FALSE).
|
|
franck@0
|
100 // reloadWhenDone: Force the entire page to reload after the popup form is submitted (Default: FALSE)
|
|
franck@0
|
101 // nonModel: Not working.
|
|
franck@0
|
102 // forceReturn: url to force a stop to work flow (Advanced. Use in conjunction with noUpdate or targetSelectors).
|
|
franck@0
|
103 // afterSubmit: function to call when updating after successful form submission.
|
|
franck@0
|
104
|
|
franck@0
|
105 doneTest: how do we know when the multiform flow is done?
|
|
franck@0
|
106 null: flow is done when returned path = original path (default).
|
|
franck@0
|
107 *path*:
|
|
franck@0
|
108 *regexp*: done when returned path matches regexp.
|
|
franck@0
|
109 updateMethod:
|
|
franck@0
|
110 none: do not update the initial page
|
|
franck@0
|
111 ajax: targeted replacement of parts of the initial page (default).
|
|
franck@0
|
112 reload: full replacement of initial page with new page.
|
|
franck@0
|
113 callback: use onUpdate(data, options, element).
|
|
franck@0
|
114 updateSource (only used if updateMethod is not none):
|
|
franck@0
|
115 initial: use the initial page (default).
|
|
franck@0
|
116 final: use the path returned at the end of the multiform flow.
|
|
franck@0
|
117 href: Override the href in the a element, or attach an href to a non-link element.
|
|
franck@0
|
118 width: Override the width specified in the css.
|
|
franck@0
|
119 targetSelectors: Hash of jQuery selectors that define the content to be swapped out.
|
|
franck@0
|
120 titleSelectors: Array of jQuery selectors to place the new page title.
|
|
franck@0
|
121 reloadOnError: Force the entire page to reload if the popup href is unaccessable (Default: FALSE)
|
|
franck@0
|
122 noMessage: Don't show drupal_set_message messages.
|
|
franck@0
|
123 onUpdate: function to call when updating after successful form submission.
|
|
franck@0
|
124 skipDirtyCheck: If true, this popup will not check for edits on the originating page.
|
|
franck@0
|
125 Often used with custom target selectors. Redundant is noUpdate is true. (Default: FALSE)
|
|
franck@0
|
126 hijackDestination: Use the destiination param to force a form submit to return to the originating page.
|
|
franck@0
|
127 Overwrites any destination already set one the link (Default: TRUE)
|
|
franck@0
|
128
|
|
franck@0
|
129 |
