Class Reference/WP Ajax Response
Role of WP_Ajax_Response
WP_Ajax_Response is WordPress' class for generating XML-formatted responses to Ajax requests. This is most commonly used to generate responses to custom AJAX actions when using the wp_ajax_ action hook.
Methods and Properties
- An array that stores the XML responses to be sent.
- Constructor (PHP4-compatible). If provided arguments, it passes them directly to the add method.
- This method takes an associative array of various options to be used in the AJAX response XML.
- This will set the correct content type for the header, output the response xml, then die - ensuring a proper XML response.
To use WP_Ajax_Response, you need to instantiate the class with an array of options, then call the instances
send() method to output the response.
The options array takes the following key=>value pairs:
- A string containing the XMLRPC response type (used as the name of the xml element).
- A boolean or string that will behave like a nonce. This is added to the response element's action attribute.
- This is either an integer (usually 1) or a WP_Error object (if you need to return an error). Most commonly, the id value is used as a boolean, where 1 is a success and 0 is a failure.
- This is
falseby default, but you can alternatively provide an integer for the previous id, if needed.
- This is an integer or a string where -1 = top, 1 = bottom, 'html ID' = after, '-html ID' = before
- A string containing output content or a message (such as html). This is disregarded if you pass a WP_Error object as the id.
- This can an associative array of strings, which will be rendered into children of the
<supplemental>element. Keys become element names, and values are embedded in CDATA within those elements. Useful for passing additional information to the browser.
A typical WordPress autosave response looks like this:
<?xml version='1.0' standalone='yes'?> <wp_ajax> <response action='autosave_1'> <autosave id='1' position='1'> <response_data> <![CDATA[Draft saved at 9:31:55 pm.]]> </response_data> <supplemental></supplemental> </autosave> </response> </wp_ajax>
Let's break this example down to see what it means:
- This the root element of every response. All responses made by the WP_Ajax_Response class are wrapped in the
- Immediately within the wp_ajax element is
<response>, which contains the attributes 'action' and 'position'. These attributes correspond to the 'action' and 'position' key=>value pairs defined in the options array.
- <autosave> (arbitrary)
- Next, the above example shows an
<autosave>element - this element matches the value of the 'what' key=>value pair in the options array. In your own use, this element can be named whatever you like, provided it is a valid XML element name.
- <response_data> / <wp_error_data>
- Within the custom response element (e.g.
<autosave>), there will either be a
<response_data>element (with CDATA tag) or a
<wp_error_data>element. If you pass a WP_Error object to WP_Ajax_Response as the 'id' in your options array, the
<wp_error_data>element is automatically generated. Otherwise, the
<response_data>element is used with whatever value you passed to WP_Ajax_Response with your option array's "data" value.
- For the most part, any content you want to pass back to the browser (such as HTML), can be passed in your option array's "data" key=>value pair.
- Finally, the
<supplemental>element will contain whatever arbitrary structure you decide to pass along with your option array's "supplemental" key=>value pair.
Typical Response Example
This demonstrates a typical response. The first code block shows the PHP required to create a simple response. The second code block shows the generated XML.
$response = array( 'what'=>'foobar', 'action'=>'update_something', 'id'=>'1', 'data'=>'<p><strong>Hello world!</strong></p>' ); $xmlResponse = new WP_Ajax_Response($response); $xmlResponse->send();
The above example would output the following XML:
<?xml version='1.0' standalone='yes'?> <wp_ajax> <response action='update_something_1'> <foobar id='1' position='1'> <response_data><![CDATA[<p><strong>Hello world!</strong></p>]]></response_data> <supplemental></supplemental> </foobar> </response> </wp_ajax>
Error Response Example
This demonstrates a typical error response. The first code block shows the PHP required to generate such a response, and the second code block shows the generated XML output. Note that you can just as easily give your response an id of
0 instead of generating a new WP_Error. The choice is up to you.
$response = array( 'what'=>'stuff', 'action'=>'delete_something', 'id'=>new WP_Error('oops','I had an accident.'), 'data'=>'Whoops, there was a problem!' ); $xmlResponse = new WP_Ajax_Response($response); $xmlResponse->send();
The above example would output the following XML:
<?xml version='1.0' standalone='yes'?> <wp_ajax> <response action='delete_something_0'> <stuff id='0' position='1'> <wp_error code='oops'><![CDATA[I had an accident.]]></wp_error> <supplemental></supplemental> </stuff> </response> </wp_ajax>
Note how this response completely disregards our 'data' value.
The WP_Ajax_Response class is located in the file onlyincludecode/wp-includes/class-wp-ajax-response.php/code/onlyinclude
div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9
Link to the source code on http://core.trac.wordpress.org/browser/.
- (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.
Link to the stable version: pre检查到模板循环：模板:Trac/pre
Link to trunk: pre检查到模板循环：模板:Trac/pre