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

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