ajax/xajaxResponse.inc.php

   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  */
  68 class 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 ?>