Newer
Older
<?php
// $Id$
/**
* @file
* Utilize the CTools AJAX responder.
*
* The AJAX responder is a javascript tool to make it very easy to do complicated
* operations as a response to AJAX requests. When links are attached to the ajax
* responder, the server sends back a packet of JSON data; this packet is an
* array of commands to carry out.
*
* The command names correlate to functions in the responder space, making it
* relatively easy for applications to provide their own commands to do whatever
* spiffy functionality is necessary.
*
* Each command is an object. $object->command is the type of command and
* will be used to find the function (it will correllate directly to
* a function in the Drupal.CTools.AJAX.Command space). The object can
* contain any other data that the command needs to process.
*
* Built in commands include:
* - replace
* - selector: The CSS selector. This can be any selector jquery uses in $().
* - data: The data to use with the jquery replace() function.
*
* - append
* - selector: The CSS selector. This can be any selector jquery uses in $().
* - data: The data to use with the jquery append() function.
*
* - changed
* - selector: The CSS selector. This selector will have 'changed' added as a clas.
* - star: If set, will add a star to this selector. It must be within the 'selector' above.
*
* - alert
* - title: The title of the alert.
* - data: The data in the alert.
*
* Commands are usually created with a couple of helper functions, so they
* look like this:
*
* $commands = array();
* $commands[] = ctools_ajax_command_replace('#ctools-object-1', 'some html here');
* $commands[] = ctools_ajax_command_changed('#ctools-object-1');
* ctools_ajax_render($commands); // this function exits.
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
*/
/**
* Render an image as a button link. This will automatically apply an AJAX class
* to the link and add the appropriate javascript to make this happen.
*
* @param $image
* The path to an image to use that will be sent to theme('image') for rendering.
* @param $dest
* The destination of the link.
* @param $alt
* The alt text of the link.
* @param $class
* Any class to apply to the link. @todo this should be a options array.
*/
function ctools_ajax_image_button($image, $dest, $alt, $class = '') {
return ctools_ajax_text_button(theme('image', $image), $dest, $alt, $class);
}
/**
* Render text as a link. This will automatically apply an AJAX class
* to the link and add the appropriate javascript to make this happen.
*
* Note: 'html' => true so be sure any text is vetted! Chances are these kinds of buttons will
* not use user input so this is a very minor concern.
*
* @param $image
* The path to an image to use that will be sent to theme('image') for rendering.
* @param $dest
* The destination of the link.
* @param $alt
* The alt text of the link.
* @param $class
* Any class to apply to the link. @todo this should be a options array.
* @param $type
* A type to use, in case a different behavior should be attached. Defaults
* to ctools-use-ajax.
*/
function ctools_ajax_text_button($text, $dest, $alt, $class = '', $type = 'ctools-use-ajax') {
return l($text, $dest, array('html' => TRUE, 'attributes' => array('class' => "$type $class", 'title' => $alt, 'alt' => $alt)));
}
/**
* Create a command array for the error case.
*/
function ctools_ajax_command_error($error = '') {
return array(
'command' => 'alert',
'title' => t('Error'),
'text' => $error ? $error : t('Server reports invalid input error.'),
);
}
/**
* Create a replace command for the AJAX responder.
*
* The replace command will replace a portion of the current document
* with the specified HTML.
*
* @param $selector
* The CSS selector. This can be any selector jquery uses in $().
* @param $html
* The data to use with the jquery replace() function.
*/
function ctools_ajax_command_replace($selector, $html) {
return array(
'command' => 'replace',
'selector' => $selector,
'data' => $html,
);
}
/**
* Create an append command for the AJAX responder.
*
* This will append the HTML to the specified selector.
*
* @param $selector
* The CSS selector. This can be any selector jquery uses in $().
* @param $html
* The data to use with the jquery append() function.
*/
function ctools_ajax_command_append($selector, $html) {
return array(
'command' => 'append',
'selector' => $selector,
'data' => $html,
);
}
/**
* Create a changed command for the AJAX responder.
*
* This will mark an item as 'changed'.
*
* @param $selector
* The CSS selector. This can be any selector jquery uses in $().
* @param $star
* An optional CSS selector which must be inside $selector. If specified,
* a star will be appended.
*/
function ctools_ajax_command_changed($selector, $star = '') {
return array(
'command' => 'changed',
'selector' => $selector,
'star' => $star,
);
}
/**
* Force a table to be restriped.
*
* This is usually used after a table has been modifed by a replace or append
* command.
*
* @param $selector
* The CSS selector. This can be any selector jquery uses in $().
*/
function ctools_ajax_command_restripe($selector) {
return array(
'command' => 'restripe',
'selector' => $selector,
);
}
/**
* Render a commands array into JSON and immediately hand this back
* to the AJAX requester.
*/
function ctools_ajax_render($commands = array()) {
drupal_json($commands);
exit;
}
/**
* Send an error response back via AJAX and immediately exit.
*/
function ctools_ajax_render_error($error = '') {
$commands = array();
$commands[] = ctools_ajax_command_error($error);
ctools_ajax_render($commands);
}