[Summary view] [Print] [Text view]

   1  /**
   2   * @class mw.Api.plugin.category
   3   */
   4  ( function ( mw, $ ) {
   5  
   6      var msg = 'Use of mediawiki.api callback params is deprecated. Use the Promise instead.';
   7      $.extend( mw.Api.prototype, {
   8          /**
   9           * Determine if a category exists.
  10           *
  11           * @param {mw.Title|string} title
  12           * @param {Function} [ok] Success callback (deprecated)
  13           * @param {Function} [err] Error callback (deprecated)
  14           * @return {jQuery.Promise}
  15           * @return {Function} return.done
  16           * @return {boolean} return.done.isCategory Whether the category exists.
  17           */
  18          isCategory: function ( title, ok, err ) {
  19              var apiPromise = this.get( {
  20                  prop: 'categoryinfo',
  21                  titles: String( title )
  22              } );
  23  
  24              if ( ok || err ) {
  25                  mw.track( 'mw.deprecate', 'api.cbParam' );
  26                  mw.log.warn( msg );
  27              }
  28  
  29              return apiPromise
  30                  .then( function ( data ) {
  31                      var exists = false;
  32                      if ( data.query && data.query.pages ) {
  33                          $.each( data.query.pages, function ( id, page ) {
  34                              if ( page.categoryinfo ) {
  35                                  exists = true;
  36                              }
  37                          } );
  38                      }
  39                      return exists;
  40                  } )
  41                  .done( ok )
  42                  .fail( err )
  43                  .promise( { abort: apiPromise.abort } );
  44          },
  45  
  46          /**
  47           * Get a list of categories that match a certain prefix.
  48           *
  49           * E.g. given "Foo", return "Food", "Foolish people", "Foosball tables"...
  50           *
  51           * @param {string} prefix Prefix to match.
  52           * @param {Function} [ok] Success callback (deprecated)
  53           * @param {Function} [err] Error callback (deprecated)
  54           * @return {jQuery.Promise}
  55           * @return {Function} return.done
  56           * @return {string[]} return.done.categories Matched categories
  57           */
  58          getCategoriesByPrefix: function ( prefix, ok, err ) {
  59              // Fetch with allpages to only get categories that have a corresponding description page.
  60              var apiPromise = this.get( {
  61                  list: 'allpages',
  62                  apprefix: prefix,
  63                  apnamespace: mw.config.get( 'wgNamespaceIds' ).category
  64              } );
  65  
  66              if ( ok || err ) {
  67                  mw.track( 'mw.deprecate', 'api.cbParam' );
  68                  mw.log.warn( msg );
  69              }
  70  
  71              return apiPromise
  72                  .then( function ( data ) {
  73                      var texts = [];
  74                      if ( data.query && data.query.allpages ) {
  75                          $.each( data.query.allpages, function ( i, category ) {
  76                              texts.push( new mw.Title( category.title ).getMainText() );
  77                          } );
  78                      }
  79                      return texts;
  80                  } )
  81                  .done( ok )
  82                  .fail( err )
  83                  .promise( { abort: apiPromise.abort } );
  84          },
  85  
  86          /**
  87           * Get the categories that a particular page on the wiki belongs to.
  88           *
  89           * @param {mw.Title|string} title
  90           * @param {Function} [ok] Success callback (deprecated)
  91           * @param {Function} [err] Error callback (deprecated)
  92           * @param {boolean} [async=true] Asynchronousness (deprecated)
  93           * @return {jQuery.Promise}
  94           * @return {Function} return.done
  95           * @return {boolean|mw.Title[]} return.done.categories List of category titles or false
  96           *  if title was not found.
  97           */
  98          getCategories: function ( title, ok, err, async ) {
  99              var apiPromise = this.get( {
 100                  prop: 'categories',
 101                  titles: String( title )
 102              }, {
 103                  async: async === undefined ? true : async
 104              } );
 105  
 106              if ( ok || err ) {
 107                  mw.track( 'mw.deprecate', 'api.cbParam' );
 108                  mw.log.warn( msg );
 109              }
 110              if ( async !== undefined ) {
 111                  mw.track( 'mw.deprecate', 'api.async' );
 112                  mw.log.warn(
 113                      'Use of mediawiki.api async=false param is deprecated. ' +
 114                      'The sychronous mode will be removed in the future.'
 115                  );
 116              }
 117  
 118              return apiPromise
 119                  .then( function ( data ) {
 120                      var titles = false;
 121                      if ( data.query && data.query.pages ) {
 122                          $.each( data.query.pages, function ( id, page ) {
 123                              if ( page.categories ) {
 124                                  if ( titles === false ) {
 125                                      titles = [];
 126                                  }
 127                                  $.each( page.categories, function ( i, cat ) {
 128                                      titles.push( new mw.Title( cat.title ) );
 129                                  } );
 130                              }
 131                          } );
 132                      }
 133                      return titles;
 134                  } )
 135                  .done( ok )
 136                  .fail( err )
 137                  .promise( { abort: apiPromise.abort } );
 138          }
 139      } );
 140  
 141      /**
 142       * @class mw.Api
 143       * @mixins mw.Api.plugin.category
 144       */
 145  
 146  }( mediaWiki, jQuery ) );