JS2 Overview

{{hist The use of "loaders" enables dynamic packaging of modules with the intent of avoiding multiple requests, for dynamically loaded interfaces.

To add a javascript Module to your extension you must supply the relative path to the module in your main extension .php file:

$wgExtensionJavascriptModules[ 'myJsModule' ] = 'extensions/myExtension/MyJsModule';

The root of your module should contain: loader.js ( "module loader" ) {moduleName}.i18n.php ( "mediaWiki localization format localization file" ) {libraryCode.js files} ( "library code" )

JS Module Components Overview
The three components of a js-module are "module loaders", "module activators" and "library code and assets".

for a given interface "module". The set of requested libraries can driven by site configuration, and user preferences. The requested set of modules can include core libraries like jquery.ui helpers.
 * "module loaders" define named paths and build the request set of the javascript and css assets

invoke the interface or application.
 * "module activators" Call the module loaders in a given application context and then

These libraries are driven by a given configuration.
 * "library code and assets" These consist of library code and assets that is the user interface or application.

Example Flow and File Contents
When an application wants to use a interface component it calls the module loader from its activator. The module loader checks relevant configuration, it then issues a single script-loader request that checks javascript application state for existing satisfied dependencies or native browser support it then retrieves all the needed javascript, css and localized message text for that interface. The returned javascript will be minfied and gziped and cached on the server. The activator gets a callback that the interface library is loaded, and can then use that interface.

Example Loader loader.js:
Loaders should define named class paths, named "module loader" functions and default configuration if appropriate. Style sheet assets should be named mw.style[ {styleName} ] this is so we can register the presence of style sheets in javascript and libraries can dynamically share style sheet components.

Example Library Code
The key thing to remember about library code is that it defines a named class ie: a file by name 'mw.Foo.js' would define a object named 'mw.Foo' ie something like:

Library code should operate off of global configuration mw.getConfig( 'configurationOption' ) and or local configuration ( where appropriate ) ie the constructor gets passed an options object that defines named value pairs of configuration or callbacks.

The other key thing to remember about library code is to handle localization in some way. The localization options are presented bellow

Localization
Each javascript module hosts a {moduleName}.i18n.php file that works with the existing mediaWiki translate system. Note when the script-loader populates the msg replacements it uses mediaWiki's wfGetMsg function so any database MediaWiki namespace strings will be included in your javascript messages.

You have three options for packaging messages in your javascript module

1) If your javascript module is simple and your interface is mostly set in a single file you may want to load all your msgs at once. You can get all the msgs in your javascript module's localization file by simply running: Putting this function call at the top of your primary library code javascript file will be replaced with all the msgs in your modules php localization file in the current language. NOTE you won't be able to pull in msgKeys that are hosted outside of your extension ( to do that you must list the keys you want at the top of the javascript file with localization option 2 )

2) If your code includes many sub-modules and you may want fine grain control over what messages are packaged when. You can define the set of msg keys it at the top of any javascript file. For example: Will be replaced by the script-loader with the localized msgs for every listed key.

3) If you are doing a lot of stand alone testing it can be faster to use a json array at the top of your javascript file.  Your javascript file then becomes your developer reference English messages. A maintenance scripts then copy your English fallbacks into the php localization file for the translate wiki scripts to work with.  Running the JS2Support maintenance script "mergeJavascriptMsgs.php" will sync javascript into phpt files. This is the most complicated setup, if your unsure use the first option and call: mw.includeAllModuleMessages; In your primary library code javascript.

Accessing Msgs in Javascript
The JS2 Localization system works similar to its php counterpart. It includes support for NaN undefineds transforms.

To get a message simply issue the call: Tight integration with jQuery means you can pass in jQuery replacements like so:

Plurals work the same way as in mediawiki. mwEmbed maintains a copy of every PLURAL transformation ported to javascript and dynamically packages the transformation as part of the localization script-loader request. A test suite of mediawiki vs javascript transformation for all 356 language keys is available. They might not work with fractional numbers, though. For more documentation see: mwEmbed/languages/mw.Language.js and mwEmbed/languages/mw.Parser.js

mwEmbed as a Gadget
mwEmbed works as a stand alone package as a gadget. The mwEmbed gadget description list the major parts of the gadget.

Debugging mwEmbed Gadget
By default mwEbed Gadget is optimized for a small package and few round trips to the server which can make it difficult to debug. You have a few options to debug the mwEmbed gadget.

The easiest way to debug mwEmbed is simply add &debug=true to the URL of the page your viewing. This will cause mwEmbed to load all the JavaScript, Css and message file assets individually instead of as a package, so you can easily identify where the application is failing and use the JavaScript console log in the bug report.

Working on mwEmbed-Gadget
1) Like with debugging you will want to disable the gadget and move to a user-script include. But instead of referencing prototype server you should setup your own local server with a check out of [//svn.wikimedia.org/svnroot/mediawiki/branches/MwEmbedStandAlone/ mwEmbed Stand alone] ie: 2) Once your user script file has been update, you should be able to directly modify the scripts in your code editor and run it directly on commons or en wiki with full source path preservation.

Developing a Gadget using mwEmbed
MwEmbed offers many convenient functions for mediaWiki javascript interfaces, and provied a shared repository of jquery.ui and useful jquery plugins.
 * 1) To use mwEmbed in your gadget you should first include the mwEmbed gadget ( try and use the exact same url as the gadget )
 * 1) Now once mwEmbed is ready, you can start using the mwEmbed functions

Example Gadget using mwEmbed
To quickly illustrate how mwEmbed streamlines mediaWiki javascript development, lets assume a gadget on commons wants to leave a message on a users en.wikipedia talk page.