WP_Ajax_Response::add( string|array $args = '' )

Appends data to an XML response based on given arguments.

Description

With $args defaults, extra data output would be:

<response action='{$action}_$id'>
 <$what id='$id' position='$position'>
     <response_data><![CDATA[$data]]></response_data>
 </$what>
</response>

Parameters

$args

(string|array) (Optional) An array or string of XML response arguments.

  • 'what'
    (string) XML-RPC response type. Used as a child element of <response>. Default 'object' (<object>).
  • 'action'
    (string|false) Value to use for the action attribute in <response>. Will be appended with _$id on output. If false, $action will default to the value of $_POST['action']. Default false.
  • 'id'
    (int|WP_Error) The response ID, used as the response type id attribute. Also accepts a WP_Error object if the ID does not exist. Default 0.
  • 'old_id'
    (int|false) The previous response ID. Used as the value for the response type old_id attribute. False hides the attribute. Default false.
  • 'position'
    (string) Value of the response type position attribute. Accepts 1 (bottom), -1 (top), html ID (after), or -html ID (before). Default 1 (bottom).
  • 'data'
    (string|WP_Error) The response content/message. Also accepts a WP_Error object if the ID does not exist.
  • 'supplemental'
    (array) An array of extra strings that will be output within a <supplemental> element as CDATA. Default empty array.

Default value: ''

Return

(string) XML response.

Source

File: wp-includes/class-wp-ajax-response.php 

	public function add( $args = '' ) {
		$defaults = array(
			'what' => 'object', 'action' => false,
			'id' => '0', 'old_id' => false,
			'position' => 1,
			'data' => '', 'supplemental' => array()
		);

		$r = wp_parse_args( $args, $defaults );

		$position = preg_replace( '/[^a-z0-9:_-]/i', '', $r['position'] );
		$id = $r['id'];
		$what = $r['what'];
		$action = $r['action'];
		$old_id = $r['old_id'];
		$data = $r['data'];

		if ( is_wp_error( $id ) ) {
			$data = $id;
			$id = 0;
		}

		$response = '';
		if ( is_wp_error( $data ) ) {
			foreach ( (array) $data->get_error_codes() as $code ) {
				$response .= "<wp_error code='$code'><![CDATA[" . $data->get_error_message( $code ) . "]]></wp_error>";
				if ( ! $error_data = $data->get_error_data( $code ) ) {
					continue;
				}
				$class = '';
				if ( is_object( $error_data ) ) {
					$class = ' class="' . get_class( $error_data ) . '"';
					$error_data = get_object_vars( $error_data );
				}

				$response .= "<wp_error_data code='$code'$class>";

				if ( is_scalar( $error_data ) ) {
					$response .= "<![CDATA[$error_data]]>";
				} elseif ( is_array( $error_data ) ) {
					foreach ( $error_data as $k => $v ) {
						$response .= "<$k><![CDATA[$v]]></$k>";
					}
				}

				$response .= "</wp_error_data>";
			}
		} else {
			$response = "<response_data><![CDATA[$data]]></response_data>";
		}

		$s = '';
		if ( is_array( $r['supplemental'] ) ) {
			foreach ( $r['supplemental'] as $k => $v ) {
				$s .= "<$k><![CDATA[$v]]></$k>";
			}
			$s = "<supplemental>$s</supplemental>";
		}

		if ( false === $action ) {
			$action = $_POST['action'];
		}
		$x = '';
		$x .= "<response action='{$action}_$id'>"; // The action attribute in the xml output is formatted like a nonce action
		$x .=	"<$what id='$id' " . ( false === $old_id ? '' : "old_id='$old_id' " ) . "position='$position'>";
		$x .=		$response;
		$x .=		$s;
		$x .=	"</$what>";
		$x .= "</response>";

		$this->responses[] = $x;
		return $x;
	}

Expand Source Code View on GitHub

Related

Uses

Uses
Uses Description
wp-includes/load.php: is_wp_error()

Check whether variable is a ClassicPress Error.
wp-includes/functions.php: wp_parse_args()

Merge user defined arguments into defaults array.

Changelog

Changelog
Version Description
WP-2.1.0 Introduced.