resources/mediawiki/mediawiki.user.js

   1 /*
   2  * Implementation for mediaWiki.user
   3  */
   4
   5 (function( $ ) {
   6
   7         /**
   8          * User object
   9          */
  10         function User( options, tokens ) {
  11
  12                 /* Private Members */
  13
  14                 var that = this;
  15                 var api = new mw.Api();
  16                 var groupsDeferred;
  17                 var rightsDeferred;
  18
  19                 /* Public Members */
  20
  21                 this.options = options || new mw.Map();
  22
  23                 this.tokens = tokens || new mw.Map();
  24
  25                 /* Public Methods */
  26
  27                 /**
  28                  * Generates a random user session ID (32 alpha-numeric characters).
  29                  *
  30                  * This information would potentially be stored in a cookie to identify a user during a
  31                  * session or series of sessions. Its uniqueness should not be depended on.
  32                  *
  33                  * @return String: Random set of 32 alpha-numeric characters
  34                  */
  35                 function generateId() {
  36                         var id = '';
  37                         var seed = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
  38                         for ( var i = 0, r; i < 32; i++ ) {
  39                                 r = Math.floor( Math.random() * seed.length );
  40                                 id += seed.substring( r, r + 1 );
  41                         }
  42                         return id;
  43                 }
  44
  45                 /**
  46                  * Gets the current user's name.
  47                  *
  48                  * @return Mixed: User name string or null if users is anonymous
  49                  */
  50                 this.getName = function () {
  51                         return mw.config.get( 'wgUserName' );
  52                 };
  53
  54                 /**
  55                  * @deprecated since 1.20 use mw.user.getName() instead
  56                  */
  57                 this.name = function () {
  58                         return this.getName();
  59                 };
  60
  61                 /**
  62                  * Checks if the current user is anonymous.
  63                  *
  64                  * @return Boolean
  65                  */
  66                 this.isAnon = function () {
  67                         return that.getName() === null;
  68                 };
  69
  70                 /**
  71                  * @deprecated since 1.20 use mw.user.isAnon() instead
  72                  */
  73                 this.anonymous = function () {
  74                         return that.isAnon();
  75                 };
  76
  77                 /**
  78                  * Gets a random session ID automatically generated and kept in a cookie.
  79                  *
  80                  * This ID is ephemeral for everyone, staying in their browser only until they close
  81                  * their browser.
  82                  *
  83                  * @return String: User name or random session ID
  84                  */
  85                 this.sessionId = function () {
  86                         var sessionId = $.cookie( 'mediaWiki.user.sessionId' );
  87                         if ( typeof sessionId == 'undefined' || sessionId === null ) {
  88                                 sessionId = generateId();
  89                                 $.cookie( 'mediaWiki.user.sessionId', sessionId, { 'expires': null, 'path': '/' } );
  90                         }
  91                         return sessionId;
  92                 };
  93
  94                 /**
  95                  * Gets the current user's name or a random ID automatically generated and kept in a cookie.
  96                  *
  97                  * This ID is persistent for anonymous users, staying in their browser up to 1 year. The
  98                  * expiration time is reset each time the ID is queried, so in most cases this ID will
  99                  * persist until the browser's cookies are cleared or the user doesn't visit for 1 year.
 100                  *
 101                  * @return String: User name or random session ID
 102                  */
 103                 this.id = function() {
 104                         var name = that.getName();
 105                         if ( name ) {
 106                                 return name;
 107                         }
 108                         var id = $.cookie( 'mediaWiki.user.id' );
 109                         if ( typeof id == 'undefined' || id === null ) {
 110                                 id = generateId();
 111                         }
 112                         // Set cookie if not set, or renew it if already set
 113                         $.cookie( 'mediaWiki.user.id', id, { 'expires': 365, 'path': '/' } );
 114                         return id;
 115                 };
 116
 117                 /**
 118                  * Gets the user's bucket, placing them in one at random based on set odds if needed.
 119                  *
 120                  * @param key String: Name of bucket
 121                  * @param options Object: Bucket configuration options
 122                  * @param options.buckets Object: List of bucket-name/relative-probability pairs (required,
 123                  * must have at least one pair)
 124                  * @param options.version Number: Version of bucket test, changing this forces rebucketing
 125                  * (optional, default: 0)
 126                  * @param options.tracked Boolean: Track the event of bucketing through the API module of
 127                  * the ClickTracking extension (optional, default: false)
 128                  * @param options.expires Number: Length of time (in days) until the user gets rebucketed
 129                  * (optional, default: 30)
 130                  * @return String: Bucket name - the randomly chosen key of the options.buckets object
 131                  *
 132                  * @example
 133                  *     mw.user.bucket( 'test', {
 134                  *         'buckets': { 'ignored': 50, 'control': 25, 'test': 25 },
 135                  *         'version': 1,
 136                  *         'tracked': true,
 137                  *         'expires': 7
 138                  *     } );
 139                  */
 140                 this.bucket = function( key, options ) {
 141                         options = $.extend( {
 142                                 'buckets': {},
 143                                 'version': 0,
 144                                 'tracked': false,
 145                                 'expires': 30
 146                         }, options || {} );
 147                         var cookie = $.cookie( 'mediaWiki.user.bucket:' + key );
 148                         var bucket = null;
 149                         var version = 0;
 150                         // Bucket information is stored as 2 integers, together as version:bucket like: "1:2"
 151                         if ( typeof cookie === 'string' && cookie.length > 2 && cookie.indexOf( ':' ) > 0 ) {
 152                                 var parts = cookie.split( ':' );
 153                                 if ( parts.length > 1 && parts[0] == options.version ) {
 154                                         version = Number( parts[0] );
 155                                         bucket = String( parts[1] );
 156                                 }
 157                         }
 158                         if ( bucket === null ) {
 159                                 if ( !$.isPlainObject( options.buckets ) ) {
 160                                         throw 'Invalid buckets error. Object expected for options.buckets.';
 161                                 }
 162                                 version = Number( options.version );
 163                                 // Find range
 164                                 var     range = 0, k;
 165                                 for ( k in options.buckets ) {
 166                                         range += options.buckets[k];
 167                                 }
 168                                 // Select random value within range
 169                                 var rand = Math.random() * range;
 170                                 // Determine which bucket the value landed in
 171                                 var total = 0;
 172                                 for ( k in options.buckets ) {
 173                                         bucket = k;
 174                                         total += options.buckets[k];
 175                                         if ( total >= rand ) {
 176                                                 break;
 177                                         }
 178                                 }
 179                                 if ( options.tracked ) {
 180                                         mw.loader.using( 'jquery.clickTracking', function() {
 181                                                 $.trackAction(
 182                                                         'mediaWiki.user.bucket:' + key + '@' + version + ':' + bucket
 183                                                 );
 184                                         } );
 185                                 }
 186                                 $.cookie(
 187                                         'mediaWiki.user.bucket:' + key,
 188                                         version + ':' + bucket,
 189                                         { 'path': '/', 'expires': Number( options.expires ) }
 190                                 );
 191                         }
 192                         return bucket;
 193                 };
 194
 195                 /**
 196                  * Gets the current user's groups.
 197                  */
 198                 this.getGroups = function ( callback ) {
 199                         if ( groupsDeferred ) {
 200                                 groupsDeferred.always( callback );
 201                                 return;
 202                         }
 203
 204                         groupsDeferred = $.Deferred();
 205                         groupsDeferred.always( callback );
 206                         api.get( {
 207                                 action: 'query',
 208                                 meta: 'userinfo',
 209                                 uiprop: 'groups'
 210                         } ).done( function ( data ) {
 211                                 if ( data.query && data.query.userinfo && data.query.userinfo.groups ) {
 212                                         groupsDeferred.resolve( data.query.userinfo.groups );
 213                                 } else {
 214                                         groupsDeferred.reject( [] );
 215                                 }
 216                         } ).fail( function ( data ) {
 217                                         groupsDeferred.reject( [] );
 218                         } );
 219                 };
 220
 221                 /**
 222                  * Gets the current user's rights.
 223                  */
 224                 this.getRights = function ( callback ) {
 225                         if ( rightsDeferred ) {
 226                                 rightsDeferred.always( callback );
 227                                 return;
 228                         }
 229
 230                         rightsDeferred = $.Deferred();
 231                         rightsDeferred.always( callback );
 232                         api.get( {
 233                                 action: 'query',
 234                                 meta: 'userinfo',
 235                                 uiprop: 'rights'
 236                         } ).done( function ( data ) {
 237                                 if ( data.query && data.query.userinfo && data.query.userinfo.rights ) {
 238                                         rightsDeferred.resolve( data.query.userinfo.rights );
 239                                 } else {
 240                                         rightsDeferred.reject( [] );
 241                                 }
 242                         } ).fail( function ( data ) {
 243                                 rightsDeferred.reject( [] );
 244                         } );
 245                 };
 246         }
 247
 248         // Extend the skeleton mw.user from mediawiki.js
 249         // This is kind of ugly but we're stuck with this for b/c reasons
 250         mw.user = new User( mw.user.options, mw.user.tokens );
 251
 252 })(jQuery);