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 apiPromise = this.get( {
  19                                 prop: 'categoryinfo',
  20                                 titles: String( title )
  21                         } );
  22
  23                         // Backwards compatibility (< MW 1.20)
  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                         // Backwards compatibility (< MW 1.20)
  67                         if ( ok || err ) {
  68                                 mw.track( 'mw.deprecate', 'api.cbParam' );
  69                                 mw.log.warn( msg );
  70                         }
  71
  72                         return apiPromise
  73                                 .then( function ( data ) {
  74                                         var texts = [];
  75                                         if ( data.query && data.query.allpages ) {
  76                                                 $.each( data.query.allpages, function ( i, category ) {
  77                                                         texts.push( new mw.Title( category.title ).getNameText() );
  78                                                 } );
  79                                         }
  80                                         return texts;
  81                                 } )
  82                                 .done( ok )
  83                                 .fail( err )
  84                                 .promise( { abort: apiPromise.abort } );
  85                 },
  86
  87                 /**
  88                  * Get the categories that a particular page on the wiki belongs to
  89                  * @param {mw.Title} title
  90                  * @param {Function} [ok] Success callback (deprecated)
  91                  * @param {Function} [err] Error callback (deprecated)
  92                  * @param {boolean} [async=true] Asynchronousness
  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                         // Backwards compatibility (< MW 1.20)
 107                         if ( ok || err ) {
 108                                 mw.track( 'mw.deprecate', 'api.cbParam' );
 109                                 mw.log.warn( msg );
 110                         }
 111
 112                         return apiPromise
 113                                 .then( function ( data ) {
 114                                         var titles = false;
 115                                         if ( data.query && data.query.pages ) {
 116                                                 $.each( data.query.pages, function ( id, page ) {
 117                                                         if ( page.categories ) {
 118                                                                 if ( titles === false ) {
 119                                                                         titles = [];
 120                                                                 }
 121                                                                 $.each( page.categories, function ( i, cat ) {
 122                                                                         titles.push( new mw.Title( cat.title ) );
 123                                                                 } );
 124                                                         }
 125                                                 } );
 126                                         }
 127                                         return titles;
 128                                 } )
 129                                 .done( ok )
 130                                 .fail( err )
 131                                 .promise( { abort: apiPromise.abort } );
 132                 }
 133
 134         } );
 135
 136         /**
 137          * @class mw.Api
 138          * @mixins mw.Api.plugin.category
 139          */
 140
 141 }( mediaWiki, jQuery ) );