Documentation:xajaxResponse.inc.php






Documentation:xajaxResponse.inc.php

Last change: updated documentation to xajax 0.2.4

The xajaxResponse class is used to create responses to be sent back to your Web page. A response contains one or more command messages for updating your page.

Currently xajax supports 21 kinds of command messages, including some common ones such as:

  • 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.

Contents

[edit] Object Variables (protected)

[edit] $xml

  • Var: (string): internal XML storage

[edit] $sEncoding

  • Var: (string): the encoding type to use

[edit] $bOutputEntities

  • Var: (boolean): if special characters in the XML should be converted to entities

[edit] Object Methods (public)

[edit] xajaxResponse (string $sEncoding=XAJAX_DEFAULT_CHAR_ENCODING, bool $bOutputEntities)

Constructor. Its 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.
  • $sEncoding (string): contains the character encoding string to use
  • $bOutputEntities (boolean): lets you set if you want special characters in the output converted to HTML entities

[edit] setCharEncoding (string $sEncoding)

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.

Usage: 

$objResponse->setCharEncoding("iso-8859-1");
// or:
$objResponse->setCharEncoding("utf-8");
// etc.

[edit] outputEntitiesOn ()

Tells the response object to convert special characters to HTML entities automatically (only works if the mb_string extension is available).

[edit] outputEntitiesOff ()

Tells the response object to output special characters intact. (default behavior)

[edit] addConfirmCommands (integer $iCmdNumber, string $sMessage)

Adds a confirm commands command message to the XML response.

Usage: 

$objResponse->addConfirmCommands(1, "Do you want to preview the new data?");
  • $iCmdNumber (integer): the number of commands to skip if the user presses Cancel in the browsers's confirm dialog
  • $sMessage (string): the message to show in the browser's confirm dialog

[edit] addAssign (string $sTarget, string $sAttribute, string $sData)

Adds an assign command message to the XML response.

An assign message is used to REPLACE the value of an attribute of an element in the client html.

Usage: 

$objResponse->addAssign("contentDiv", "innerHTML", "Some Text");
  • $sTarget (string): contains the id of an HTML element
  • $sAttribute (string): the part of the element you wish to modify ("innerHTML", "value", etc.)
  • $sData (string): the data you want to set the attribute to

For example, you have constructed a table in a string named $table and you want to assign $table to the innerHTML of a div whose id attribute is "tablediv." You would code: 

           $objResponse->AddAssign('tablediv', 'innerHTML', $table);

The contents of $table will REPLACE the current content of tablediv.

[edit] addAppend (string $sTarget, string $sAttribute, string $sData)

Adds an append command message to the XML response.

Usage: 

$objResponse->addAppend("contentDiv", "innerHTML", "Some New Text");
  • $sTarget (string): contains the id of an HTML element
  • $sAttribute (string): the part of the element you wish to modify ("innerHTML", "value", etc.)
  • $sData (string): the data you want to append to the end of the attribute

[edit] addPrepend (string $sTarget, string $sAttribute, string $sData)

Adds a prepend command message to the XML response.

Usage: 

$objResponse->addPrepend("contentDiv", "innerHTML", "Some Starting Text");
  • $sTarget (string): contains the id of an HTML element
  • $sAttribute (string): the part of the element you wish to modify ("innerHTML", "value", etc.)
  • $sData (string): the data you want to prepend to the beginning of the attribute

[edit] addReplace (string $sTarget, string $sAttribute, string $sSearch, string $sData)

Adds a replace command message to the XML response.

Usage: 

$objResponse->addReplace("contentDiv", "innerHTML", "text", "<b>text</b>");
  • $sTarget (string): contains the id of an HTML element
  • $sAttribute (string): the part of the element you wish to modify ("innerHTML", "value", etc.)
  • $sSearch (string): the string to search for
  • $sData (string): the string to replace the search string when found in the attribute

[edit] addClear (string $sTarget, string $sAttribute)

Adds a clear command message to the XML response.

Usage: 

$objResponse->addClear("contentDiv", "innerHTML");
  • $sTarget (string): contains the id of an HTML element
  • $sAttribute (string): the part of the element you wish to clear ("innerHTML", "value", etc.)

[edit] addAlert (string $sMsg)

Adds an alert command message to the XML response.

Usage: 

$objResponse->addAlert("This is important information");
  • $sMsg (string): the text to be displayed in the Javascript alert box

[edit] addRedirect (string $sURL, integer $iDelay)

Uses the addScript() method to add a Javascript redirect to another URL.

Usage: 

$objResponse->addRedirect("http://www.xajaxproject.org");

or 

$objResponse->addRedirect("http://www.xajaxproject.org",4);
  • $sURL (string): the URL to redirect the client browser to
  • $iDelay (integer): the delay before the redirection

[edit] addScript (string $sJS)

Adds a Javascript command message to the XML response.

Usage: 

$objResponse->addScript("var x = prompt('get some text');");
  • $sJS (string): contains Javascript code to be executed

i.e. You have an input on a form whose id=inp and want to focus on it when the response processes: $objResponse->addScript("document.all.inp.focus()");

[edit] addScriptCall ()

Adds a Javascript function call command message to the XML response.

Usage: 

$objResponse->addScriptCall("myJSFunction", "arg 1", "arg 2", 12345);
  • $sFunc (string): the name of a Javascript function
  • $args,... (mixed): optional arguments to pass to the Javascript function

[edit] addRemove (string $sTarget)

Adds a remove element command message to the XML response.

Usage: 

$objResponse->addRemove("Div2");
  • $sTarget (string): contains the id of an HTML element to be removed

[edit] addCreate (string $sParent, string $sTag, string $sId)

Adds a create element command message to the XML response.

Usage: 

$objResponse->addCreate("parentDiv", "h3", "myid");
  • $sParent (string): contains the id of an HTML element to which the new element will be appended.
  • $sTag (string): the tag to be added
  • $sId (string): the id to be assigned to the new element
  • $sType (string): deprecated, use the addCreateInput() method instead

[edit] addInsert (string $sBefore, string $sTag, string $sId)

Adds a insert element command message to the XML response.

Usage: 

$objResponse->addInsert("childDiv", "h3", "myid");
  • $sBefore (string): contains the id of the child before which the new element will be inserted
  • $sTag (string): the tag to be added
  • $sId (string): the id to be assigned to the new element

[edit] addInsertAfter (string $sAfter, string $sTag, string $sId)

Adds a insert element command message to the XML response.

Usage: 

$objResponse->addInsertAfter("childDiv", "h3", "myid");
  • $sAfter (string): contains the id of the child after which the new element will be inserted
  • $sTag (string): the tag to be added
  • $sId (string): the id to be assigned to the new element

[edit] addCreateInput (string $sParent, string $sType, string $sName, string $sId)

Adds a create input command message to the XML response.

Usage: 

$objResponse->addCreateInput("form1", "text", "username", "input1");
  • $sParent (string): contains the id of an HTML element to which the new input will be appended
  • $sType (string): the type of input to be created (text, radio, checkbox, etc.)
  • $sName (string): the name to be assigned to the new input and the variable name when it is submitted
  • $sId (string): the id to be assigned to the new input

[edit] addInsertInput (string $sBefore, string $sType, string $sName, string $sId)

Adds an insert input command message to the XML response.

Usage: 

$objResponse->addInsertInput("input5", "text", "username", "input1");
  • $sBefore (string): contains the id of the child before which the new element will be inserted
  • $sType (string): the type of input to be created (text, radio, checkbox, etc.)
  • $sName (string): the name to be assigned to the new input and the variable name when it is submitted
  • $sId (string): the id to be assigned to the new input

[edit] addInsertInputAfter (string $sAfter, string $sType, string $sName, string $sId)

Adds an insert input command message to the XML response.

Usage: 

$objResponse->addInsertInputAfter("input7", "text", "email", "input2");
  • $sAfter (string): contains the id of the child after which the new element will be inserted
  • $sType (string): the type of input to be created (text, radio, checkbox, etc.)
  • $sName (string): the name to be assigned to the new input and the variable name when it is submitted
  • $sId (string): the id to be assigned to the new input

[edit] addEvent (string $sTarget, string $sEvent, string $sScript)

Adds an event command message to the XML response.

Usage: 

$objResponse->addEvent("contentDiv", "onclick", "alert(\'Hello World\');");
  • $sTarget (string): contains the id of an HTML element
  • $sEvent (string): the event you wish to set ("onclick", "onmouseover", etc.)
  • $sScript (string): the Javascript string you want the event to invoke
Note: in version 0.2 the $sEvent argument of the addEvent method differs from the addHandler() method. The addEvent() method expects the event name to include the "on-" at the beginning ("onclick") whereas the addHandler() method expects the event name without the "on-" ("click"). This difference reflects the difference in the javascript between assigning the event property of an element, and assigning an event handler using the addEventListener() method. The difference has already been remedied in the development version of xajax in CVS which now treats "onclick" and "click" interchangeably in both methods.

[edit] addHandler (string $sTarget, string $sEvent, string $sHandler)

Adds a handler command message to the XML response.

Usage: 

$objResponse->addHandler("contentDiv", "onclick", "content_click");
  • $sTarget (string): contains the id of an HTML element
  • $sEvent (string): the event you wish to set ("onclick", "onmouseover", etc.)
  • $sHandler (string): the name of a Javascript function that will handle the event. Multiple handlers can be added for the same event
Note: in version 0.2 the $sEvent argument of the addEvent method differs from the addHandler() method. The addEvent() method expects the event name to include the "on-" at the beginning ("onclick") whereas the addHandler() method expects the event name without the "on-" ("click"). This difference reflects the difference in the javascript between assigning the event property of an element, and assigning an event handler using the addEventListener() method. The difference has already been remedied in the development version of xajax in CVS which now treats "onclick" and "click" interchangeably in both methods.

[edit] addRemoveHandler (string $sTarget, string $sEvent, string $sHandler)

Adds a remove handler command message to the XML response.

Usage: 

$objResponse->addRemoveHandler("contentDiv", "onclick", "content_click");
  • $sTarget (string): contains the id of an HTML element
  • $sEvent (string): the event you wish to remove ("onclick", "onmouseover", etc.)
  • $sHandler (string): the name of a Javascript handler function that you want to remove

[edit] addIncludeScript (string $sFileName)

Adds an include script command message to the XML response.

Usage: 

$objResponse->addIncludeScript("functions.js");
  • $sFileName (string): URL of the Javascript file to include

[edit] getXML ()

Returns the XML to be returned from your function to the xajax processor on your page. Since xajax 0.2, you can also return an xajaxResponse object from your function directly, and xajax will automatically request the XML using this method call.

Usage: 

return $objResponse->getXML();
  • Return (string): response XML data

[edit] loadXML (string $sXML)

Adds the commands of the provided response XML output to this response object

Usage: 

$r1 = $objResponse1->getXML();
$objResponse2->loadXML($r1);
return $objResponse2->getXML();
  • $sXML (string): the response XML (returned from a getXML() method) to add to the end of this response object

[edit] Object Methods (protected)

[edit] _cmdXML (array $aAttributes, string $sData)

Generates XML from command data

  • $aAttributes (array): associative array of attributes
  • $sData (string): data
  • Return (string): XML command

[edit] _buildObjXml (mixed $var) {

Recursively serializes a data structure in XML so it can be sent to the client. It could be thought of as the opposite of xajax::_parseObjXml().

  • $var (mixed): data structure to serialize to XML
  • Return (string): serialized XML
Retrieved from "http://xajaxproject.org/wiki/Documentation:xajaxResponse.inc.php"