From b0bcff1f60b456483a8d0fd464c97b174d7cc961 Mon Sep 17 00:00:00 2001 From: Timo Tijhof Date: Sun, 9 Jun 2013 11:21:44 +0200 Subject: [PATCH] mediawiki.user: Simplify implementation and jsduckify Similar to mediawiki.util: * Return plain object instead of an instantiated function. * Refer to local reference instead of 'this' which makes it possible to use all methods "detached" without needing a specific context bound. * Fix documentation comments be valid in jsduck syntax. - @example was invalid - "foo String : desc" was invalid, changed to: "{string} foo Desc" - type {false} was invalid, changed to {boolean} - reference mw.user.foo was invalid, changed to mw.user#foo. - getUserInfo was missing @private. * Include in JSDuck index. Change-Id: I2732cd7422f444b5cad1c6737a2de5dafb12d541 --- maintenance/jsduck/categories.json | 1 + maintenance/jsduck/config.json | 1 + resources/mediawiki/mediawiki.user.js | 178 +++++++++++++------------- 3 files changed, 89 insertions(+), 91 deletions(-) diff --git a/maintenance/jsduck/categories.json b/maintenance/jsduck/categories.json index 68e1fb2c73..df927b3ca8 100644 --- a/maintenance/jsduck/categories.json +++ b/maintenance/jsduck/categories.json @@ -21,6 +21,7 @@ "classes": [ "mw.Title", "mw.notification", + "mw.user", "mw.util", "mw.plugin.*" ] diff --git a/maintenance/jsduck/config.json b/maintenance/jsduck/config.json index 4ad75f00ff..46033fc7b7 100644 --- a/maintenance/jsduck/config.json +++ b/maintenance/jsduck/config.json @@ -14,6 +14,7 @@ "../../resources/mediawiki/mediawiki.Title.js", "../../resources/mediawiki/mediawiki.notify.js", "../../resources/mediawiki/mediawiki.notification.js", + "../../resources/mediawiki/mediawiki.user.js", "../../resources/mediawiki.api", "../../resources/jquery/jquery.localize.js" ] diff --git a/resources/mediawiki/mediawiki.user.js b/resources/mediawiki/mediawiki.user.js index 6cbe74c581..e8366a554a 100644 --- a/resources/mediawiki/mediawiki.user.js +++ b/resources/mediawiki/mediawiki.user.js @@ -1,57 +1,52 @@ -/* - * Implementation for mediaWiki.user +/** + * @class mw.user + * @singleton */ - ( function ( mw, $ ) { + var callbacks, options, tokens, user; /** - * User object + * Gets the current user's groups or rights. + * + * @private + * @param {string} info One of 'groups' or 'rights' + * @param {Function} callback */ - function User( options, tokens ) { - var user, callbacks; - - /* Private Members */ - - user = this; - callbacks = {}; - - /** - * Gets the current user's groups or rights. - * @param {String} info: One of 'groups' or 'rights'. - * @param {Function} callback - */ - function getUserInfo( info, callback ) { - var api; - if ( callbacks[info] ) { - callbacks[info].add( callback ); - return; - } - callbacks.rights = $.Callbacks('once memory'); - callbacks.groups = $.Callbacks('once memory'); + function getUserInfo( info, callback ) { + var api; + if ( callbacks[info] ) { callbacks[info].add( callback ); - api = new mw.Api(); - api.get( { - action: 'query', - meta: 'userinfo', - uiprop: 'rights|groups' - } ).always( function ( data ) { - var rights, groups; - if ( data.query && data.query.userinfo ) { - rights = data.query.userinfo.rights; - groups = data.query.userinfo.groups; - } - callbacks.rights.fire( rights || [] ); - callbacks.groups.fire( groups || [] ); - } ); + return; } + callbacks.rights = $.Callbacks('once memory'); + callbacks.groups = $.Callbacks('once memory'); + callbacks[info].add( callback ); + api = new mw.Api(); + api.get( { + action: 'query', + meta: 'userinfo', + uiprop: 'rights|groups' + } ).always( function ( data ) { + var rights, groups; + if ( data.query && data.query.userinfo ) { + rights = data.query.userinfo.rights; + groups = data.query.userinfo.groups; + } + callbacks.rights.fire( rights || [] ); + callbacks.groups.fire( groups || [] ); + } ); + } - /* Public Members */ - - this.options = options || new mw.Map(); + callbacks = {}; - this.tokens = tokens || new mw.Map(); + // Extend the skeleton mw.user from mediawiki.js + // This is kind of ugly but we're stuck with this for b/c reasons + options = mw.user.options || new mw.Map(); + tokens = mw.user.tokens || new mw.Map(); - /* Public Methods */ + mw.user = user = { + options: options, + tokens: tokens, /** * Generates a random user session ID (32 alpha-numeric characters). @@ -59,9 +54,9 @@ * This information would potentially be stored in a cookie to identify a user during a * session or series of sessions. Its uniqueness should not be depended on. * - * @return String: Random set of 32 alpha-numeric characters + * @return {string} Random set of 32 alpha-numeric characters */ - this.generateRandomSessionId = function () { + generateRandomSessionId: function () { var i, r, id = '', seed = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'; @@ -70,33 +65,34 @@ id += seed.substring( r, r + 1 ); } return id; - }; + }, /** * Gets the current user's name. * - * @return Mixed: User name string or null if users is anonymous + * @return {string|null} User name string or null if users is anonymous */ - this.getName = function () { + getName: function () { return mw.config.get( 'wgUserName' ); - }; + }, /** - * @deprecated since 1.20 use mw.user.getName() instead + * @inheritdoc #getName + * @deprecated since 1.20 use #getName instead */ - this.name = function () { - return this.getName(); - }; + name: function () { + return user.getName(); + }, /** * Get date user registered, if available. * - * @return {Date|false|null} date user registered, or false for anonymous users, or + * @return {Date|boolean|null} Date user registered, or false for anonymous users, or * null when data is not available */ - this.getRegistration = function () { + getRegistration: function () { var registration = mw.config.get( 'wgUserRegistration' ); - if ( this.isAnon() ) { + if ( user.isAnon() ) { return false; } else if ( registration === null ) { // Information may not be available if they signed up before @@ -105,23 +101,24 @@ } else { return new Date( registration ); } - }; + }, /** * Checks if the current user is anonymous. * - * @return Boolean + * @return {boolean} */ - this.isAnon = function () { + isAnon: function () { return user.getName() === null; - }; + }, /** - * @deprecated since 1.20 use mw.user.isAnon() instead + * @inheritdoc #isAnon + * @deprecated since 1.20 use #isAnon instead */ - this.anonymous = function () { + anonymous: function () { return user.isAnon(); - }; + }, /** * Gets a random ID automatically generated and stored in a session cookie. @@ -129,51 +126,50 @@ * This ID is ephemeral for everyone, staying in their browser only until they close * their browser. * - * @return String: random session ID + * @return {string} Random session ID */ - this.sessionId = function () { + sessionId: function () { var sessionId = $.cookie( 'mediaWiki.user.sessionId' ); if ( typeof sessionId === 'undefined' || sessionId === null ) { sessionId = user.generateRandomSessionId(); $.cookie( 'mediaWiki.user.sessionId', sessionId, { 'expires': null, 'path': '/' } ); } return sessionId; - }; + }, /** * Gets the current user's name or the session ID * * @return {string} User name or random session ID */ - this.id = function () { + id: function () { var name = user.getName(); if ( name ) { return name; } return user.sessionId(); - }; + }, /** * Gets the user's bucket, placing them in one at random based on set odds if needed. * - * @param key String: Name of bucket - * @param options Object: Bucket configuration options - * @param options.buckets Object: List of bucket-name/relative-probability pairs (required, - * must have at least one pair) - * @param options.version Number: Version of bucket test, changing this forces rebucketing - * (optional, default: 0) - * @param options.expires Number: Length of time (in days) until the user gets rebucketed - * (optional, default: 30) - * @return String: Bucket name - the randomly chosen key of the options.buckets object - * - * @example * mw.user.bucket( 'test', { * 'buckets': { 'ignored': 50, 'control': 25, 'test': 25 }, * 'version': 1, * 'expires': 7 * } ); + * + * @param {string} key Name of bucket + * @param {Object} options Bucket configuration options + * @param {Object} options.buckets List of bucket-name/relative-probability pairs (required, + * must have at least one pair) + * @param {number} options.version Version of bucket test, changing this forces rebucketing + * (optional, default: 0) + * @param {number} options.expires Length of time (in days) until the user gets rebucketed + * (optional, default: 30) + * @return {string} Bucket name - the randomly chosen key of the options.buckets object */ - this.bucket = function ( key, options ) { + bucket: function ( key, options ) { var cookie, parts, version, bucket, range, k, rand, total; @@ -221,25 +217,25 @@ ); } return bucket; - }; + }, /** * Gets the current user's groups. + * + * @param {Function} callback */ - this.getGroups = function ( callback ) { + getGroups: function ( callback ) { getUserInfo( 'groups', callback ); - }; + }, /** * Gets the current user's rights. + * + * @param {Function} callback */ - this.getRights = function ( callback ) { + getRights: function ( callback ) { getUserInfo( 'rights', callback ); - }; - } - - // Extend the skeleton mw.user from mediawiki.js - // This is kind of ugly but we're stuck with this for b/c reasons - mw.user = new User( mw.user.options, mw.user.tokens ); + } + }; }( mediaWiki, jQuery ) ); -- 2.20.1