resources/src/mediawiki.api/messages.js

   1 /**
   2  * Allows to retrieve a specific or a set of
   3  * messages to be added to mw.messages and returned
   4  * by the Api.
   5  *
   6  * @class mw.Api.plugin.messages
   7  * @since 1.27
   8  */
   9 ( function () {
  10         'use strict';
  11
  12         $.extend( mw.Api.prototype, {
  13                 /**
  14                  * Get a set of messages.
  15                  *
  16                  * @param {Array} messages Messages to retrieve
  17                  * @param {Object} [options] Additional parameters for the API call
  18                  * @return {jQuery.Promise}
  19                  */
  20                 getMessages: function ( messages, options ) {
  21                         options = options || {};
  22                         return this.get( $.extend( {
  23                                 action: 'query',
  24                                 meta: 'allmessages',
  25                                 ammessages: messages,
  26                                 amlang: mw.config.get( 'wgUserLanguage' ),
  27                                 formatversion: 2
  28                         }, options ) ).then( function ( data ) {
  29                                 var result = {};
  30
  31                                 data.query.allmessages.forEach( function ( obj ) {
  32                                         if ( !obj.missing ) {
  33                                                 result[ obj.name ] = obj.content;
  34                                         }
  35                                 } );
  36
  37                                 return result;
  38                         } );
  39                 },
  40
  41                 /**
  42                  * Loads a set of messages and add them to mw.messages.
  43                  *
  44                  * @param {Array} messages Messages to retrieve
  45                  * @param {Object} [options] Additional parameters for the API call
  46                  * @return {jQuery.Promise}
  47                  */
  48                 loadMessages: function ( messages, options ) {
  49                         return this.getMessages( messages, options ).then( mw.messages.set.bind( mw.messages ) );
  50                 },
  51
  52                 /**
  53                  * Loads a set of messages and add them to mw.messages. Only messages that are not already known
  54                  * are loaded. If all messages are known, the returned promise is resolved immediately.
  55                  *
  56                  * @param {Array} messages Messages to retrieve
  57                  * @param {Object} [options] Additional parameters for the API call
  58                  * @return {jQuery.Promise}
  59                  */
  60                 loadMessagesIfMissing: function ( messages, options ) {
  61                         var missing = messages.filter( function ( msg ) {
  62                                 return !mw.message( msg ).exists();
  63                         } );
  64
  65                         if ( missing.length === 0 ) {
  66                                 return $.Deferred().resolve();
  67                         }
  68
  69                         return this.loadMessages( missing, options );
  70                 }
  71         } );
  72
  73         /**
  74          * @class mw.Api
  75          * @mixins mw.Api.plugin.messages
  76          */
  77
  78 }() );