resources/src/mediawiki/api/options.js

   1 /**
   2  * @class mw.Api.plugin.options
   3  */
   4 ( function ( mw, $ ) {
   5
   6         $.extend( mw.Api.prototype, {
   7
   8                 /**
   9                  * Asynchronously save the value of a single user option using the API. See #saveOptions.
  10                  *
  11                  * @param {string} name
  12                  * @param {string|null} value
  13                  * @return {jQuery.Promise}
  14                  */
  15                 saveOption: function ( name, value ) {
  16                         var param = {};
  17                         param[ name ] = value;
  18                         return this.saveOptions( param );
  19                 },
  20
  21                 /**
  22                  * Asynchronously save the values of user options using the API.
  23                  *
  24                  * If a value of `null` is provided, the given option will be reset to the default value.
  25                  *
  26                  * Any warnings returned by the API, including warnings about invalid option names or values,
  27                  * are ignored. However, do not rely on this behavior.
  28                  *
  29                  * If necessary, the options will be saved using several parallel API requests. Only one promise
  30                  * is always returned that will be resolved when all requests complete.
  31                  *
  32                  * @param {Object} options Options as a `{ name: value, … }` object
  33                  * @return {jQuery.Promise}
  34                  */
  35                 saveOptions: function ( options ) {
  36                         var name, value, bundleable,
  37                                 grouped = [],
  38                                 deferreds = [];
  39
  40                         for ( name in options ) {
  41                                 value = options[ name ] === null ? null : String( options[ name ] );
  42
  43                                 // Can we bundle this option, or does it need a separate request?
  44                                 if ( this.defaults.useUS ) {
  45                                         bundleable = name.indexOf( '=' ) === -1;
  46                                 } else {
  47                                         bundleable =
  48                                                 ( value === null || value.indexOf( '|' ) === -1 ) &&
  49                                                 ( name.indexOf( '|' ) === -1 && name.indexOf( '=' ) === -1 );
  50                                 }
  51
  52                                 if ( bundleable ) {
  53                                         if ( value !== null ) {
  54                                                 grouped.push( name + '=' + value );
  55                                         } else {
  56                                                 // Omitting value resets the option
  57                                                 grouped.push( name );
  58                                         }
  59                                 } else {
  60                                         if ( value !== null ) {
  61                                                 deferreds.push( this.postWithToken( 'csrf', {
  62                                                         formatversion: 2,
  63                                                         action: 'options',
  64                                                         optionname: name,
  65                                                         optionvalue: value
  66                                                 } ) );
  67                                         } else {
  68                                                 // Omitting value resets the option
  69                                                 deferreds.push( this.postWithToken( 'csrf', {
  70                                                         formatversion: 2,
  71                                                         action: 'options',
  72                                                         optionname: name
  73                                                 } ) );
  74                                         }
  75                                 }
  76                         }
  77
  78                         if ( grouped.length ) {
  79                                 deferreds.push( this.postWithToken( 'csrf', {
  80                                         formatversion: 2,
  81                                         action: 'options',
  82                                         change: grouped
  83                                 } ) );
  84                         }
  85
  86                         return $.when.apply( $, deferreds );
  87                 }
  88
  89         } );
  90
  91         /**
  92          * @class mw.Api
  93          * @mixins mw.Api.plugin.options
  94          */
  95
  96 }( mediaWiki, jQuery ) );