User:TheDJ/ExampleGadget.js

/** * This is an example gadget * It has no goal other than to show you techniques you might want to use in your own gadgets */ // 1: Module pattern // This first line has two basic functions. Creating "functional scoping" // and to rename and keep track of our our global variables // mw and $ are also declared globally, but due to their length there is a higher // chance of collisions and especially $ is often used by other libraries as well. // Check the bottom of this script, for the last line, which closes off this statement ( function( mw, $ ) {	// 2: Any variables you want to use for the duration of the module's lifetime	// can be kept here. They are the global state of the module.	var state;	// 3: Functions that you use internally within the module should be defined	// as named functions. Try to avoid declaring functions inside functions,	// but especially avoid declaring them inside loops, because that is. 	function aPrivateFunction {	}	// Code that you execute here, runs immediately	mw.log( 'Is executed immediately while this script is loading' );

// 4: Waiting for the page to be ready function pageReady { // From here we can start reading and adding to the the webpage. // Before this point, the document will be available, but possibly incomplete mw.log( 'The document is ready' ); }	// There are multiple ways to wait for the page to be complete. // Variant 1: $( document ).ready( pageReady ); // Variant 2: Shortest and most used, identical to the above $( pageReady ); // Variant 3: Use this if you need to wait for the page to be ready, // but also need to wait or guarantee that other conditions are fulfilled // This uses promises to wait for both document ready to finish and for the // mediawiki.util library to finish loading before it executes pageReady $.when( $.ready, mw.loader.using( 'mediawiki.util' ) ).then( pageReady ); // 5: ResourceLoader modules basics // MediaWiki uses a resource loader to segment Javascript, CSS, // DOM templates and translation messages into bundles, that can be loaded on // demand. MediaWiki has many modules and libraries (thousands), so on demand // loading a library ONLY when the user actually requires it is very important // and becoming somewhat familiar with how this works is therefor critical // 	// The mediawiki.loader aka mw.loader takes care and provides all these options // The loader is always available //	// 	$.when( mw.loader.using( ['mediawiki.util'] ), $.ready ).then( function {		// Here we guarantee that the provided array of modules is loaded,		// in this case only mediawiki.util, as well as that the document is available.		// If the modules were already loaded by something else on the page, then		// this is a noop and this function will load immediately.		// We can now add a link to the toolboxes for instance		mw.util.addPortletLink( '/wiki/MediaWiki:ExampleGadget.js', 'p-tb', 'Example Gadget' );	} ); // TODO // 2: mw.hooks // 3: addportletlink // 4: resource loader modules (and loader) // 5: require pattern // 6: api requests // 7: preferences // 7: click handler preventDefault // 8: using external cdnjs libraries // 9: Advanced resourceloader techniques //  - load another gadget //  - preloading

// 1: End of 1 // Here we execute the anonymous function preceding it, and pass it global // variables that we want it to be able to use. These are supposed to be the // 'only' global variables you use, making it easier to avoid accidently leaking // variables into your global scope. } )( mediaWiki, jQuery );