Mercurial > defr > drupal > popups

comparison README.txt @ 0:76f9b43738f2

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