accueil: correction d'un lien (pour Gustavo)
[aidenligne_francais_universite.git] / ajax / xajaxResponse.inc.php
CommitLineData
c495c100
P
1<?php
2/**
3 * xajaxResponse.inc.php :: xajax XML response class
4 *
5 * xajax version 0.2.4
6 * copyright (c) 2005 by Jared White & J. Max Wilson
7 * http://www.xajaxproject.org
8 *
9 * xajax is an open source PHP class library for easily creating powerful
10 * PHP-driven, web-based Ajax Applications. Using xajax, you can asynchronously
11 * call PHP functions and update the content of your your webpage without
12 * reloading the page.
13 *
14 * xajax is released under the terms of the LGPL license
15 * http://www.gnu.org/copyleft/lesser.html#SEC3
16 *
17 * This library is free software; you can redistribute it and/or
18 * modify it under the terms of the GNU Lesser General Public
19 * License as published by the Free Software Foundation; either
20 * version 2.1 of the License, or (at your option) any later version.
21 *
22 * This library is distributed in the hope that it will be useful,
23 * but WITHOUT ANY WARRANTY; without even the implied warranty of
24 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
25 * Lesser General Public License for more details.
26 *
27 * You should have received a copy of the GNU Lesser General Public
28 * License along with this library; if not, write to the Free Software
29 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
30 *
31 * @package xajax
32 * @version $Id$
33 * @copyright Copyright (c) 2005-2006 by Jared White & J. Max Wilson
34 * @license http://www.gnu.org/copyleft/lesser.html#SEC3 LGPL License
35 */
36
37/*
38 ----------------------------------------------------------------------------
39 | Online documentation for this class is available on the xajax wiki at: |
40 | http://wiki.xajaxproject.org/Documentation:xajaxResponse.inc.php |
41 ----------------------------------------------------------------------------
42*/
43
44/**
45 * The xajaxResponse class is used to create responses to be sent back to your
46 * Web page. A response contains one or more command messages for updating
47 * your page.
48 * Currently xajax supports 21 kinds of command messages, including some common
49 * ones such as:
50 * <ul>
51 * <li>Assign - sets the specified attribute of an element in your page</li>
52 * <li>Append - appends data to the end of the specified attribute of an
53 * element in your page</li>
54 * <li>Prepend - prepends data to the beginning of the specified attribute of
55 * an element in your page</li>
56 * <li>Replace - searches for and replaces data in the specified attribute of
57 * an element in your page</li>
58 * <li>Script - runs the supplied JavaScript code</li>
59 * <li>Alert - shows an alert box with the supplied message text</li>
60 * </ul>
61 *
62 * <i>Note:</i> elements are identified by their HTML id, so if you don't see
63 * your browser HTML display changing from the request, make sure you're using
64 * the right id names in your response.
65 *
66 * @package xajax
67 */
68class xajaxResponse
69{
70 /**#@+
71 * @access protected
72 */
73 /**
74 * @var string internal XML storage
75 */
76 var $xml;
77 /**
78 * @var string the encoding type to use
79 */
80 var $sEncoding;
81 /**
82 * @var boolean if special characters in the XML should be converted to
83 * entities
84 */
85 var $bOutputEntities;
86
87 /**#@-*/
88
89 /**
90 * The constructor's main job is to set the character encoding for the
91 * response.
92 *
93 * <i>Note:</i> to change the character encoding for all of the
94 * responses, set the XAJAX_DEFAULT_ENCODING constant before you
95 * instantiate xajax.
96 *
97 * @param string contains the character encoding string to use
98 * @param boolean lets you set if you want special characters in the output
99 * converted to HTML entities
100 *
101 */
102 function xajaxResponse($sEncoding=XAJAX_DEFAULT_CHAR_ENCODING, $bOutputEntities=false)
103 {
104 $this->setCharEncoding($sEncoding);
105 $this->bOutputEntities = $bOutputEntities;
106 }
107
108 /**
109 * Sets the character encoding for the response based on $sEncoding, which
110 * is a string containing the character encoding to use. You don't need to
111 * use this method normally, since the character encoding for the response
112 * gets set automatically based on the XAJAX_DEFAULT_CHAR_ENCODING
113 * constant.
114 *
115 * @param string
116 */
117 function setCharEncoding($sEncoding)
118 {
119 $this->sEncoding = $sEncoding;
120 }
121
122 /**
123 * Tells the response object to convert special characters to HTML entities
124 * automatically (only works if the mb_string extension is available).
125 */
126 function outputEntitiesOn()
127 {
128 $this->bOutputEntities = true;
129 }
130
131 /**
132 * Tells the response object to output special characters intact. (default
133 * behavior)
134 */
135 function outputEntitiesOff()
136 {
137 $this->bOutputEntities = false;
138 }
139
140 /**
141 * Adds a confirm commands command message to the XML response.
142 *
143 * <i>Usage:</i> <kbd>$objResponse->addConfirmCommands(1, "Do you want to preview the new data?");</kbd>
144 *
145 * @param integer the number of commands to skip if the user presses
146 * Cancel in the browsers's confirm dialog
147 * @param string the message to show in the browser's confirm dialog
148 */
149 function addConfirmCommands($iCmdNumber, $sMessage)
150 {
151 $this->xml .= $this->_cmdXML(array("n"=>"cc","t"=>$iCmdNumber),$sMessage);
152 }
153
154 /**
155 * Adds an assign command message to the XML response.
156 *
157 * <i>Usage:</i> <kbd>$objResponse->addAssign("contentDiv", "innerHTML", "Some Text");</kbd>
158 *
159 * @param string contains the id of an HTML element
160 * @param string the part of the element you wish to modify ("innerHTML",
161 * "value", etc.)
162 * @param string the data you want to set the attribute to
163 */
164 function addAssign($sTarget,$sAttribute,$sData)
165 {
166 $this->xml .= $this->_cmdXML(array("n"=>"as","t"=>$sTarget,"p"=>$sAttribute),$sData);
167 }
168
169 /**
170 * Adds an append command message to the XML response.
171 *
172 * <i>Usage:</i> <kbd>$objResponse->addAppend("contentDiv", "innerHTML", "Some New Text");</kbd>
173 *
174 * @param string contains the id of an HTML element
175 * @param string the part of the element you wish to modify ("innerHTML",
176 * "value", etc.)
177 * @param string the data you want to append to the end of the attribute
178 */
179 function addAppend($sTarget,$sAttribute,$sData)
180 {
181 $this->xml .= $this->_cmdXML(array("n"=>"ap","t"=>$sTarget,"p"=>$sAttribute),$sData);
182 }
183
184 /**
185 * Adds an prepend command message to the XML response.
186 *
187 * <i>Usage:</i> <kbd>$objResponse->addPrepend("contentDiv", "innerHTML", "Some Starting Text");</kbd>
188 *
189 * @param string contains the id of an HTML element
190 * @param string the part of the element you wish to modify ("innerHTML",
191 * "value", etc.)
192 * @param string the data you want to prepend to the beginning of the
193 * attribute
194 */
195 function addPrepend($sTarget,$sAttribute,$sData)
196 {
197 $this->xml .= $this->_cmdXML(array("n"=>"pp","t"=>$sTarget,"p"=>$sAttribute),$sData);
198 }
199
200 /**
201 * Adds a replace command message to the XML response.
202 *
203 * <i>Usage:</i> <kbd>$objResponse->addReplace("contentDiv", "innerHTML", "text", "<b>text</b>");</kbd>
204 *
205 * @param string contains the id of an HTML element
206 * @param string the part of the element you wish to modify ("innerHTML",
207 * "value", etc.)
208 * @param string the string to search for
209 * @param string the string to replace the search string when found in the
210 * attribute
211 */
212 function addReplace($sTarget,$sAttribute,$sSearch,$sData)
213 {
214 $sDta = "<s><![CDATA[$sSearch]]></s><r><![CDATA[$sData]]></r>";
215 $this->xml .= $this->_cmdXML(array("n"=>"rp","t"=>$sTarget,"p"=>$sAttribute),$sDta);
216 }
217
218 /**
219 * Adds a clear command message to the XML response.
220 *
221 * <i>Usage:</i> <kbd>$objResponse->addClear("contentDiv", "innerHTML");</kbd>
222 *
223 * @param string contains the id of an HTML element
224 * @param string the part of the element you wish to clear ("innerHTML",
225 * "value", etc.)
226 */
227 function addClear($sTarget,$sAttribute)
228 {
229 $this->addAssign($sTarget,$sAttribute,'');
230 }
231
232 /**
233 * Adds an alert command message to the XML response.
234 *
235 * <i>Usage:</i> <kbd>$objResponse->addAlert("This is important information");</kbd>
236 *
237 * @param string the text to be displayed in the Javascript alert box
238 */
239 function addAlert($sMsg)
240 {
241 $this->xml .= $this->_cmdXML(array("n"=>"al"),$sMsg);
242 }
243
244 /**
245 * Uses the addScript() method to add a Javascript redirect to another URL.
246 *
247 * <i>Usage:</i> <kbd>$objResponse->addRedirect("http://www.xajaxproject.org");</kbd>
248 *
249 * @param string the URL to redirect the client browser to
250 */
251 function addRedirect($sURL)
252 {
253 //we need to parse the query part so that the values are rawurlencode()'ed
254 //can't just use parse_url() cos we could be dealing with a relative URL which
255 // parse_url() can't deal with.
256 $queryStart = strpos($sURL, '?', strrpos($sURL, '/'));
257 if ($queryStart !== FALSE)
258 {
259 $queryStart++;
260 $queryEnd = strpos($sURL, '#', $queryStart);
261 if ($queryEnd === FALSE)
262 $queryEnd = strlen($sURL);
263 $queryPart = substr($sURL, $queryStart, $queryEnd-$queryStart);
264 parse_str($queryPart, $queryParts);
265 $newQueryPart = "";
266 foreach($queryParts as $key => $value)
267 {
268 $newQueryPart .= rawurlencode($key).'='.rawurlencode($value).ini_get('arg_separator.output');
269 }
270 $sURL = str_replace($queryPart, $newQueryPart, $sURL);
271 }
272 $this->addScript('window.location = "'.$sURL.'";');
273 }
274
275 /**
276 * Adds a Javascript command message to the XML response.
277 *
278 * <i>Usage:</i> <kbd>$objResponse->addScript("var x = prompt('get some text');");</kbd>
279 *
280 * @param string contains Javascript code to be executed
281 */
282 function addScript($sJS)
283 {
284 $this->xml .= $this->_cmdXML(array("n"=>"js"),$sJS);
285 }
286
287 /**
288 * Adds a Javascript function call command message to the XML response.
289 *
290 * <i>Usage:</i> <kbd>$objResponse->addScriptCall("myJSFunction", "arg 1", "arg 2", 12345);</kbd>
291 *
292 * @param string $sFunc the name of a Javascript function
293 * @param mixed $args,... optional arguments to pass to the Javascript function
294 */
295 function addScriptCall() {
296 $arguments = func_get_args();
297 $sFunc = array_shift($arguments);
298 $sData = $this->_buildObjXml($arguments);
299 $this->xml .= $this->_cmdXML(array("n"=>"jc","t"=>$sFunc),$sData);
300 }
301
302 /**
303 * Adds a remove element command message to the XML response.
304 *
305 * <i>Usage:</i> <kbd>$objResponse->addRemove("Div2");</kbd>
306 *
307 * @param string contains the id of an HTML element to be removed
308 */
309 function addRemove($sTarget)
310 {
311 $this->xml .= $this->_cmdXML(array("n"=>"rm","t"=>$sTarget),'');
312 }
313
314 /**
315 * Adds a create element command message to the XML response.
316 *
317 * <i>Usage:</i> <kbd>$objResponse->addCreate("parentDiv", "h3", "myid");</kbd>
318 *
319 * @param string contains the id of an HTML element to to which the new
320 * element will be appended.
321 * @param string the tag to be added
322 * @param string the id to be assigned to the new element
323 * @param string deprecated, use the addCreateInput() method instead
324 */
325 function addCreate($sParent, $sTag, $sId, $sType="")
326 {
327 if ($sType)
328 {
329 trigger_error("The \$sType parameter of addCreate has been deprecated. Use the addCreateInput() method instead.", E_USER_WARNING);
330 return;
331 }
332 $this->xml .= $this->_cmdXML(array("n"=>"ce","t"=>$sParent,"p"=>$sId),$sTag);
333 }
334
335 /**
336 * Adds a insert element command message to the XML response.
337 *
338 * <i>Usage:</i> <kbd>$objResponse->addInsert("childDiv", "h3", "myid");</kbd>
339 *
340 * @param string contains the id of the child before which the new element
341 * will be inserted
342 * @param string the tag to be added
343 * @param string the id to be assigned to the new element
344 */
345 function addInsert($sBefore, $sTag, $sId)
346 {
347 $this->xml .= $this->_cmdXML(array("n"=>"ie","t"=>$sBefore,"p"=>$sId),$sTag);
348 }
349
350 /**
351 * Adds a insert element command message to the XML response.
352 *
353 * <i>Usage:</i> <kbd>$objResponse->addInsertAfter("childDiv", "h3", "myid");</kbd>
354 *
355 * @param string contains the id of the child after which the new element
356 * will be inserted
357 * @param string the tag to be added
358 * @param string the id to be assigned to the new element
359 */
360 function addInsertAfter($sAfter, $sTag, $sId)
361 {
362 $this->xml .= $this->_cmdXML(array("n"=>"ia","t"=>$sAfter,"p"=>$sId),$sTag);
363 }
364
365 /**
366 * Adds a create input command message to the XML response.
367 *
368 * <i>Usage:</i> <kbd>$objResponse->addCreateInput("form1", "text", "username", "input1");</kbd>
369 *
370 * @param string contains the id of an HTML element to which the new input
371 * will be appended
372 * @param string the type of input to be created (text, radio, checkbox,
373 * etc.)
374 * @param string the name to be assigned to the new input and the variable
375 * name when it is submitted
376 * @param string the id to be assigned to the new input
377 */
378 function addCreateInput($sParent, $sType, $sName, $sId)
379 {
380 $this->xml .= $this->_cmdXML(array("n"=>"ci","t"=>$sParent,"p"=>$sId,"c"=>$sType),$sName);
381 }
382
383 /**
384 * Adds an insert input command message to the XML response.
385 *
386 * <i>Usage:</i> <kbd>$objResponse->addInsertInput("input5", "text", "username", "input1");</kbd>
387 *
388 * @param string contains the id of the child before which the new element
389 * will be inserted
390 * @param string the type of input to be created (text, radio, checkbox,
391 * etc.)
392 * @param string the name to be assigned to the new input and the variable
393 * name when it is submitted
394 * @param string the id to be assigned to the new input
395 */
396 function addInsertInput($sBefore, $sType, $sName, $sId)
397 {
398 $this->xml .= $this->_cmdXML(array("n"=>"ii","t"=>$sBefore,"p"=>$sId,"c"=>$sType),$sName);
399 }
400
401 /**
402 * Adds an insert input command message to the XML response.
403 *
404 * <i>Usage:</i> <kbd>$objResponse->addInsertInputAfter("input7", "text", "email", "input2");</kbd>
405 *
406 * @param string contains the id of the child after which the new element
407 * will be inserted
408 * @param string the type of input to be created (text, radio, checkbox,
409 * etc.)
410 * @param string the name to be assigned to the new input and the variable
411 * name when it is submitted
412 * @param string the id to be assigned to the new input
413 */
414 function addInsertInputAfter($sAfter, $sType, $sName, $sId)
415 {
416 $this->xml .= $this->_cmdXML(array("n"=>"iia","t"=>$sAfter,"p"=>$sId,"c"=>$sType),$sName);
417 }
418
419 /**
420 * Adds an event command message to the XML response.
421 *
422 * <i>Usage:</i> <kbd>$objResponse->addEvent("contentDiv", "onclick", "alert(\'Hello World\');");</kbd>
423 *
424 * @param string contains the id of an HTML element
425 * @param string the event you wish to set ("onclick", "onmouseover", etc.)
426 * @param string the Javascript string you want the event to invoke
427 */
428 function addEvent($sTarget,$sEvent,$sScript)
429 {
430 $this->xml .= $this->_cmdXML(array("n"=>"ev","t"=>$sTarget,"p"=>$sEvent),$sScript);
431 }
432
433 /**
434 * Adds a handler command message to the XML response.
435 *
436 * <i>Usage:</i> <kbd>$objResponse->addHandler("contentDiv", "onclick", "content_click");</kbd>
437 *
438 * @param string contains the id of an HTML element
439 * @param string the event you wish to set ("onclick", "onmouseover", etc.)
440 * @param string the name of a Javascript function that will handle the
441 * event. Multiple handlers can be added for the same event
442 */
443 function addHandler($sTarget,$sEvent,$sHandler)
444 {
445 $this->xml .= $this->_cmdXML(array("n"=>"ah","t"=>$sTarget,"p"=>$sEvent),$sHandler);
446 }
447
448 /**
449 * Adds a remove handler command message to the XML response.
450 *
451 * <i>Usage:</i> <kbd>$objResponse->addRemoveHandler("contentDiv", "onclick", "content_click");</kbd>
452 *
453 * @param string contains the id of an HTML element
454 * @param string the event you wish to remove ("onclick", "onmouseover",
455 * etc.)
456 * @param string the name of a Javascript handler function that you want to
457 * remove
458 */
459 function addRemoveHandler($sTarget,$sEvent,$sHandler)
460 {
461 $this->xml .= $this->_cmdXML(array("n"=>"rh","t"=>$sTarget,"p"=>$sEvent),$sHandler);
462 }
463
464 /**
465 * Adds an include script command message to the XML response.
466 *
467 * <i>Usage:</i> <kbd>$objResponse->addIncludeScript("functions.js");</kbd>
468 *
469 * @param string URL of the Javascript file to include
470 */
471 function addIncludeScript($sFileName)
472 {
473 $this->xml .= $this->_cmdXML(array("n"=>"in"),$sFileName);
474 }
475
476 /**
477 * Returns the XML to be returned from your function to the xajax processor
478 * on your page. Since xajax 0.2, you can also return an xajaxResponse
479 * object from your function directly, and xajax will automatically request
480 * the XML using this method call.
481 *
482 * <i>Usage:</i> <kbd>return $objResponse->getXML();</kbd>
483 *
484 * @return string response XML data
485 */
486 function getXML()
487 {
488 $sXML = "<?xml version=\"1.0\"";
489 if ($this->sEncoding && strlen(trim($this->sEncoding)) > 0)
490 $sXML .= " encoding=\"".$this->sEncoding."\"";
491 $sXML .= " ?"."><xjx>" . $this->xml . "</xjx>";
492
493 return $sXML;
494 }
495
496 /**
497 * Adds the commands of the provided response XML output to this response
498 * object
499 *
500 * <i>Usage:</i>
501 * <code>$r1 = $objResponse1->getXML();
502 * $objResponse2->loadXML($r1);
503 * return $objResponse2->getXML();</code>
504 *
505 * @param string the response XML (returned from a getXML() method) to add
506 * to the end of this response object
507 */
508 function loadXML($mXML)
509 {
510 if (is_a($mXML, "xajaxResponse")) {
511 $mXML = $mXML->getXML();
512 }
513 $sNewXML = "";
514 $iStartPos = strpos($mXML, "<xjx>") + 5;
515 $sNewXML = substr($mXML, $iStartPos);
516 $iEndPos = strpos($sNewXML, "</xjx>");
517 $sNewXML = substr($sNewXML, 0, $iEndPos);
518 $this->xml .= $sNewXML;
519 }
520
521 /**
522 * Generates XML from command data
523 *
524 * @access private
525 * @param array associative array of attributes
526 * @param string data
527 * @return string XML command
528 */
529 function _cmdXML($aAttributes, $sData)
530 {
531 if ($this->bOutputEntities) {
532 if (function_exists('mb_convert_encoding')) {
533 $sData = call_user_func_array('mb_convert_encoding', array(&$sData, 'HTML-ENTITIES', $this->sEncoding));
534 }
535 else {
536 trigger_error("The xajax XML response output could not be converted to HTML entities because the mb_convert_encoding function is not available", E_USER_NOTICE);
537 }
538 }
539 $xml = "<cmd";
540 foreach($aAttributes as $sAttribute => $sValue)
541 $xml .= " $sAttribute=\"$sValue\"";
542 if ($sData !== null && !stristr($sData,'<![CDATA['))
543 $xml .= "><![CDATA[$sData]]></cmd>";
544 else if ($sData !== null)
545 $xml .= ">$sData</cmd>";
546 else
547 $xml .= "></cmd>";
548
549 return $xml;
550 }
551
552 /**
553 * Recursively serializes a data structure in XML so it can be sent to
554 * the client. It could be thought of as the opposite of
555 * {@link xajax::_parseObjXml()}.
556 *
557 * @access private
558 * @param mixed data structure to serialize to XML
559 * @return string serialized XML
560 */
561 function _buildObjXml($var) {
562 if (gettype($var) == "object") $var = get_object_vars($var);
563 if (!is_array($var)) {
564 return "<![CDATA[$var]]>";
565 }
566 else {
567 $data = "<xjxobj>";
568 foreach ($var as $key => $value) {
569 $data .= "<e>";
570 $data .= "<k>" . htmlspecialchars($key) . "</k>";
571 $data .= "<v>" . $this->_buildObjXml($value) . "</v>";
572 $data .= "</e>";
573 }
574 $data .= "</xjxobj>";
575 return $data;
576 }
577 }
578
579}// end class xajaxResponse
580?>