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                 /**
  89                  * Get the categories that a particular page on the wiki belongs to
  90                  * @param {mw.Title} title
  91                  * @param {Function} [ok] Success callback (deprecated)
  92                  * @param {Function} [err] Error callback (deprecated)
  93                  * @param {boolean} [async=true] Asynchronousness
  94                  * @return {jQuery.Promise}
  95                  * @return {Function} return.done
  96                  * @return {boolean|mw.Title[]} return.done.categories List of category titles or false
  97                  *  if title was not found.
  98                  */
  99                 getCategories: function ( title, ok, err, async ) {
 100                         var apiPromise = this.get( {
 101                                 prop: 'categories',
 102                                 titles: String( title )
 103                         }, {
 104                                 async: async === undefined ? true : async
 105                         } );
 106
 107                         // Backwards compatibility (< MW 1.20)
 108                         if ( ok || err ) {
 109                                 mw.track( 'mw.deprecate', 'api.cbParam' );
 110                                 mw.log.warn( msg );
 111                         }
 112
 113                         return apiPromise
 114                                 .then( function ( data ) {
 115                                         var titles = false;
 116                                         if ( data.query && data.query.pages ) {
 117                                                 $.each( data.query.pages, function ( id, page ) {
 118                                                         if ( page.categories ) {
 119                                                                 if ( titles === false ) {
 120                                                                         titles = [];
 121                                                                 }
 122                                                                 $.each( page.categories, function ( i, cat ) {
 123                                                                         titles.push( new mw.Title( cat.title ) );
 124                                                                 } );
 125                                                         }
 126                                                 } );
 127                                         }
 128                                         return titles;
 129                                 } )
 130                                 .done( ok )
 131                                 .fail( err )
 132                                 .promise( { abort: apiPromise.abort } );
 133                 }
 134
 135         } );
 136
 137         /**
 138          * @class mw.Api
 139          * @mixins mw.Api.plugin.category
 140          */
 141
 142 }( mediaWiki, jQuery ) );