resources/mediawiki/mediawiki.user.js

   1 /*
   2  * Implementation for mediaWiki.log stub
   3  */
   4
   5 (function( $ ) {
   6
   7         /**
   8          * User object
   9          */
  10         function User() {
  11
  12                 /* Private Members */
  13
  14                 var that = this;
  15
  16                 /* Public Members */
  17
  18                 this.options = new mw.Map();
  19
  20                 /* Public Methods */
  21
  22                 /**
  23                  * Generates a random user session ID (32 alpha-numeric characters).
  24                  *
  25                  * This information would potentially be stored in a cookie to identify a user during a
  26                  * session or series of sessions. It's uniqueness should not be depended on.
  27                  *
  28                  * @return string random set of 32 alpha-numeric characters
  29                  */
  30                 function generateId() {
  31                         var id = '';
  32                         var seed = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
  33                         for ( var i = 0, r; i < 32; i++ ) {
  34                                 r = Math.floor( Math.random() * seed.length );
  35                                 id += seed.substring( r, r + 1 );
  36                         }
  37                         return id;
  38                 }
  39
  40                 /**
  41                  * Gets the current user's name.
  42                  *
  43                  * @return mixed user name string or null if users is anonymous
  44                  */
  45                 this.name = function() {
  46                         return mw.config.get( 'wgUserName' );
  47                 };
  48
  49                 /**
  50                  * Checks if the current user is anonymous.
  51                  *
  52                  * @return boolean
  53                  */
  54                 this.anonymous = function() {
  55                         return that.name() ? false : true;
  56                 };
  57
  58                 /**
  59                  * Gets a random session ID automatically generated and kept in a cookie.
  60                  *
  61                  * This ID is ephemeral for everyone, staying in their browser only until they close
  62                  * their browser.
  63                  *
  64                  * Do not use this method before the first call to mw.loader.go(), it depends on
  65                  * jquery.cookie, which is added to the first pay-load just after mediaWiki is defined, but
  66                  * won't be loaded until the first call to go().
  67                  *
  68                  * @return string user name or random session ID
  69                  */
  70                 this.sessionId = function () {
  71                         var sessionId = $.cookie( 'mediaWiki.user.sessionId' );
  72                         if ( typeof sessionId == 'undefined' || sessionId === null ) {
  73                                 sessionId = generateId();
  74                                 $.cookie( 'mediaWiki.user.sessionId', sessionId, { 'expires': null, 'path': '/' } );
  75                         }
  76                         return sessionId;
  77                 };
  78
  79                 /**
  80                  * Gets the current user's name or a random ID automatically generated and kept in a cookie.
  81                  *
  82                  * This ID is persistent for anonymous users, staying in their browser up to 1 year. The
  83                  * expiration time is reset each time the ID is queried, so in most cases this ID will
  84                  * persist until the browser's cookies are cleared or the user doesn't visit for 1 year.
  85                  *
  86                  * Do not use this method before the first call to mw.loader.go(), it depends on
  87                  * jquery.cookie, which is added to the first pay-load just after mediaWiki is defined, but
  88                  * won't be loaded until the first call to go().
  89                  *
  90                  * @return string user name or random session ID
  91                  */
  92                 this.id = function() {
  93                         var name = that.name();
  94                         if ( name ) {
  95                                 return name;
  96                         }
  97                         var id = $.cookie( 'mediaWiki.user.id' );
  98                         if ( typeof id == 'undefined' || id === null ) {
  99                                 id = generateId();
 100                         }
 101                         // Set cookie if not set, or renew it if already set
 102                         $.cookie( 'mediaWiki.user.id', id, { 'expires': 365, 'path': '/' } );
 103                         return id;
 104                 };
 105
 106                 /**
 107                  * Gets the user's bucket, placing them in one at random based on set odds if needed.
 108                  *
 109                  * @param key String: Name of bucket
 110                  * @param options Object: Bucket configuration options
 111                  * @param options.buckets Object: List of bucket-name/relative-probability pairs (required,
 112                  * must have at least one pair)
 113                  * @param options.version Number: Version of bucket test, changing this forces rebucketing
 114                  * (optional, default: 0)
 115                  * @param options.tracked Boolean: Track the event of bucketing through the API module of
 116                  * the ClickTracking extension (optional, default: false)
 117                  * @param options.expires Number: Length of time (in days) until the user gets rebucketed
 118                  * (optional, default: 30)
 119                  * @return String: Bucket name - the randomly chosen key of the options.buckets object
 120                  *
 121                  * @example
 122                  *     mw.user.bucket( 'test', {
 123                  *         'buckets': { 'ignored': 50, 'control': 25, 'test': 25 },
 124                  *         'version': 1,
 125                  *         'tracked': true,
 126                  *         'expires': 7
 127                  *     } );
 128                  */
 129                 this.bucket = function( key, options ) {
 130                         options = $.extend( {
 131                                 'buckets': {},
 132                                 'version': 0,
 133                                 'tracked': false,
 134                                 'expires': 30
 135                         }, options || {} );
 136                         var cookie = $.cookie( 'mediaWiki.user.bucket:' + key );
 137                         var bucket = null;
 138                         var version = 0;
 139                         // Bucket information is stored as 2 integers, together as version:bucket like: "1:2"
 140                         if ( typeof cookie === 'string' && cookie.length > 2 && cookie.indexOf( ':' ) > 0 ) {
 141                                 var parts = cookie.split( ':' );
 142                                 if ( parts.length > 1 && parts[0] == options.version ) {
 143                                         version = Number( parts[0] );
 144                                         bucket = String( parts[1] );
 145                                 }
 146                         }
 147                         if ( bucket === null ) {
 148                                 if ( !$.isPlainObject( options.buckets ) ) {
 149                                         throw 'Invalid buckets error. Object expected for options.buckets.';
 150                                 }
 151                                 version = Number( options.version );
 152                                 // Find range
 153                                 var     range = 0, k;
 154                                 for ( k in options.buckets ) {
 155                                         range += options.buckets[k];
 156                                 }
 157                                 // Select random value within range
 158                                 var rand = Math.random() * range;
 159                                 // Determine which bucket the value landed in
 160                                 var total = 0;
 161                                 for ( k in options.buckets ) {
 162                                         bucket = k;
 163                                         total += options.buckets[k];
 164                                         if ( total >= rand ) {
 165                                                 break;
 166                                         }
 167                                 }
 168                                 if ( options.tracked ) {
 169                                         mw.loader.using( 'jquery.clickTracking', function() {
 170                                                 $.trackAction(
 171                                                         'mediaWiki.user.bucket:' + key + '@' + version + ':' + bucket
 172                                                 );
 173                                         } );
 174                                 }
 175                                 $.cookie(
 176                                         'mediaWiki.user.bucket:' + key,
 177                                         version + ':' + bucket,
 178                                         { 'path': '/', 'expires': Number( options.expires ) }
 179                                 );
 180                         }
 181                         return bucket;
 182                 };
 183         }
 184
 185         mw.user = new User();
 186
 187 })(jQuery);