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

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