wp-includes/js/wp-util.js

   1 /* global _wpUtilSettings */
   2 window.wp = window.wp || {};
   3
   4 (function ($) {
   5         // Check for the utility settings.
   6         var settings = typeof _wpUtilSettings === 'undefined' ? {} : _wpUtilSettings;
   7
   8         /**
   9          * wp.template( id )
  10          *
  11          * Fetch a JavaScript template for an id, and return a templating function for it.
  12          *
  13          * @param  {string} id   A string that corresponds to a DOM element with an id prefixed with "tmpl-".
  14          *                       For example, "attachment" maps to "tmpl-attachment".
  15          * @return {function}    A function that lazily-compiles the template requested.
  16          */
  17         wp.template = _.memoize(function ( id ) {
  18                 var compiled,
  19                         /*
  20                          * Underscore's default ERB-style templates are incompatible with PHP
  21                          * when asp_tags is enabled, so WordPress uses Mustache-inspired templating syntax.
  22                          *
  23                          * @see trac ticket #22344.
  24                          */
  25                         options = {
  26                                 evaluate:    /<#([\s\S]+?)#>/g,
  27                                 interpolate: /\{\{\{([\s\S]+?)\}\}\}/g,
  28                                 escape:      /\{\{([^\}]+?)\}\}(?!\})/g,
  29                                 variable:    'data'
  30                         };
  31
  32                 return function ( data ) {
  33                         compiled = compiled || _.template( $( '#tmpl-' + id ).html(), null, options );
  34                         return compiled( data );
  35                 };
  36         });
  37
  38         // wp.ajax
  39         // ------
  40         //
  41         // Tools for sending ajax requests with JSON responses and built in error handling.
  42         // Mirrors and wraps jQuery's ajax APIs.
  43         wp.ajax = {
  44                 settings: settings.ajax || {},
  45
  46                 /**
  47                  * wp.ajax.post( [action], [data] )
  48                  *
  49                  * Sends a POST request to WordPress.
  50                  *
  51                  * @param  {string} action The slug of the action to fire in WordPress.
  52                  * @param  {object} data   The data to populate $_POST with.
  53                  * @return {$.promise}     A jQuery promise that represents the request,
  54                  *                         decorated with an abort() method.
  55                  */
  56                 post: function( action, data ) {
  57                         return wp.ajax.send({
  58                                 data: _.isObject( action ) ? action : _.extend( data || {}, { action: action })
  59                         });
  60                 },
  61
  62                 /**
  63                  * wp.ajax.send( [action], [options] )
  64                  *
  65                  * Sends a POST request to WordPress.
  66                  *
  67                  * @param  {string} action  The slug of the action to fire in WordPress.
  68                  * @param  {object} options The options passed to jQuery.ajax.
  69                  * @return {$.promise}      A jQuery promise that represents the request,
  70                  *                          decorated with an abort() method.
  71                  */
  72                 send: function( action, options ) {
  73                         var promise, deferred;
  74                         if ( _.isObject( action ) ) {
  75                                 options = action;
  76                         } else {
  77                                 options = options || {};
  78                                 options.data = _.extend( options.data || {}, { action: action });
  79                         }
  80
  81                         options = _.defaults( options || {}, {
  82                                 type:    'POST',
  83                                 url:     wp.ajax.settings.url,
  84                                 context: this
  85                         });
  86
  87                         deferred = $.Deferred( function( deferred ) {
  88                                 // Transfer success/error callbacks.
  89                                 if ( options.success )
  90                                         deferred.done( options.success );
  91                                 if ( options.error )
  92                                         deferred.fail( options.error );
  93
  94                                 delete options.success;
  95                                 delete options.error;
  96
  97                                 // Use with PHP's wp_send_json_success() and wp_send_json_error()
  98                                 deferred.jqXHR = $.ajax( options ).done( function( response ) {
  99                                         // Treat a response of `1` as successful for backwards
 100                                         // compatibility with existing handlers.
 101                                         if ( response === '1' || response === 1 )
 102                                                 response = { success: true };
 103
 104                                         if ( _.isObject( response ) && ! _.isUndefined( response.success ) )
 105                                                 deferred[ response.success ? 'resolveWith' : 'rejectWith' ]( this, [response.data] );
 106                                         else
 107                                                 deferred.rejectWith( this, [response] );
 108                                 }).fail( function() {
 109                                         deferred.rejectWith( this, arguments );
 110                                 });
 111                         });
 112
 113                         promise = deferred.promise();
 114                         promise.abort = function() {
 115                                 deferred.jqXHR.abort();
 116                                 return this;
 117                         };
 118
 119                         return promise;
 120                 }
 121         };
 122
 123 }(jQuery));