resources/src/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                  *
  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 ) );