resources/src/mediawiki/mediawiki.user.js

   1 /**
   2  * @class mw.user
   3  * @singleton
   4  */
   5 ( function ( mw, $ ) {
   6         var user,
   7                 deferreds = {},
   8                 // Extend the skeleton mw.user from mediawiki.js
   9                 // This is kind of ugly but we're stuck with this for b/c reasons
  10                 options = mw.user.options || new mw.Map(),
  11                 tokens = mw.user.tokens || new mw.Map();
  12
  13         /**
  14          * Get the current user's groups or rights
  15          *
  16          * @private
  17          * @param {string} info One of 'groups' or 'rights'
  18          * @param {Function} [callback]
  19          * @return {jQuery.Promise}
  20          */
  21         function getUserInfo( info, callback ) {
  22                 var api;
  23                 if ( !deferreds[info] ) {
  24
  25                         deferreds.rights = $.Deferred();
  26                         deferreds.groups = $.Deferred();
  27
  28                         api = new mw.Api();
  29                         api.get( {
  30                                 action: 'query',
  31                                 meta: 'userinfo',
  32                                 uiprop: 'rights|groups'
  33                         } ).always( function ( data ) {
  34                                 var rights, groups;
  35                                 if ( data.query && data.query.userinfo ) {
  36                                         rights = data.query.userinfo.rights;
  37                                         groups = data.query.userinfo.groups;
  38                                 }
  39                                 deferreds.rights.resolve( rights || [] );
  40                                 deferreds.groups.resolve( groups || [] );
  41                         } );
  42
  43                 }
  44
  45                 return deferreds[info].done( callback ).promise();
  46         }
  47
  48         mw.user = user = {
  49                 options: options,
  50                 tokens: tokens,
  51
  52                 /**
  53                  * Generate a random user session ID (32 alpha-numeric characters)
  54                  *
  55                  * This information would potentially be stored in a cookie to identify a user during a
  56                  * session or series of sessions. Its uniqueness should not be depended on.
  57                  *
  58                  * @return {string} Random set of 32 alpha-numeric characters
  59                  */
  60                 generateRandomSessionId: function () {
  61                         var i, r,
  62                                 id = '',
  63                                 seed = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
  64                         for ( i = 0; i < 32; i++ ) {
  65                                 r = Math.floor( Math.random() * seed.length );
  66                                 id += seed.substring( r, r + 1 );
  67                         }
  68                         return id;
  69                 },
  70
  71                 /**
  72                  * Get the current user's database id
  73                  *
  74                  * Not to be confused with #id.
  75                  *
  76                  * @return {number} Current user's id, or 0 if user is anonymous
  77                  */
  78                 getId: function () {
  79                         return mw.config.get( 'wgUserId', 0 );
  80                 },
  81
  82                 /**
  83                  * Get the current user's name
  84                  *
  85                  * @return {string|null} User name string or null if user is anonymous
  86                  */
  87                 getName: function () {
  88                         return mw.config.get( 'wgUserName' );
  89                 },
  90
  91                 /**
  92                  * Get date user registered, if available
  93                  *
  94                  * @return {Date|boolean|null} Date user registered, or false for anonymous users, or
  95                  *  null when data is not available
  96                  */
  97                 getRegistration: function () {
  98                         var registration = mw.config.get( 'wgUserRegistration' );
  99                         if ( user.isAnon() ) {
 100                                 return false;
 101                         } else if ( registration === null ) {
 102                                 // Information may not be available if they signed up before
 103                                 // MW began storing this.
 104                                 return null;
 105                         } else {
 106                                 return new Date( registration );
 107                         }
 108                 },
 109
 110                 /**
 111                  * Whether the current user is anonymous
 112                  *
 113                  * @return {boolean}
 114                  */
 115                 isAnon: function () {
 116                         return user.getName() === null;
 117                 },
 118
 119                 /**
 120                  * Get an automatically generated random ID (stored in a session cookie)
 121                  *
 122                  * This ID is ephemeral for everyone, staying in their browser only until they close
 123                  * their browser.
 124                  *
 125                  * @return {string} Random session ID
 126                  */
 127                 sessionId: function () {
 128                         var sessionId = $.cookie( 'mediaWiki.user.sessionId' );
 129                         if ( sessionId === undefined || sessionId === null ) {
 130                                 sessionId = user.generateRandomSessionId();
 131                                 $.cookie( 'mediaWiki.user.sessionId', sessionId, { expires: null, path: '/' } );
 132                         }
 133                         return sessionId;
 134                 },
 135
 136                 /**
 137                  * Get the current user's name or the session ID
 138                  *
 139                  * Not to be confused with #getId.
 140                  *
 141                  * @return {string} User name or random session ID
 142                  */
 143                 id: function () {
 144                         return user.getName() || user.sessionId();
 145                 },
 146
 147                 /**
 148                  * Get the user's bucket (place them in one if not done already)
 149                  *
 150                  *     mw.user.bucket( 'test', {
 151                  *         buckets: { ignored: 50, control: 25, test: 25 },
 152                  *         version: 1,
 153                  *         expires: 7
 154                  *     } );
 155                  *
 156                  * @deprecated since 1.23
 157                  * @param {string} key Name of bucket
 158                  * @param {Object} options Bucket configuration options
 159                  * @param {Object} options.buckets List of bucket-name/relative-probability pairs (required,
 160                  *  must have at least one pair)
 161                  * @param {number} [options.version=0] Version of bucket test, changing this forces
 162                  *  rebucketing
 163                  * @param {number} [options.expires=30] Length of time (in days) until the user gets
 164                  *  rebucketed
 165                  * @return {string} Bucket name - the randomly chosen key of the `options.buckets` object
 166                  */
 167                 bucket: function ( key, options ) {
 168                         var cookie, parts, version, bucket,
 169                                 range, k, rand, total;
 170
 171                         options = $.extend( {
 172                                 buckets: {},
 173                                 version: 0,
 174                                 expires: 30
 175                         }, options || {} );
 176
 177                         cookie = $.cookie( 'mediaWiki.user.bucket:' + key );
 178
 179                         // Bucket information is stored as 2 integers, together as version:bucket like: "1:2"
 180                         if ( typeof cookie === 'string' && cookie.length > 2 && cookie.indexOf( ':' ) !== -1 ) {
 181                                 parts = cookie.split( ':' );
 182                                 if ( parts.length > 1 && Number( parts[0] ) === options.version ) {
 183                                         version = Number( parts[0] );
 184                                         bucket = String( parts[1] );
 185                                 }
 186                         }
 187
 188                         if ( bucket === undefined ) {
 189                                 if ( !$.isPlainObject( options.buckets ) ) {
 190                                         throw new Error( 'Invalid bucket. Object expected for options.buckets.' );
 191                                 }
 192
 193                                 version = Number( options.version );
 194
 195                                 // Find range
 196                                 range = 0;
 197                                 for ( k in options.buckets ) {
 198                                         range += options.buckets[k];
 199                                 }
 200
 201                                 // Select random value within range
 202                                 rand = Math.random() * range;
 203
 204                                 // Determine which bucket the value landed in
 205                                 total = 0;
 206                                 for ( k in options.buckets ) {
 207                                         bucket = k;
 208                                         total += options.buckets[k];
 209                                         if ( total >= rand ) {
 210                                                 break;
 211                                         }
 212                                 }
 213
 214                                 $.cookie(
 215                                         'mediaWiki.user.bucket:' + key,
 216                                         version + ':' + bucket,
 217                                         { path: '/', expires: Number( options.expires ) }
 218                                 );
 219                         }
 220
 221                         return bucket;
 222                 },
 223
 224                 /**
 225                  * Get the current user's groups
 226                  *
 227                  * @param {Function} [callback]
 228                  * @return {jQuery.Promise}
 229                  */
 230                 getGroups: function ( callback ) {
 231                         return getUserInfo( 'groups', callback );
 232                 },
 233
 234                 /**
 235                  * Get the current user's rights
 236                  *
 237                  * @param {Function} [callback]
 238                  * @return {jQuery.Promise}
 239                  */
 240                 getRights: function ( callback ) {
 241                         return getUserInfo( 'rights', callback );
 242                 }
 243         };
 244
 245         /**
 246          * @method name
 247          * @inheritdoc #getName
 248          * @deprecated since 1.20 Use #getName instead
 249          */
 250         mw.log.deprecate( user, 'name', user.getName, 'Use mw.user.getName instead.' );
 251
 252         /**
 253          * @method anonymous
 254          * @inheritdoc #isAnon
 255          * @deprecated since 1.20 Use #isAnon instead
 256          */
 257         mw.log.deprecate( user, 'anonymous', user.isAnon, 'Use mw.user.isAnon instead.' );
 258
 259 }( mediaWiki, jQuery ) );