resources/mediawiki.api/mediawiki.api.category.js

   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                  * @param {mw.Title} title
  11                  * @param {Function} [ok] Success callback (deprecated)
  12                  * @param {Function} [err] Error callback (deprecated)
  13                  * @return {jQuery.Promise}
  14                  * @return {Function} return.done
  15                  * @return {boolean} return.done.isCategory Whether the category exists.
  16                  */
  17                 isCategory: function ( title, ok, err ) {
  18                         var d = $.Deferred(),
  19                                 apiPromise;
  20
  21                         // Backwards compatibility (< MW 1.20)
  22                         if ( ok || err ) {
  23                                 mw.track( 'mw.deprecate', 'api.cbParam' );
  24                                 mw.log.warn( msg );
  25                                 d.done( ok ).fail( err );
  26                         }
  27
  28                         apiPromise = this.get( {
  29                                         prop: 'categoryinfo',
  30                                         titles: title.toString()
  31                                 } )
  32                                 .done( function ( data ) {
  33                                         var exists = false;
  34                                         if ( data.query && data.query.pages ) {
  35                                                 $.each( data.query.pages, function ( id, page ) {
  36                                                         if ( page.categoryinfo ) {
  37                                                                 exists = true;
  38                                                         }
  39                                                 } );
  40                                         }
  41                                         d.resolve( exists );
  42                                 } )
  43                                 .fail( d.reject );
  44
  45                         return d.promise( { abort: apiPromise.abort } );
  46                 },
  47
  48                 /**
  49                  * Get a list of categories that match a certain prefix.
  50                  *   e.g. given "Foo", return "Food", "Foolish people", "Foosball tables" ...
  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                         var d = $.Deferred(),
  60                                 apiPromise;
  61
  62                         // Backwards compatibility (< MW 1.20)
  63                         if ( ok || err ) {
  64                                 mw.track( 'mw.deprecate', 'api.cbParam' );
  65                                 mw.log.warn( msg );
  66                                 d.done( ok ).fail( err );
  67                         }
  68
  69                         // Fetch with allpages to only get categories that have a corresponding description page.
  70                         apiPromise = this.get( {
  71                                         list: 'allpages',
  72                                         apprefix: prefix,
  73                                         apnamespace: mw.config.get( 'wgNamespaceIds' ).category
  74                                 } )
  75                                 .done( function ( data ) {
  76                                         var texts = [];
  77                                         if ( data.query && data.query.allpages ) {
  78                                                 $.each( data.query.allpages, function ( i, category ) {
  79                                                         texts.push( new mw.Title( category.title ).getNameText() );
  80                                                 } );
  81                                         }
  82                                         d.resolve( texts );
  83                                 } )
  84                                 .fail( d.reject );
  85
  86                         return d.promise( { abort: apiPromise.abort } );
  87                 },
  88
  89
  90                 /**
  91                  * Get the categories that a particular page on the wiki belongs to
  92                  * @param {mw.Title} title
  93                  * @param {Function} [ok] Success callback (deprecated)
  94                  * @param {Function} [err] Error callback (deprecated)
  95                  * @param {boolean} [async=true] Asynchronousness
  96                  * @return {jQuery.Promise}
  97                  * @return {Function} return.done
  98                  * @return {boolean|mw.Title[]} return.done.categories List of category titles or false
  99                  *  if title was not found.
 100                  */
 101                 getCategories: function ( title, ok, err, async ) {
 102                         var d = $.Deferred(),
 103                                 apiPromise;
 104
 105                         // Backwards compatibility (< MW 1.20)
 106                         if ( ok || err ) {
 107                                 mw.track( 'mw.deprecate', 'api.cbParam' );
 108                                 mw.log.warn( msg );
 109                                 d.done( ok ).fail( err );
 110                         }
 111
 112                         apiPromise = this.get( {
 113                                         prop: 'categories',
 114                                         titles: title.toString()
 115                                 }, {
 116                                         async: async === undefined ? true : async
 117                                 } )
 118                                 .done( function ( data ) {
 119                                         var ret = false;
 120                                         if ( data.query && data.query.pages ) {
 121                                                 $.each( data.query.pages, function ( id, page ) {
 122                                                         if ( page.categories ) {
 123                                                                 if ( typeof ret !== 'object' ) {
 124                                                                         ret = [];
 125                                                                 }
 126                                                                 $.each( page.categories, function ( i, cat ) {
 127                                                                         ret.push( new mw.Title( cat.title ) );
 128                                                                 } );
 129                                                         }
 130                                                 } );
 131                                         }
 132                                         d.resolve( ret );
 133                                 } )
 134                                 .fail( d.reject );
 135
 136                         return d.promise( { abort: apiPromise.abort } );
 137                 }
 138
 139         } );
 140
 141         /**
 142          * @class mw.Api
 143          * @mixins mw.Api.plugin.category
 144          */
 145
 146 }( mediaWiki, jQuery ) );