[Sommaire] [Imprimer]

   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  ?>