/**
* Creates an object that can be read from or written to from prototype functions
* that allow both single and multiple variables at once.
+ *
+ * @example
+ *
+ * var addies, wanted, results;
+ *
+ * // Create your address book
+ * addies = new mw.Map();
+ *
+ * // This data could be coming from an external source (eg. API/AJAX)
+ * addies.set( {
+ * 'John Doe' : '10 Wall Street, New York, USA',
+ * 'Jane Jackson' : '21 Oxford St, London, UK',
+ * 'Dominique van Halen' : 'Kalverstraat 7, Amsterdam, NL'
+ * } );
+ *
+ * wanted = ['Dominique van Halen', 'George Johnson', 'Jane Jackson'];
+ *
+ * // You can detect missing keys first
+ * if ( !addies.exists( wanted ) ) {
+ * // One or more are missing (in this case: "George Johnson")
+ * mw.log( 'One or more names were not found in your address book' );
+ * }
+ *
+ * // Or just let it give you what it can
+ * results = addies.get( wanted, 'Middle of Nowhere, Alaska, US' );
+ * mw.log( results['Jane Jackson'] ); // "21 Oxford St, London, UK"
+ * mw.log( results['George Johnson'] ); // "Middle of Nowhere, Alaska, US"
+ *
* @class mw.Map
*
* @constructor
- * @param {boolean} global Whether to store the values in the global window
+ * @param {boolean} [global=false] Whether to store the values in the global window
* object or a exclusively in the object property 'values'.
*/
function Map( global ) {
};
/**
+ * Base library for MediaWiki.
+ *
* @class mw
* @alternateClassName mediaWiki
* @singleton
Message: Message,
/**
- * List of configuration values
+ * Map of configuration values
*
- * Dummy placeholder. Initiated in startUp module as a new instance of mw.Map().
- * If `$wgLegacyJavaScriptGlobals` is true, this Map will have its values
- * in the global window object.
- * @property
+ * Check out [the complete list of configuration values](https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#mw.config)
+ * on MediaWiki.org.
+ *
+ * If `$wgLegacyJavaScriptGlobals` is true, this Map will put its values in the
+ * global window object.
+ *
+ * @property {mw.Map} config
*/
+ // Dummy placeholder. Re-assigned in ResourceLoaderStartupModule with an instance of `mw.Map`.
config: null,
/**
libs: {},
/**
+ * Access container for deprecated functionality that can be moved from
+ * from their legacy location and attached to this object (e.g. a global
+ * function that is deprecated and as stop-gap can be exposed through here).
+ *
+ * This was reserved for future use but never ended up being used.
+ *
+ * @deprecated since 1.22: Let deprecated identifiers keep their original name
+ * and use mw.log#deprecate to create an access container for tracking.
* @property
*/
legacy: {},
*
* @private
* @param {string} text CSS text
- * @param {Mixed} [nextnode] An Element or jQuery object for an element where
- * the style tag should be inserted before. Otherwise appended to the `<head>`.
- * @return {HTMLElement} Node reference to the created `<style>` tag.
+ * @param {HTMLElement|jQuery} [nextnode=document.head] The element where the style tag should be
+ * inserted before. Otherwise it will be appended to `<head>`.
+ * @return {HTMLElement} Reference to the created `<style>` element.
*/
- function addStyleTag( text, nextnode ) {
+ function newStyleTag( text, nextnode ) {
var s = document.createElement( 'style' );
// Insert into document before setting cssText (bug 33305)
if ( nextnode ) {
}
/**
+ * Add a bit of CSS text to the current browser page.
+ *
+ * The CSS will be appended to an existing ResourceLoader-created `<style>` tag
+ * or create a new one based on whether the given `cssText` is safe for extension.
+ *
* @param {string} [cssText=cssBuffer] If called without cssText,
- * the internal buffer will be inserted instead.
+ * the internal buffer will be inserted instead.
* @param {Function} [callback]
*/
function addEmbeddedCSS( cssText, callback ) {
}
}
- $( addStyleTag( cssText, getMarker() ) ).data( 'ResourceLoaderDynamicStyleTag', true );
+ $( newStyleTag( cssText, getMarker() ) ).data( 'ResourceLoaderDynamicStyleTag', true );
cssCallbacks.fire().empty();
}
*/
function addScript( src, callback, async ) {
/*jshint evil:true */
- var script, head,
- done = false;
+ var script, head, done;
// Using isReady directly instead of storing it locally from
// a $.fn.ready callback (bug 31895).
// IE-safe way of getting the <head>. document.head isn't supported
// in old IE, and doesn't work when in the <head>.
+ done = false;
head = document.getElementsByTagName( 'head' )[0] || document.body;
script = document.createElement( 'script' );
// Handle memory leak in IE
script.onload = script.onreadystatechange = null;
- // Remove the script
+ // Detach the element from the document
if ( script.parentNode ) {
script.parentNode.removeChild( script );
}
- // Dereference the script
+ // Dereference the element from javascript
script = undefined;
callback();
/* Public Methods */
return {
- addStyleTag: addStyleTag,
+ /**
+ * @inheritdoc #newStyleTag
+ * @method
+ */
+ addStyleTag: newStyleTag,
/**
- * Requests dependencies from server, loading and executing when things when ready.
+ * Batch-request queued dependencies from the server.
*/
work: function () {
var reqBase, splits, maxQueryLength, q, b, bSource, bGroup, bSourceGroup,
},
/**
- * Registers a module, letting the system know about it and its
+ * Register a module, letting the system know about it and its
* properties. Startup modules contain calls to this function.
*
* @param {string} module Module name
},
/**
- * Implements a module, giving the system a course of action to take
- * upon loading. Results of a request for one or more modules contain
- * calls to this function.
+ * Implement a module given the components that make up the module.
+ *
+ * When #load or #using requests one or more modules, the server
+ * response contain calls to this function.
*
* All arguments are required.
*
},
/**
- * Executes a function as soon as one or more required modules are ready
+ * Execute a function as soon as one or more required modules are ready.
*
* @param {string|Array} dependencies Module name or array of modules names the callback
* dependends on to be ready before executing
},
/**
- * Loads an external script or one or more modules for future use
+ * Load an external script or one or more modules.
*
* @param {string|Array} modules Either the name of a module, array of modules,
* or a URL of an external script or style
},
/**
- * Changes the state of a module
+ * Change the state of one or more modules.
*
* @param {string|Object} module module name or object of module name/state pairs
* @param {string} state state name
},
/**
- * Gets the version of a module
+ * Get the version of a module.
*
- * @param {string} module name of module to get version for
+ * @param {string} module Name of module to get version for
*/
getVersion: function ( module ) {
if ( registry[module] !== undefined && registry[module].version !== undefined ) {
},
/**
- * @deprecated since 1.18 use mw.loader.getVersion() instead
+ * @inheritdoc #getVersion
+ * @deprecated since 1.18 use #getVersion instead
*/
version: function () {
return mw.loader.getVersion.apply( mw.loader, arguments );
},
/**
- * Gets the state of a module
+ * Get the state of a module.
*
* @param {string} module name of module to get state for
*/
},
/**
- * For backwards-compatibility with Squid-cached pages. Loads mw.user
+ * Load the `mediawiki.user` module.
+ *
+ * For backwards-compatibility with cached pages from before 2013 where:
+ *
+ * - the `mediawiki.user` module didn't exist yet
+ * - `mw.user` was still part of mediawiki.js
+ * - `mw.loader.go` still existed and called after `mw.loader.load()`
*/
go: function () {
mw.loader.load( 'mediawiki.user' );
/**
* HTML construction helper functions
+ *
+ * @example
+ *
+ * var Html, output;
+ *
+ * Html = mw.html;
+ * output = Html.element( 'div', {}, new Html.Raw(
+ * Html.element( 'img', { src: '<' } )
+ * ) );
+ * mw.log( output ); // <div><img src="<"/></div>
+ *
* @class mw.html
* @singleton
*/
return s.replace( /['"<>&]/g, escapeCallback );
},
- /**
- * Wrapper object for raw HTML passed to mw.html.element().
- * @class mw.html.Raw
- */
- Raw: function ( value ) {
- this.value = value;
- },
-
- /**
- * Wrapper object for CDATA element contents passed to mw.html.element()
- * @class mw.html.Cdata
- */
- Cdata: function ( value ) {
- this.value = value;
- },
-
/**
* Create an HTML element string, with safe escaping.
*
* - this.Cdata: The value attribute is included, and an exception is
* thrown if it contains an illegal ETAGO delimiter.
* See http://www.w3.org/TR/1999/REC-html401-19991224/appendix/notes.html#h-B.3.2
- *
- * Example:
- * var h = mw.html;
- * return h.element( 'div', {},
- * new h.Raw( h.element( 'img', {src: '<'} ) ) );
- * Returns <div><img src="<"/></div>
*/
element: function ( name, attrs, contents ) {
var v, attrName, s = '<' + name;
}
s += '</' + name + '>';
return s;
+ },
+
+ /**
+ * Wrapper object for raw HTML passed to mw.html.element().
+ * @class mw.html.Raw
+ */
+ Raw: function ( value ) {
+ this.value = value;
+ },
+
+ /**
+ * Wrapper object for CDATA element contents passed to mw.html.element()
+ * @class mw.html.Cdata
+ */
+ Cdata: function ( value ) {
+ this.value = value;
}
};
}() ),
user: {
options: new Map(),
tokens: new Map()
- }
+ },
+
+ /**
+ * Registry and firing of events.
+ *
+ * MediaWiki has various interface components that are extended, enhanced
+ * or manipulated in some other way by extensions, gadgets and even
+ * in core itself.
+ *
+ * This framework helps streamlining the timing of when these other
+ * code paths fire their plugins (instead of using document-ready,
+ * which can and should be limited to firing only once).
+ *
+ * Features like navigating to other wiki pages, previewing an edit
+ * and editing itself – without a refresh – can then retrigger these
+ * hooks accordingly to ensure everything still works as expected.
+ *
+ * Example usage:
+ *
+ * mw.hook( 'wikipage.content' ).add( fn ).remove( fn );
+ * mw.hook( 'wikipage.content' ).fire( $content );
+ *
+ * Handlers can be added and fired for arbitrary event names at any time. The same
+ * event can be fired multiple times. The last run of an event is memorized
+ * (similar to `$(document).ready` and `$.Deferred().done`).
+ * This means if an event is fired, and a handler added afterwards, the added
+ * function will be fired right away with the last given event data.
+ *
+ * Like Deferreds and Promises, the mw.hook object is both detachable and chainable.
+ * Thus allowing flexible use and optimal maintainability and authority control.
+ * You can pass around the `add` and/or `fire` method to another piece of code
+ * without it having to know the event name (or `mw.hook` for that matter).
+ *
+ * var h = mw.hook( 'bar.ready' );
+ * new mw.Foo( .. ).fetch( { callback: h.fire } );
+ *
+ * @class mw.hook
+ */
+ hook: ( function () {
+ var lists = {};
+
+ /**
+ * Create an instance of mw.hook.
+ *
+ * @method hook
+ * @member mw
+ * @param {string} name Name of hook.
+ * @return {mw.hook}
+ */
+ return function ( name ) {
+ var list = lists[name] || ( lists[name] = $.Callbacks( 'memory' ) );
+
+ return {
+ /**
+ * Register a hook handler
+ * @param {Function...} handler Function to bind.
+ * @chainable
+ */
+ add: list.add,
+
+ /**
+ * Unregister a hook handler
+ * @param {Function...} handler Function to unbind.
+ * @chainable
+ */
+ remove: list.remove,
+
+ /**
+ * Run a hook.
+ * @param {Mixed...} data
+ * @chainable
+ */
+ fire: function () {
+ return list.fireWith( null, slice.call( arguments ) );
+ }
+ };
+ };
+ }() )
};
}( jQuery ) );
dépôts / lhc / web / wiklou.git / blobdiff