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