Wordpress 4.6-scripts

[autoinstalls/wordpress.git] / wp-includes / js / wp-util.js

diff --git a/wp-includes/js/wp-util.js b/wp-includes/js/wp-util.js
index 701ec3ea433ff7abff83b40d8ba182f961b880ed..527441dda9504c1c1eeb394117e23b164eb77620 100644 (file)
--- a/wp-includes/js/wp-util.js
+++ b/wp-includes/js/wp-util.js
@@ -1,3 +1,4 @@
+/* global _wpUtilSettings */
 window.wp = window.wp || {};
 
 (function ($) {
@@ -7,7 +8,7 @@ window.wp = window.wp || {};
        /**
         * wp.template( id )
         *
-        * Fetches a template by id.
+        * Fetch a JavaScript template for an id, and return a templating function for it.
         *
         * @param  {string} id   A string that corresponds to a DOM element with an id prefixed with "tmpl-".
         *                       For example, "attachment" maps to "tmpl-attachment".
@@ -15,6 +16,12 @@ window.wp = window.wp || {};
         */
        wp.template = _.memoize(function ( id ) {
                var compiled,
+                       /*
+                        * Underscore's default ERB-style templates are incompatible with PHP
+                        * when asp_tags is enabled, so WordPress uses Mustache-inspired templating syntax.
+                        *
+                        * @see trac ticket #22344.
+                        */
                        options = {
                                evaluate:    /<#([\s\S]+?)#>/g,
                                interpolate: /\{\{\{([\s\S]+?)\}\}\}/g,
@@ -23,7 +30,7 @@ window.wp = window.wp || {};
                        };
 
                return function ( data ) {
-                       compiled = compiled || _.template( $( '#tmpl-' + id ).html(), null, options );
+                       compiled = compiled || _.template( $( '#tmpl-' + id ).html(),  options );
                        return compiled( data );
                };
        });
@@ -41,9 +48,11 @@ window.wp = window.wp || {};
                 *
                 * Sends a POST request to WordPress.
                 *
-                * @param  {string} action The slug of the action to fire in WordPress.
-                * @param  {object} data   The data to populate $_POST with.
-                * @return {$.promise}     A jQuery promise that represents the request.
+                * @param  {(string|object)} action  The slug of the action to fire in WordPress or options passed
+                *                                   to jQuery.ajax.
+                * @param  {object=}         data    Optional. The data to populate $_POST with.
+                * @return {$.promise}     A jQuery promise that represents the request,
+                *                         decorated with an abort() method.
                 */
                post: function( action, data ) {
                        return wp.ajax.send({
@@ -56,11 +65,14 @@ window.wp = window.wp || {};
                 *
                 * Sends a POST request to WordPress.
                 *
-                * @param  {string} action  The slug of the action to fire in WordPress.
-                * @param  {object} options The options passed to jQuery.ajax.
-                * @return {$.promise}      A jQuery promise that represents the request.
+                * @param  {(string|object)} action  The slug of the action to fire in WordPress or options passed
+                *                                   to jQuery.ajax.
+                * @param  {object=}         options Optional. The options passed to jQuery.ajax.
+                * @return {$.promise}      A jQuery promise that represents the request,
+                *                          decorated with an abort() method.
                 */
                send: function( action, options ) {
+                       var promise, deferred;
                        if ( _.isObject( action ) ) {
                                options = action;
                        } else {
@@ -74,7 +86,7 @@ window.wp = window.wp || {};
                                context: this
                        });
 
-                       return $.Deferred( function( deferred ) {
+                       deferred = $.Deferred( function( deferred ) {
                                // Transfer success/error callbacks.
                                if ( options.success )
                                        deferred.done( options.success );
@@ -85,9 +97,8 @@ window.wp = window.wp || {};
                                delete options.error;
 
                                // Use with PHP's wp_send_json_success() and wp_send_json_error()
-                               $.ajax( options ).done( function( response ) {
-                                       // Treat a response of `1` as successful for backwards
-                                       // compatibility with existing handlers.
+                               deferred.jqXHR = $.ajax( options ).done( function( response ) {
+                                       // Treat a response of 1 as successful for backward compatibility with existing handlers.
                                        if ( response === '1' || response === 1 )
                                                response = { success: true };
 
@@ -98,7 +109,15 @@ window.wp = window.wp || {};
                                }).fail( function() {
                                        deferred.rejectWith( this, arguments );
                                });
-                       }).promise();
+                       });
+
+                       promise = deferred.promise();
+                       promise.abort = function() {
+                               deferred.jqXHR.abort();
+                               return this;
+                       };
+
+                       return promise;
                }
        };