|
|
|---|
| [ Index ] |
Source Code Reference for V1.00 |
[Summary view] [Print] [Text view]
1 <?php 2 /* 3 File: xajaxResponse.inc.php 4 5 Contains the response class. 6 7 Title: xajax response class 8 9 Please see <copyright.inc.php> for a detailed description, copyright 10 and license information. 11 */ 12 13 /* 14 @package xajax 15 @version $Id: xajaxResponse.inc.php 361 2007-05-24 12:48:14Z calltoconstruct $ 16 @copyright Copyright (c) 2005-2006 by Jared White & J. Max Wilson 17 @license http://www.xajaxproject.org/bsd_license.txt BSD License 18 */ 19 20 /* 21 Class: xajaxResponse 22 23 Collect commands to be sent back to the browser in response to a xajax 24 request. Commands are encoded and packaged in a format that is acceptable 25 to the response handler from the javascript library running on the client 26 side. 27 28 Common commands include: 29 - <xajaxResponse->assign>: Assign a value to an elements property. 30 - <xajaxResponse->append>: Append a value on to an elements property. 31 - <xajaxResponse->script>: Execute a portion of javascript code. 32 - <xajaxResponse->call>: Execute an existing javascript function. 33 - <xajaxResponse->alert>: Display an alert dialog to the user. 34 35 Elements are identified by the value of the HTML id attribute. If you do 36 not see your updates occuring on the browser side, ensure that you are 37 using the correct id in your response. 38 */ 39 class xajaxResponse 40 { 41 /**#@+ 42 * @access protected 43 */ 44 45 /* 46 Array: aCommands 47 48 Stores the commands that will be sent to the browser in the response. 49 */ 50 var $aCommands; 51 52 /* 53 String: sCharacterEncoding 54 55 The name of the encoding method you wish to use when dealing with 56 special characters. See <xajax->setEncoding> for more information. 57 */ 58 var $sCharacterEncoding; 59 60 /* 61 Boolean: bOutputEntities 62 63 Convert special characters to the HTML equivellent. See also 64 <xajax->bOutputEntities> and <xajax->setFlag>. 65 */ 66 var $bOutputEntities; 67 68 /* 69 Mixed: returnValue 70 71 A string, array or integer value to be returned to the caller when 72 using 'synchronous' mode requests. See <xajax->setMode> for details. 73 */ 74 var $returnValue; 75 76 /* 77 Object: objPluginManager 78 79 A reference to the global plugin manager. 80 */ 81 var $objPluginManager; 82 83 /**#@-*/ 84 85 /* 86 Constructor: xajaxResponse 87 88 Create and initialize a xajaxResponse object. 89 */ 90 function xajaxResponse() 91 { 92 //SkipDebug 93 if (0 < func_num_args()) { 94 $objLanguageManager =& xajaxLanguageManager::getInstance(); 95 trigger_error( 96 $objLanguageManager->getText('XJXRSP:EDERR:01') 97 , E_USER_ERROR 98 ); 99 } 100 //EndSkipDebug 101 102 $this->aCommands = array(); 103 104 $objResponseManager =& xajaxResponseManager::getInstance(); 105 106 $this->sCharacterEncoding = $objResponseManager->getCharacterEncoding(); 107 $this->bOutputEntities = $objResponseManager->getOutputEntities(); 108 109 $this->objPluginManager =& xajaxPluginManager::getInstance(); 110 } 111 112 /* 113 Function: setCharacterEncoding 114 115 Overrides the default character encoding (or the one specified in the 116 constructor) to the specified character encoding. 117 118 sCharacterEncoding - (string): The encoding method to use for this response. 119 120 See also, <xajaxResponse->xajaxResponse>() 121 122 Returns: 123 124 object - The xajaxResponse object. 125 */ 126 function setCharacterEncoding($sCharacterEncoding) 127 { 128 $this->sCharacterEncoding = $sCharacterEncoding; 129 return $this; 130 } 131 132 /* 133 Function: setOutputEntities 134 135 Convert special characters to their HTML equivellent automatically 136 (only works if the mb_string extension is available). 137 138 bOption - (boolean): Convert special characters 139 140 Returns: 141 142 object - The xajaxResponse object. 143 */ 144 function setOutputEntities($bOutputEntities) 145 { 146 $this->bOutputEntities = (boolean)$bOutputEntities; 147 return $this; 148 } 149 150 /* 151 Function: plugin 152 153 Provides access to registered response plugins. If you are using PHP 154 4 or 5, pass the plugin name as the first argument, the plugin method 155 name as the second argument and subsequent arguments (if any) to be 156 passed along to the plugin. 157 158 Optionally, if you use PHP 5, you can pass just the plugin name as the 159 first argument and the plugin object will be returned. You can then 160 access the methods of the plugin directly. 161 162 sName - (string): Name of the plugin. 163 sFunction - (string, optional): The name of the method to call. 164 arg1...argn - (mixed, optional): Additional arguments to pass on to 165 the plugin function. 166 167 Returns: 168 169 object - The plugin specified by sName. 170 */ 171 function &plugin() 172 { 173 $aArgs = func_get_args(); 174 $nArgs = func_num_args(); 175 176 //SkipDebug 177 if (false == (0 < $nArgs)) { 178 $objLanguageManager =& xajaxLanguageManager::getInstance(); 179 trigger_error( 180 $objLanguageManager->getText('XJXRSP:MPERR:01') 181 , E_USER_ERROR 182 ); 183 } 184 //EndSkipDebug 185 186 $sName = array_shift($aArgs); 187 188 $objPlugin =& $this->objPluginManager->getPlugin($sName); 189 190 if (false === $objPlugin) 191 { 192 $bReturn = false; 193 return $bReturn; 194 } 195 196 $objPlugin->setResponse($this); 197 198 if (0 < count($aArgs)) 199 { 200 $sMethod = array_shift($aArgs); 201 202 $aFunction = array(&$objPlugin, $sMethod); 203 call_user_func_array($aFunction, $aArgs); 204 } 205 206 return $objPlugin; 207 } 208 209 /* 210 Function: __get 211 212 Magic function for PHP 5. Used to permit plugins to be called as if they 213 where native members of the xajaxResponse instance. 214 215 sPluginName - (string): The name of the plugin. 216 217 Returns: 218 219 object - The plugin specified by sPluginName. 220 */ 221 function &__get($sPluginName) 222 { 223 $objPlugin =& $this->plugin($sPluginName); 224 return $objPlugin; 225 } 226 227 /* 228 Function: confirmCommands 229 230 Response command that prompts user with [ok] [cancel] style 231 message box. If the user clicks cancel, the specified 232 number of response commands following this one, will be 233 skipped. 234 235 iCmdNumber - (integer): The number of commands to skip upon cancel. 236 sMessage - (string): The message to display to the user. 237 238 Returns: 239 240 object - The xajaxResponse object. 241 */ 242 function confirmCommands($iCmdNumber, $sMessage) 243 { 244 return $this->addCommand( 245 array( 246 'n'=>'cc', 247 't'=>$iCmdNumber 248 ), 249 $sMessage 250 ); 251 } 252 253 /* 254 Function: assign 255 256 Response command indicating that the specified value should be 257 assigned to the given element's attribute. 258 259 sTarget - (string): The id of the html element on the browser. 260 sAttribute - (string): The property to be assigned. 261 sData - (string): The value to be assigned to the property. 262 263 Returns: 264 265 object - The <xajaxResponse> object. 266 267 Example: 268 269 $objResponse->assign("contentDiv", "innerHTML", "Some Text"); 270 */ 271 function assign($sTarget,$sAttribute,$sData) 272 { 273 return $this->addCommand( 274 array( 275 'n'=>'as', 276 't'=>$sTarget, 277 'p'=>$sAttribute 278 ), 279 $sData 280 ); 281 } 282 283 /* 284 Function: append 285 286 Response command that indicates the specified data should be appended 287 to the given element's property. 288 289 sTarget - (string): The id of the element to be updated. 290 sAttribute - (string): The name of the property to be appended to. 291 sData - (string): The data to be appended to the property. 292 293 Returns: 294 295 object - The <xajaxResponse> object. 296 */ 297 function append($sTarget,$sAttribute,$sData) 298 { 299 return $this->addCommand( 300 array( 301 'n'=>'ap', 302 't'=>$sTarget, 303 'p'=>$sAttribute 304 ), 305 $sData 306 ); 307 } 308 309 /* 310 Function: prepend 311 312 Response command to prepend the specified value onto the given 313 element's property. 314 315 sTarget - (string): The id of the element to be updated. 316 sAttribute - (string): The property to be updated. 317 sData - (string): The value to be prepended. 318 319 Returns: 320 321 object - The <xajaxResponse> object. 322 */ 323 function prepend($sTarget,$sAttribute,$sData) 324 { 325 return $this->addCommand( 326 array( 327 'n'=>'pp', 328 't'=>$sTarget, 329 'p'=>$sAttribute 330 ), 331 $sData 332 ); 333 } 334 335 /* 336 Function: replace 337 338 Replace a specified value with another value within the given 339 element's property. 340 341 sTarget - (string): The id of the element to update. 342 sAttribute - (string): The property to be updated. 343 sSearch - (string): The needle to search for. 344 sData - (string): The data to use in place of the needle. 345 */ 346 function replace($sTarget,$sAttribute,$sSearch,$sData) 347 { 348 return $this->addCommand( 349 array( 350 'n'=>'rp', 351 't'=>$sTarget, 352 'p'=>$sAttribute 353 ), 354 array( 355 's' => $sSearch, 356 'r' => $sData 357 ) 358 ); 359 } 360 361 /* 362 Function: clear 363 364 Response command used to clear the specified property of the 365 given element. 366 367 sTarget - (string): The id of the element to be updated. 368 sAttribute - (string): The property to be clared. 369 370 Returns: 371 372 object - The <xajaxResponse> object. 373 */ 374 function clear($sTarget,$sAttribute) 375 { 376 return $this->assign( 377 $sTarget, 378 $sAttribute, 379 '' 380 ); 381 } 382 383 /* 384 Function: contextAssign 385 386 Response command used to assign a value to a member of a 387 javascript object (or element) that is specified by the context 388 member of the request. The object is referenced using the 'this' keyword 389 in the sAttribute parameter. 390 391 sAttribute - (string): The property to be updated. 392 sData - (string): The value to assign. 393 394 Returns: 395 396 object - The <xajaxResponse> object. 397 */ 398 function contextAssign($sAttribute, $sData) 399 { 400 return $this->addCommand( 401 array( 402 'n'=>'c:as', 403 'p'=>$sAttribute 404 ), 405 $sData 406 ); 407 } 408 409 /* 410 Function: contextAppend 411 412 Response command used to append a value onto the specified member 413 of the javascript context object (or element) specified by the context 414 member of the request. The object is referenced using the 'this' keyword 415 in the sAttribute parameter. 416 417 sAttribute - (string): The member to be appended to. 418 sData - (string): The value to append. 419 420 Returns: 421 422 object - The <xajaxResponse> object. 423 */ 424 function contextAppend($sAttribute, $sData) 425 { 426 return $this->addCommand( 427 array( 428 'n'=>'c:ap', 429 'p'=>$sAttribute 430 ), 431 $sData 432 ); 433 } 434 435 /* 436 Function: contextPrepend 437 438 Response command used to prepend the speicified data to the given 439 member of the current javascript object specified by context in the 440 current request. The object is access via the 'this' keyword in the 441 sAttribute parameter. 442 443 sAttribute - (string): The member to be updated. 444 sData - (string): The value to be prepended. 445 446 Returns: 447 448 object - The <xajaxResponse> object. 449 */ 450 function contextPrepend($sAttribute, $sData) 451 { 452 return $this->addCommand( 453 array( 454 'n'=>'c:pp', 455 'p'=>$sAttribute 456 ), 457 $sData 458 ); 459 } 460 461 /* 462 Function: contextClear 463 464 Response command used to clear the value of the property specified 465 in the sAttribute parameter. The member is access via the 'this' 466 keyword and can be used to update a javascript object specified 467 by context in the request parameters. 468 469 sAttribute - (string): The member to be cleared. 470 471 Returns: 472 473 object - The <xajaxResponse> object. 474 */ 475 function contextClear($sAttribute) 476 { 477 return $this->contextAssign( 478 $sAttribute, 479 '' 480 ); 481 } 482 483 /* 484 Function: alert 485 486 Response command that is used to display an alert message to the user. 487 488 sMsg - (string): The message to be displayed. 489 490 Returns: 491 492 object - The <xajaxResponse> object. 493 */ 494 function alert($sMsg) 495 { 496 return $this->addCommand( 497 array( 498 'n'=>'al' 499 ), 500 $sMsg 501 ); 502 } 503 504 function debug($sMessage) 505 { 506 return $this->addCommand( 507 array( 508 'n'=>'dbg' 509 ), 510 $sMessage 511 ); 512 } 513 514 /* 515 Function: redirect 516 517 Response command that causes the browser to navigate to the specified 518 URL. 519 520 sURL - (string): The relative or fully qualified URL. 521 iDelay - (integer, optional): Number of seconds to delay before 522 the redirect occurs. 523 524 Returns: 525 526 object - The <xajaxResponse> object. 527 */ 528 function redirect($sURL, $iDelay=0) 529 { 530 //we need to parse the query part so that the values are rawurlencode()'ed 531 //can't just use parse_url() cos we could be dealing with a relative URL which 532 // parse_url() can't deal with. 533 $queryStart = strpos($sURL, '?', strrpos($sURL, '/')); 534 if ($queryStart !== FALSE) 535 { 536 $queryStart++; 537 $queryEnd = strpos($sURL, '#', $queryStart); 538 if ($queryEnd === FALSE) 539 $queryEnd = strlen($sURL); 540 $queryPart = substr($sURL, $queryStart, $queryEnd-$queryStart); 541 parse_str($queryPart, $queryParts); 542 $newQueryPart = ""; 543 if ($queryParts) 544 { 545 $first = true; 546 foreach($queryParts as $key => $value) 547 { 548 if ($first) 549 $first = false; 550 else 551 $newQueryPart .= ini_get('arg_separator.output'); 552 $newQueryPart .= rawurlencode($key).'='.rawurlencode($value); 553 } 554 } else if ($_SERVER['QUERY_STRING']) { 555 //couldn't break up the query, but there's one there 556 //possibly "http://url/page.html?query1234" type of query? 557 //just encode it and hope it works 558 $newQueryPart = rawurlencode($_SERVER['QUERY_STRING']); 559 } 560 $sURL = str_replace($queryPart, $newQueryPart, $sURL); 561 } 562 if ($iDelay) 563 $this->script( 564 'window.setTimeout("window.location = \'' 565 . $sURL 566 . '\';",' 567 . ($iDelay*1000) 568 . ');' 569 ); 570 else 571 $this->script( 572 'window.location = "' 573 . $sURL 574 . '";' 575 ); 576 return $this; 577 } 578 579 /* 580 Function: script 581 582 Response command that is used to execute a portion of javascript on 583 the browser. The script runs in it's own context, so variables declared 584 locally, using the 'var' keyword, will no longer be available after the 585 call. To construct a variable that will be accessable globally, even 586 after the script has executed, leave off the 'var' keyword. 587 588 sJS - (string): The script to execute. 589 590 Returns: 591 592 object - The <xajaxResponse> object. 593 */ 594 function script($sJS) 595 { 596 return $this->addCommand( 597 array( 598 'n'=>'js' 599 ), 600 $sJS 601 ); 602 } 603 604 /* 605 Function: call 606 607 Response command that indicates that the specified javascript 608 function should be called with the given (optional) parameters. 609 610 arg1 - (string): The name of the function to call. 611 arg2 .. argn - arguments to be passed to the function. 612 613 Returns: 614 615 object - The <xajaxResponse> object. 616 */ 617 function call() { 618 $aArgs = func_get_args(); 619 $sFunc = array_shift($aArgs); 620 return $this->addCommand( 621 array( 622 'n'=>'jc', 623 'f'=>$sFunc 624 ), 625 $aArgs 626 ); 627 } 628 629 /* 630 Function: remove 631 632 Response command used to remove an element from the document. 633 634 sTarget - (string): The id of the element to be removed. 635 636 Returns: 637 638 object - The <xajaxResponse> object. 639 */ 640 function remove($sTarget) 641 { 642 return $this->addCommand( 643 array( 644 'n'=>'rm', 645 't'=>$sTarget), 646 '' 647 ); 648 } 649 650 /* 651 Function: create 652 653 Response command used to create a new element on the browser. 654 655 sParent - (string): The id of the parent element. 656 sTag - (string): The tag name to be used for the new element. 657 sId - (string): The id to assign to the new element. 658 sType - (string, optional): The type of tag, deprecated, use 659 <xajaxResponse->createInput> instead. 660 661 Returns: 662 663 object - The <xajaxResponse> object. 664 */ 665 function create($sParent, $sTag, $sId, $sType=null) 666 { 667 //SkipDebug 668 if (false === (null === $sType)) { 669 $objLanguageManager =& xajaxLanguageManager::getInstance(); 670 trigger_error( 671 $objLanguageManager->getText('XJXRSP:CPERR:01') 672 , E_USER_WARNING 673 ); 674 } 675 //EndSkipDebug 676 677 return $this->addCommand( 678 array( 679 'n'=>'ce', 680 't'=>$sParent, 681 'p'=>$sId 682 ), 683 $sTag 684 ); 685 } 686 687 /* 688 Function: insert 689 690 Response command used to insert a new element just prior to the specified 691 element. 692 693 sBefore - (string): The element used as a reference point for the 694 insertion. 695 sTag - (string): The tag to be used for the new element. 696 sId - (string): The id to be used for the new element. 697 698 Returns: 699 700 object - The <xajaxResponse> object. 701 */ 702 function insert($sBefore, $sTag, $sId) 703 { 704 return $this->addCommand( 705 array( 706 'n'=>'ie', 707 't'=>$sBefore, 708 'p'=>$sId 709 ), 710 $sTag 711 ); 712 } 713 714 /* 715 Function: insertAfter 716 717 Response command used to insert a new element after the specified 718 one. 719 720 sAfter - (string): The id of the element that will be used as a reference 721 for the insertion. 722 sTag - (string): The tag name to be used for the new element. 723 sId - (string): The id to be used for the new element. 724 725 Returns: 726 727 object - The <xajaxResponse> object. 728 */ 729 function insertAfter($sAfter, $sTag, $sId) 730 { 731 return $this->addCommand( 732 array( 733 'n'=>'ia', 734 't'=>$sAfter, 735 'p'=>$sId 736 ), 737 $sTag 738 ); 739 } 740 741 /* 742 Function: createInput 743 744 Response command used to create an input element on the browser. 745 746 sParent - (string): The id of the parent element. 747 sType - (string): The type of the new input element. 748 sName - (string): The name of the new input element. 749 sId - (string): The id of the new element. 750 751 Returns: 752 753 object - The <xajaxResponse> object. 754 */ 755 function createInput($sParent, $sType, $sName, $sId) 756 { 757 return $this->addCommand( 758 array( 759 'n'=>'ci', 760 't'=>$sParent, 761 'p'=>$sId, 762 'c'=>$sType 763 ), 764 $sName 765 ); 766 } 767 768 /* 769 Function: insertInput 770 771 Response command used to insert a new input element preceeding the 772 specified element. 773 774 sBefore - (string): The id of the element to be used as the reference 775 point for the insertion. 776 sType - (string): The type of the new input element. 777 sName - (string): The name of the new input element. 778 sId - (string): The id of the new input element. 779 780 Returns: 781 782 object - The <xajaxResponse> object. 783 */ 784 function insertInput($sBefore, $sType, $sName, $sId) 785 { 786 return $this->addCommand( 787 array( 788 'n'=>'ii', 789 't'=>$sBefore, 790 'p'=>$sId, 791 'c'=>$sType 792 ), 793