resources/mediawiki/mediawiki.api.category.js

   1 // library to assist with API calls on categories
   2
   3 ( function( mw, $ ) {
   4
   5         $.extend( mw.Api.prototype, {
   6                 /**
   7                  * Determine if a category exists
   8                  * @param {mw.Title}
   9                  * @param {Function} callback to pass boolean of category's existence
  10                  * @param {Function} optional callback to run if api error
  11                  * @return ajax call object
  12                  */
  13                 isCategory: function( title, callback, err ) {
  14                         var params = {
  15                                 'prop': 'categoryinfo',
  16                                 'titles': title.toString()
  17                         };
  18
  19                         var ok = function( data ) {
  20                                 var exists = false;
  21                                 if ( data.query && data.query.pages ) {
  22                                         $.each( data.query.pages, function( id, page ) {
  23                                                 if ( page.categoryinfo ) {
  24                                                         exists = true;
  25                                                 }
  26                                         } );
  27                                 }
  28                                 callback( exists );
  29                         };
  30
  31                         return this.get( params, { ok: ok, err: err } );
  32
  33                 },
  34
  35                 /**
  36                  * Get a list of categories that match a certain prefix.
  37                  *   e.g. given "Foo", return "Food", "Foolish people", "Foosball tables" ...
  38                  * @param {String} prefix to match
  39                  * @param {Function} callback to pass matched categories to
  40                  * @param {Function} optional callback to run if api error
  41                  * @return ajax call object
  42                  */
  43                 getCategoriesByPrefix: function( prefix, callback, err ) {
  44
  45                         // fetch with allpages to only get categories that have a corresponding description page.
  46                         var params = {
  47                                 'list': 'allpages',
  48                                 'apprefix': prefix,
  49                                 'apnamespace': mw.config.get('wgNamespaceIds').category
  50                         };
  51
  52                         var ok = function( data ) {
  53                                 var texts = [];
  54                                 if ( data.query && data.query.allpages ) {
  55                                         $.each( data.query.allpages, function( i, category ) {
  56                                                 texts.push( new mw.Title( category.title ).getNameText() );
  57                                         } );
  58                                 }
  59                                 callback( texts );
  60                         };
  61
  62                         return this.get( params, { ok: ok, err: err } );
  63
  64                 },
  65
  66
  67                 /**
  68                  * Get the categories that a particular page on the wiki belongs to
  69                  * @param {mw.Title}
  70                  * @param {Function} callback to pass categories to (or false, if title not found)
  71                  * @param {Function} optional callback to run if api error
  72                  * @param {Boolean} optional asynchronousness (default = true = async)
  73                  * @return ajax call object
  74                  */
  75                 getCategories: function( title, callback, err, async ) {
  76                         var params = {
  77                                 prop: 'categories',
  78                                 titles: title.toString()
  79                         };
  80                         if ( async === undefined ) {
  81                                 async = true;
  82                         }
  83
  84                         var ok = function( data ) {
  85                                 var ret = false;
  86                                 if ( data.query && data.query.pages ) {
  87                                         $.each( data.query.pages, function( id, page ) {
  88                                                 if ( page.categories ) {
  89                                                         if ( typeof ret !== 'object' ) {
  90                                                                 ret = [];
  91                                                         }
  92                                                         $.each( page.categories, function( i, cat ) {
  93                                                                 ret.push( new mw.Title( cat.title ) );
  94                                                         } );
  95                                                 }
  96                                         } );
  97                                 }
  98                                 callback( ret );
  99                         };
 100
 101                         return this.get( params, { ok: ok, err: err, async: async } );
 102
 103                 }
 104
 105         } );
 106 } )( window.mediaWiki, jQuery );