* Assign - sets the specified attribute of an element in your page
* Append - appends data to the end of the specified attribute of an
* element in your page
* Prepend - prepends data to the beginning of the specified attribute of
* an element in your page
* Replace - searches for and replaces data in the specified attribute of
* an element in your page
* Script - runs the supplied JavaScript code
* Alert - shows an alert box with the supplied message text
*
*
* Note: elements are identified by their HTML id, so if you don't see
* your browser HTML display changing from the request, make sure you're using
* the right id names in your response.
*
* @package xajax
*/
class xajaxResponse
{
/**#@+
* @access protected
*/
/**
* @var array internal command storage
*/
var $aCommands;
/**
* @var string the encoding type to use
*/
var $sEncoding;
/**
* @var boolean if special characters in the XML should be converted to
* entities
*/
var $bOutputEntities;
/**#@-*/
/**
* The constructor's main job is to set the character encoding for the
* response.
*
* Note: to change the character encoding for all of the
* responses, set the XAJAX_DEFAULT_ENCODING constant before you
* instantiate xajax.
*
* @param string contains the character encoding string to use
* @param boolean lets you set if you want special characters in the output
* converted to HTML entities
*
*/
function xajaxResponse($sEncoding=XAJAX_DEFAULT_CHAR_ENCODING, $bOutputEntities=false)
{
$this->setCharEncoding($sEncoding);
$this->bOutputEntities = $bOutputEntities;
$this->aCommands = array();
}
/**
* Sets the character encoding for the response based on $sEncoding, which
* is a string containing the character encoding to use. You don't need to
* use this method normally, since the character encoding for the response
* gets set automatically based on the XAJAX_DEFAULT_CHAR_ENCODING
* constant.
*
* @param string
*/
function setCharEncoding($sEncoding)
{
$this->sEncoding = $sEncoding;
return $this;
}
/**
* If true, tells the response object to convert special characters to HTML
* entities automatically (only works if the mb_string extension is
* available).
*/
function setOutputEntities($bOption)
{
$this->bOutputEntities = (boolean)$bOption;
return $this;
}
/**
* Provides access to the xajaxResponse plugin system. If you use PHP 4 or
* 5, pass the plugin name as the first argument, the plugin's method name
* as the second argument, and subsequent arguments (if any) after that.
* Optionally, if you use PHP 5, you can pass just the plugin name as the
* first argument and the plugin object will be returned which you can use
* to call the appropriate method.
*
* @param string name of the plugin to call
*/
function &plugin($sName)
{
$objManager =& xajaxPluginManager::getInstance();
$objPlugin =& $objManager->getResponsePlugin($sName);
$objPlugin->setResponseObject($this);
$aArgs = func_get_args();
array_shift($aArgs);
if (!empty($aArgs)) {
$sMethodName = array_shift($aArgs);
call_user_func_array(array(&$objPlugin, $sMethodName), $aArgs);
}
return $objPlugin;
}
/**
* Internal function for PHP5 only. Used to permit plugins to be called as
* if they were native member variables of the xajaxResponse class.
*
* PHP5 Usage: $objResponse->myPlugin->myPluginMethod("param1", "param2");
*
* @param string The name of the callName of a responsePlugin that has been registered with the plugin manager
*/
function __get($sPluginName)
{
return $this->plugin($sPluginName);
}
/**
* Adds a confirm commands command message to the response.
*
* Usage: $objResponse->confirmCommands(1, "Do you want to preview the new data?");
*
* @param integer the number of commands to skip if the user presses
* Cancel in the browsers's confirm dialog
* @param string the message to show in the browser's confirm dialog
*/
function confirmCommands($iCmdNumber, $sMessage)
{
$this->addCommand(array("n"=>"cc","t"=>$iCmdNumber),$sMessage);
return $this;
}
/**
* Adds an assign command message to the response.
*
* Usage: $objResponse->assign("contentDiv", "innerHTML", "Some Text");
*
* @param string contains the id of an HTML element
* @param string the part of the element you wish to modify ("innerHTML",
* "value", etc.)
* @param string the data you want to set the attribute to
*/
function assign($sTarget,$sAttribute,$sData)
{
$this->addCommand(array("n"=>"as","t"=>$sTarget,"p"=>$sAttribute),$sData);
return $this;
}
/**
* Adds an append command message to the response.
*
* Usage: $objResponse->append("contentDiv", "innerHTML", "Some New Text");
*
* @param string contains the id of an HTML element
* @param string the part of the element you wish to modify ("innerHTML",
* "value", etc.)
* @param string the data you want to append to the end of the attribute
*/
function append($sTarget,$sAttribute,$sData)
{
$this->addCommand(array("n"=>"ap","t"=>$sTarget,"p"=>$sAttribute),$sData);
return $this;
}
/**
* Adds an prepend command message to the response.
*
* Usage: $objResponse->prepend("contentDiv", "innerHTML", "Some Starting Text");
*
* @param string contains the id of an HTML element
* @param string the part of the element you wish to modify ("innerHTML",
* "value", etc.)
* @param string the data you want to prepend to the beginning of the
* attribute
*/
function prepend($sTarget,$sAttribute,$sData)
{
$this->addCommand(array("n"=>"pp","t"=>$sTarget,"p"=>$sAttribute),$sData);
return $this;
}
/**
* Adds a replace command message to the response.
*
* Usage: $objResponse->replace("contentDiv", "innerHTML", "text", "text");
*
* @param string contains the id of an HTML element
* @param string the part of the element you wish to modify ("innerHTML",
* "value", etc.)
* @param string the string to search for
* @param string the string to replace the search string when found in the
* attribute
*/
function replace($sTarget,$sAttribute,$sSearch,$sData)
{
$aData = array('s'=>$sSearch, 'r'=>$sData);
$this->addCommand(array("n"=>"rp","t"=>$sTarget,"p"=>$sAttribute),$aData);
return $this;
}
/**
* Adds a clear command message to the response.
*
* Usage: $objResponse->clear("contentDiv", "innerHTML");
*
* @param string contains the id of an HTML element
* @param string the part of the element you wish to clear ("innerHTML",
* "value", etc.)
*/
function clear($sTarget,$sAttribute)
{
$this->assign($sTarget,$sAttribute,'');
return $this;
}
/**
* Adds an alert command message to the response.
*
* Usage: $objResponse->alert("This is important information");
*
* @param string the text to be displayed in the Javascript alert box
*/
function alert($sMsg)
{
$this->addCommand(array("n"=>"al"),$sMsg);
return $this;
}
/**
* Uses the addScript() method to add a Javascript redirect to another URL.
*
* Usage: $objResponse->redirect("http://www.xajaxproject.org");
*
* @param string the URL to redirect the client browser to
*/
function redirect($sURL, $iDelay=0)
{
//we need to parse the query part so that the values are rawurlencode()'ed
//can't just use parse_url() cos we could be dealing with a relative URL which
// parse_url() can't deal with.
$queryStart = strpos($sURL, '?', strrpos($sURL, '/'));
if ($queryStart !== FALSE)
{
$queryStart++;
$queryEnd = strpos($sURL, '#', $queryStart);
if ($queryEnd === FALSE)
$queryEnd = strlen($sURL);
$queryPart = substr($sURL, $queryStart, $queryEnd-$queryStart);
parse_str($queryPart, $queryParts);
$newQueryPart = "";
if ($queryParts)
{
$first = true;
foreach($queryParts as $key => $value)
{
if ($first)
$first = false;
else
$newQueryPart .= ini_get('arg_separator.output');
$newQueryPart .= rawurlencode($key).'='.rawurlencode($value);
}
} else if ($_SERVER['QUERY_STRING']) {
//couldn't break up the query, but there's one there
//possibly "http://url/page.html?query1234" type of query?
//just encode it and hope it works
$newQueryPart = rawurlencode($_SERVER['QUERY_STRING']);
}
$sURL = str_replace($queryPart, $newQueryPart, $sURL);
}
if ($iDelay)
$this->script('window.setTimeout("window.location = \''.$sURL.'\';",'.($iDelay*1000).');');
else
$this->script('window.location = "'.$sURL.'";');
return $this;
}
/**
* Adds a Javascript command message to the response.
*
* Usage: $objResponse->script("var x = prompt('get some text');");
*
* @param string contains Javascript code to be executed
*/
function script($sJS)
{
$this->addCommand(array("n"=>"js"),$sJS);
return $this;
}
/**
* Adds a Javascript function call command message to the response.
*
* Usage: $objResponse->call("myJSFunction", "arg 1", "arg 2", 12345);
*
* @param string $sFunc the name of a Javascript function
* @param mixed $args,... optional arguments to pass to the Javascript function
*/
function call() {
$aArgs = func_get_args();
$sFunc = array_shift($aArgs);
$aData = $this->_buildObj($aArgs);
$this->addCommand(array("n"=>"jc","t"=>$sFunc),$aData);
return $this;
}
/**
* Adds a remove element command message to the response.
*
* Usage: $objResponse->remove("Div2");
*
* @param string contains the id of an HTML element to be removed
*/
function remove($sTarget)
{
$this->addCommand(array("n"=>"rm","t"=>$sTarget),'');
return $this;
}
/**
* Adds a create element command message to the response.
*
* Usage: $objResponse->create("parentDiv", "h3", "myid");
*
* @param string contains the id of an HTML element to to which the new
* element will be appended.
* @param string the tag to be added
* @param string the id to be assigned to the new element
* @param string deprecated, use the addCreateInput() method instead
*/
function create($sParent, $sTag, $sId, $sType="")
{
if ($sType)
{
trigger_error("The \$sType parameter of addCreate has been deprecated. Use the addCreateInput() method instead.", E_USER_WARNING);
return;
}
$this->addCommand(array("n"=>"ce","t"=>$sParent,"p"=>$sId),$sTag);
return $this;
}
/**
* Adds a insert element command message to the response.
*
* Usage: $objResponse->insert("childDiv", "h3", "myid");
*
* @param string contains the id of the child before which the new element
* will be inserted
* @param string the tag to be added
* @param string the id to be assigned to the new element
*/
function insert($sBefore, $sTag, $sId)
{
$this->addCommand(array("n"=>"ie","t"=>$sBefore,"p"=>$sId),$sTag);
return $this;
}
/**
* Adds a insert element command message to the response.
*
* Usage: $objResponse->insertAfter("childDiv", "h3", "myid");
*
* @param string contains the id of the child after which the new element
* will be inserted
* @param string the tag to be added
* @param string the id to be assigned to the new element
*/
function insertAfter($sAfter, $sTag, $sId)
{
$this->addCommand(array("n"=>"ia","t"=>$sAfter,"p"=>$sId),$sTag);
return $this;
}
/**
* Adds a create input command message to the response.
*
* Usage: $objResponse->createInput("form1", "text", "username", "input1");
*
* @param string contains the id of an HTML element to which the new input
* will be appended
* @param string the type of input to be created (text, radio, checkbox,
* etc.)
* @param string the name to be assigned to the new input and the variable
* name when it is submitted
* @param string the id to be assigned to the new input
*/
function createInput($sParent, $sType, $sName, $sId)
{
$this->addCommand(array("n"=>"ci","t"=>$sParent,"p"=>$sId,"c"=>$sType),$sName);
return $this;
}
/**
* Adds an insert input command message to the response.
*
* Usage: $objResponse->insertInput("input5", "text", "username", "input1");
*
* @param string contains the id of the child before which the new element
* will be inserted
* @param string the type of input to be created (text, radio, checkbox,
* etc.)
* @param string the name to be assigned to the new input and the variable
* name when it is submitted
* @param string the id to be assigned to the new input
*/
function insertInput($sBefore, $sType, $sName, $sId)
{
$this->addCommand(array("n"=>"ii","t"=>$sBefore,"p"=>$sId,"c"=>$sType),$sName);
return $this;
}
/**
* Adds an insert input command message to the response.
*
* Usage: $objResponse->insertInputAfter("input7", "text", "email", "input2");
*
* @param string contains the id of the child after which the new element
* will be inserted
* @param string the type of input to be created (text, radio, checkbox,
* etc.)
* @param string the name to be assigned to the new input and the variable
* name when it is submitted
* @param string the id to be assigned to the new input
*/
function insertInputAfter($sAfter, $sType, $sName, $sId)
{
$this->addCommand(array("n"=>"iia","t"=>$sAfter,"p"=>$sId,"c"=>$sType),$sName);
return $this;
}
/**
* Adds an event command message to the response.
*
* Usage: $objResponse->addEvent("contentDiv", "onclick", "alert(\'Hello World\');");
*
* @param string contains the id of an HTML element
* @param string the event you wish to set ("onclick", "onmouseover", etc.)
* @param string the Javascript string you want the event to invoke
*/
function addEvent($sTarget,$sEvent,$sScript)
{
$this->addCommand(array("n"=>"ev","t"=>$sTarget,"p"=>$sEvent),$sScript);
return $this;
}
/**
* Adds a handler command message to the response.
*
* Usage: $objResponse->addHandler("contentDiv", "onclick", "content_click");
*
* @param string contains the id of an HTML element
* @param string the event you wish to set ("onclick", "onmouseover", etc.)
* @param string the name of a Javascript function that will handle the
* event. Multiple handlers can be added for the same event
*/
function addHandler($sTarget,$sEvent,$sHandler)
{
$this->addCommand(array("n"=>"ah","t"=>$sTarget,"p"=>$sEvent),$sHandler);
return $this;
}
/**
* Adds a remove handler command message to the response.
*
* Usage: $objResponse->removeHandler("contentDiv", "onclick", "content_click");
*
* @param string contains the id of an HTML element
* @param string the event you wish to remove ("onclick", "onmouseover",
* etc.)
* @param string the name of a Javascript handler function that you want to
* remove
*/
function removeHandler($sTarget,$sEvent,$sHandler)
{
$this->addCommand(array("n"=>"rh","t"=>$sTarget,"p"=>$sEvent),$sHandler);
return $this;
}
/**
* Adds an include script command message to the response.
*
* Usage: $objResponse->includeScript("functions.js");
*
* @param string URL of the Javascript file to include
*/
function includeScript($sFileName)
{
$this->addCommand(array("n"=>"in"),$sFileName);
return $this;
}
/**
* Adds an include script once command message to the response.
*
* Usage: $objResponse->includeScriptOnce("functions2.js");
*
* @param string URL of the Javascript file to include
*/
function includeScriptOnce($sFileName)
{
$this->addCommand(array("n"=>"ino"),$sFileName);
return $this;
}
/**
* Adds an include CSS command message to the response.
*
* Usage: $objResponse->includeCSS("stylesheet.css");
*
* @param string URL of the CSS file to include
*/
function includeCSS($sFileName)
{
$this->addCommand(array("n"=>"css"),$sFileName);
return $this;
}
/**
* Returns the content type of the response (typically "text/xml").
*
* @return string
*/
function getContentType()
{
return 'text/xml';
}
/**
* Returns the output of the response suitable for sending to a Web browser
* (i. e., XML or JSON)
*
* @return string
*/
function getOutput()
{
$xml = "";
if (is_array($this->aCommands))
{
foreach($this->aCommands as $aCommand)
{
$sData = $aCommand['data'];
unset($aCommand['data']);
$xml .= $this->_getXMLForCommand($aCommand, $sData);
}
}
$sXML = "sEncoding && strlen(trim($this->sEncoding)) > 0)
$sXML .= " encoding=\"".$this->sEncoding."\"";
$sXML .= " ?".">" . $xml . "";
return $sXML;
}
/**
* Returns the number of commands current in the response
*
* @return integer
*/
function getCommandCount()
{
return count($this->aCommands);
}
/**
* Adds the commands of the provided response to this response object
*
* Usage:
* $objResponse2->loadCommands($objResponse1);
* return $objResponse2;
*
* @param mixed the response object to add to the end of this response
* object, or an array of response commands
*/
function loadCommands($mCommands, $bBefore=false)
{
if (is_a($mCommands, "xajaxResponse")) {
if ($bBefore) {
$this->aCommands = array_merge($mCommands->aCommands, $this->aCommands);
}
else {
$this->aCommands = array_merge($this->aCommands, $mCommands->aCommands);
}
}
else if (is_array($mCommands)) {
if ($bBefore) {
$this->aCommands = array_merge($mCommands, $this->aCommands);
}
else {
$this->aCommands = array_merge($this->aCommands, $mCommands);
}
}
else {
if (!empty($mCommands))
trigger_error("The xajax response output could not load other commands as data was not a valid array", E_USER_ERROR);
}
}
/**
* Used internally by the response plugin system
*
* @param xajaxResponsePlugin response plugin (subclass of xajaxResponsePlugin)
* @param array associative array of command attributes
* @param mixed command data
*/
function addPluginCommand($objPlugin, $aAttributes, $mData)
{
$aAttributes["plg"] = $objPlugin->sCallName;
$this->addCommand($aAttributes, $mData);
}
/**
* Generates XML from command data
*
* @access private
* @param array associative array of attributes
* @param mixed data
* @return string XML command
*/
function _getXMLForCommand($aAttributes, $mData)
{
$xml = " $sValue)
{
if ($sAttribute)
$xml .= " $sAttribute=\"$sValue\"";
}
if (is_array($mData)) {
$xml .= ">".$this->_arrayToXML($mData)."";
} else {
$xml .= ">".$this->_escape($mData)."";
}
return $xml;
}
/**
* Converts an array of data into XML
*
* @access private
* @param mixed associative array of data or string of data
* @return string XML command
*/
function _arrayToXML($mArray)
{
if (!is_array($mArray))
return $this->_escape($mArray);
$xml = "";
foreach($mArray as $sKey=>$sValue)
{
$xml .= '<'.htmlentities($sKey).'>';
$xml .= $this->_arrayToXML($sValue);
$xml .= '';
}
return $xml;
}
/**
* Adds a commmand to the array of all commands
*
* @param array associative array of attributes
* @param mixed data
*/
function addCommand($aAttributes, $mData)
{
$aAttributes['data'] = $mData;
$this->aCommands[] = $aAttributes;
}
/**
* Escapes the data. Can be overridden to allow other transports to send
* data.
*
* @access private
* @param string data
* @return string escaped data
*/
function _escape($sData)
{
if ($sData !== null && strpos($sData,'bOutputEntities) {
if (function_exists('mb_convert_encoding')) {
$sData = call_user_func_array('mb_convert_encoding', array(&$sData, 'HTML-ENTITIES', $this->sEncoding));
}
else {
trigger_error("The xajax response output could not be converted to HTML entities because the mb_convert_encoding function is not available", E_USER_NOTICE);
}
}
}
else if ($sData === null) {
$sData = "";
}
$sData = str_replace(']]>',']]]]>', $sData);
$sData = "";
return $sData;
}
/**
* Recursively serializes a data structure in an array so it can be sent to
* the client. It could be thought of as the opposite of
* {@link xajax::_parseObjXml()}.
*
* @access private
* @param mixed data structure to serialize
* @return array data ready for insertion into command list array
*/
function _buildObj($mData) {
if (gettype($mData) == "object") $mData = get_object_vars($mData);
if (!is_array($mData)) {
return $this->_escape($mData);
}
else {
$aData = array();
foreach ($mData as $key => $value) {
$aData['k'] = htmlentities($key);
$aData['v'] = $this->_buildObj($value);
}
return $aData;
}
}
}// end class xajaxResponse
?>