Jump to: navigation, search

Note the stand alone mwEmbed Library is hosted on GitHub.

MwEmbed is a core library for JS2 MediaWiki interfaces. It supports localization and script-loader integration, and provides a few useful helper functions. Built as a standalone library, it also supports importing "mediaWiki" interfaces into other contexts, such as the video player, add-media-wizard or sequencer in an external site. For more information on the standalone version of mwEmbed see html5 library page on To see the code as deployed on WMF sites:

Core mwEmbed.js function overview[edit | edit source]

This documentation is mostly copied from the code for easy updates.

Configuration Vars[edit | edit source]

Here are the default configuration variables:

* If jQuery / mwEmbed should be loaded.
* This flag is automatically set to true if: 
*  Any script calls mw.ready ( callback_function )
*  Page DOM includes any tags set in config.rewritePlayerTags at onDomReady 
*  ( embedPlayer module )
* This flag increases page performance on pages that do not use mwEmbed 
* and don't already load jQuery 
* For example when including the mwEmbed.js in your blog template 
* mwEmbed will only load extra js on blog posts that include the video tag.
* NOTE: Future architecture will probably do away with this flag and refactor it into 
* a smaller "remotePageMwEmbed.js" script similar to ../remoteMwEmbed.js
"runSetupMwEmbed" : false,	

// The mediaWiki path of mwEmbed  
"mediaWikiEmbedPath" : "js/mwEmbed/",

// Api actions that must be submitted in a POST, and need an api proxy for cross domain calls
'apiPostActions': [ 'login', 'purge', 'rollback', 'delete', 'undelete',
	'protect', 'block', 'unblock', 'move', 'edit', 'upload', 'emailuser',
	'import', 'userrights' ],

//If we are in debug mode ( results in fresh debug javascript includes )
'debug' : false,	

// Default request timeout ( for cases where we inlucde js and normal browser timeout can't be used )
// stored in seconds
'defaultRequestTimeout' : 20,

// Default user language is "en" Can be overwritten by: 
// 	"uselang" url param 
// 	wgUserLang global  
'userLanguage' : 'en',

// Set the default providers ( you can add more provider via {provider_id}_apiurl = apiUrl	  
'commons_apiurl' : ''

mwEmbed Object Documentation[edit | edit source]

* Enables load hooks to run once DOM is "ready" 
* Will ensure jQuery is available, is in the $j namespace 
* and mw interfaces and configuration has been loaded and applied
* this is different from jQuery(document).ready() 
* ( jQuery ready is not friendly with dynamic includes and core interface asynchronous build out.)
* @param {Function} callback Function to run once DOM and jQuery are ready
mw.ready ( callback )

* Setter for configuration values
* @param [Mixed] name Name of configuration value
*	{Object} Will iderate through each key and call setConfig
* 	{String} Will set configuration by string name to value
* @param {String} value Value of configuration name 
mw.setConfig ( name, value )
* Getter for configuration values
* @param {String} name of configuration value to get
* @return {Mixed} value of configuration key
* 	returns "false" if key not found
mw.getConfig ( name )

* Set a default config value 
* Will only update configuration if no value is present
* @param [Mixed] name 
*	{Object} Will iderate through each key and call setDefaultConfig
* 	{String} Will set configuration by string name to value
* @param [Mixed] value Set configuration name to value
mw.setDefaultConfig = function( name, value ) {

Language Methods[edit | edit source]

* Localized Language support attempts to mirror some of the functionality of Language.php in MediaWiki
* It contains methods for loading and transforming msg text

* Loads a set of json messages into the messegeCache object.
* @param json msgSet The set of msgs to be loaded
mw.addMessages ( msgSet )

 * Returns a transformed msg string
 * it take a msg key and array of replacement values of form
 * $1, $2 and does relevant msgkey transformation returning
 * the user msg.
 * @param {String} key The msg key as set by mw.addMessages
 * @param {Array} args  An array of replacement strings
 * @return string
mw.getMsg ( key , args )

//gM function is a global shortcut to mw.getMsg
gM ( key, args )

* getRemoteMsg loads remote msg strings
* @param mixed msgSet the set of msg to load remotely
* @param function callback  the callback to issue once string is ready
mw.getRemoteMsg ( msgSet, callback )

Parser Object[edit | edit source]

* MediaWiki wikitext "Parser"
* Not feature complete so we will skip documentation on this feature set for now. 

Loader[edit | edit source]

* Core load function: 
* @param {Mixed} loadRequest:
* {String} Name of a module to be loaded
* 	Modules are added via addModuleLoader and can define custom
* 	code needed to load the module dependencies
*	Module loader function should callback with module name
* {String} Name of a class to loaded. 
* 	Classes are added via addClassFilePaths function
*	Using defined class names avoids loading the same class
*	twice by first checking if the "class variable" is defined
* {String} Absolute or relative to mwEmbed file path. 
*	The same file won't be loaded twice
* {Array} can be an array of any combination of the above strings.
*	Will be loaded in-order or in a single 
*	script-loader request if scriptLoader is enabled 
* {Array} {Array} Can be a set of Arrays for loading.		 
*	Some browsers execute included scripts out of order. 
* 	This lets you chain sets of request for those browsers.
*	If using the server side script-loader order is preserved 
* 	in output and a single request will be used.
* @param {Function} callback Function called once loading is complete
mw.load ( loadRequest, callback )

* Adds a module to the mwLoader object 
* @param {String} name Name of module
* @param {Function} moduleLoader Function that
*		loads dependencies for a module
mw.addModuleLoader ( name, loaderFunction )

* Adds class file path key value pairs
* @param {Object} classSet JSON formated list of 
*  class name file path pairs.
*  classSet must be strict JSON to allow the 
*  php scriptLoader to parse the file paths.  
mw.addClassFilePaths ( classSet )

* Add a style sheet to be loaded the same time as the requested class
* NOTE: In general style sheets should be loaded via a module loader function. 
*  In some cases a single class has a single sheet dependency which can be set-up using this function
* @param {Object} sheetSet ClassKey : sheet location key value paris
mw.addClassStyleSheets ( sheetSet )

API Helper functions[edit | edit source]

* Get mediaWiki JSON a wrapper for jQuery getJSON:
* $j.getJSON( url, [data], [callback] )
* The mediaWiki version lets you skip the url part 
* mw.getJSON( [url], data, callback ); 
* Lets you assume a few options:
* 	* url is optional 
* 		( If the first argument is not a string we assume a local mediaWiki api request )
*   * callback parameter is not needed we setup the callback automatically
* 	* url param 'action'=>'query' is assumed ( if not set to something else in the "data" parma )
* 	* format is set to "json" automatically
* @param {Mixed} url or data request
* @param {Mixed} data or callback
* @param {Mixed} callbcak
mw.getJSON ( arg1, arg2, arg3 )

 * Simple api helper to grab an edit token
 * @param title The wiki page title you want to edit
 * @param {String} [api_url] The target API URL
 * @param {callback} callback Function to pass the token to
mw.getToken ( title, api_url, callback )

 * Issues the wikitext parse call 
 * @param {String} wikitext Wiki Text to be parsed by mediaWiki api call
 * @param {String} title Context title of the content to be parsed
 * @param {Function} callback Function called with api parser output 
mw.parseWikiText = function( wikitext, title, callback )

 * Api helper to grab the username
 * @param {String} [apiUrl] Optional target API url (uses default local api if unset) 
 * @param {Function} callback Function to callback with username or false if not found	 
mw.getUserName = function( apiUrl, callback ){	 

* Wrapper for jQuery getScript, 
* Uses the scriptLoader if enabled
* If jQuery is not defined load it.
* @param {String} scriptRequest The requested path or classNames for the scriptLoader
* @param {Function} callback Function to call once script is loaded   
mw.getScript ( scriptRequest, callback )

Utility Functions[edit | edit source]

* Similar to php isset function checks if the variable exists.
* Does a safe check of a descendent method or variable
* @param {String} objectPath
* @return {Boolean}
* 	true if objectPath exists
*	false if objectPath is undefined
mw.isset ( objectPath )

* Waits for a object to be defined and the calls callback
* @param {Object} objectName Name of object to be defined
* @param {Function} callback Function to call once object is defined
* @param {Null} callNumber Used internally to keep track of 
*	number of times waitForObject has been called 
mw.waitForObject ( objectName, callback )

* Check if an object is empty or if its an empty string. 
* @param {Object} object Object to be checked
mw.isEmpty ( object ) 

* Log a string msg to the console
* all mw.log statements will be removed on script-loader minification so
* lots of mw.log calls will not impact performance in non debug mode
* @param {String} string String to output to console
mw.log ( string )

* "Get" a style sheet.
* Appends a style sheet to the DOM is called "getStyleSheet" to mirror wraping of jqueries getScript
* @param {Mixed}
*	{Array} url List of urls to be loaded
*	{String} url Url of the style sheet to be loaded
mw.getStyleSheet ( url )

* Get Api URL from mediaWiki page defined variables
* @return {Mixed}
* 	api url
* 	false
mw.getLocalApiUrl () 

* Replace url parameters via newParams key value pairs
* @param {String} url Source url to be updated
* @param {Object} newParams key, value paris to swap in
* @return {String}
*	the updated url
mw.replaceUrlParams ( url, newParams )

* Parse URI function
* For documentation on its usage see: 
mw.parseUri ( str ) 

* Absolute Url takes a src and returns the absolute location given the document.URL
* @param {String} src path or url
* @return {String} absolute url
mw.absoluteUrl ( src, contextUrl )

* Takes in a string returns an xml dom object 
* This should be depreciated in favor of jQuery xml parsing: 
* ie: $j( xmlString ).find("item").each(function() { 
* @param {String} str String of XML content to be parsed
* @return 
* 	{Object} XML
*	false If XML could not be parsed 
mw.parseXML = function ( str )

MwEmbed File Overview[edit | edit source]

mwEmbed overview diagram ( slightly outdated )
  • jsScriptLoader.php The script-loader entry point.
  • mwEmbed.js The javascript entry point. Contains helper functions for javascript class dependency loading, skin setup, conditional invocation of video tag interface rewrite and entry points to firefogg, add-media-wizard, and sequencer interfaces.
  • /remotes/mediaWiki.js a script file to use the mwEmbed tools as a remote script for mediaWiki
  • tests Examples usage and tests of stand alone usage of the mwEmbed library.
    • media a folder with some sample media files
    • Add_Media_Wizard.html a simple inject media into a page sample of add-media-wizard. Usefull if building a simple plugin for blogging software or other CMS.
    • Firefogg_Make_Advanced.html Advanced Encoder example for firefogg. You can see it in action here
    • Firefogg_Make_Simple.html Simple Usage example of firefogg
    • Player_Simple_Video_Tag.html Simple example usage of the mwEmbed player. Showing how it rewrites the <video> tag.
    • Player_Themable.html Sample themeable player via jquery.ui theme engine.
    • Player_Timed_Text.html Timed Text example.
    • Sequence_Editor.html Sample Stand alone sequence editor.
  • jquery
    • jquery.ui-1.7.1 (includes jquery.ui 1.7.1 install)
    • plugins includes a few jquery plugins.
    • jquery-1.3.2.js the jquery library named by version.
  • modules
    • AddMedia Holds all the components for searching and importing of assets. Also know as the add media wizard
      • mw.BaseUploadInterface.js the base library for displaying upload progress and errors. it also handles basic form rewriting
      • mw.Firefogg.js The base firefogg library. Extends the BaseUploadInterface with support for firefogg.
      • mw.FirefoggGUI.js The advanced firefogg interface. Extends the base mvFirefogg library and exposes all firefogg options.
      • mw.RemoteSearchDriver.js The base engine for the add-media-wizard. Contains content provider configuration.
      • searchLibs holds api bindings for the various search providers
        • baseRemoteSearch.js the base class for search providers (provides shared methods among searchLibs)
        • archiveOrgSearch.js bindings for search
        • flickrSearch.js bindings for flicker image search (just stubs atm)
        • mediaWikiSearch.js bindings for mediaWiki api based search. (used both for searching commons and or the local mediaWiki install)
        • metavidSearch.js bindings for searching the archive of use house and senate floor proceedings.
    • ClipEdit Holds tools for image and video manipulation
      • colorpicker A jquery plugin for selecting a color with color weel and all.
      • jCrop A jquery plugin for cropping images.
      • pixastic-editor a jquery.ui photoshop light in-browser image editor.
      • pixastic-lib the core filters for the pixastic editor
      • mvClipEdit.js the driver for editing images and video clips.
    • EmbedPlayer the core libraries for embedding video.
      • binPlayers contains applets used for playback of video
        • cortado
        • kaltura-player
          • kdp.swf KDP GPL flash player for h.264 & flv fallback for more info see kaltura dynamic player not used on wikimedia projects
        • flowplayer A simple GPL flash player (for flash fallback of content in mwEmbed not used on wikimedia projects
        • omtk-fx
          • omtkp.swf A simple flash applet for playback of vorbis content included from OMTK source
      • embedPlayer.js The interface driver and base method provider for embedding video
      • nativeEmbed.js The native embedder object. Extends the embedPlayer object with native html5 video embedding.
      • vlcEmbed.js The VLC plugin embeder object. Extends the embedPlayer object with VLC plugin embedding.
      • javaEmbed.js A java embeder that abstracts the cortado applet to work with the embedPlayer object
      • omtkEmbed.js A flash based vorbis audio player, extends the embedPlayer object for audio only playback of vorbis with flash.
      • flashEmbed.js The flash embeder that abstracts a flash player to the embedPlayer object (not used in wikimedia projects)
      • genericEmbed.js A simple object embedder for browsers that register ogg/video support but are not a supported plugin.
      • htmlEmbed.js A embeder for displaying html with embedPlayer controls. This is mostly for sequences that display html based title screens or html based intro text/images.
  • *Sequencer Top level folder for sequencer / playlist components.
      • mw.PlayList.js The base playlist player. It parses a few formats including our reduced feature set SMIL sequencer language and displays the video.
      • mw.Sequencer.js The sequencer library that drives the sequence editor.
      • mw.TimedEffectsEdit.js An early stub for timed Effects editing interface
    • TimedText
      • mw.TextInterface.js A interface for timed text display. Presently support CMML and srt. Also includes a tool for selecting language and click on text seeking.
  • includes
    • languages the language files for localized versions of all the above mentioned components.
      • mwEmbed.i18n.php the core language file. Matches the language file structure of mediaWiki extensions. Placed in this folder to support stand alone localization of the reusable javascript libraries.
    • maintenance the maintenance utilies for syncing language msgs
      • mergeJavascriptMsg.php A simple script for merging javascript msg into the mwEmbed.i8n.php file
    • minify the library for minifying the javascript
      • JSMin.php The JSMin php based javascript minnification library.
    • script-cache holds the cached versions of scripts
    • skins The top level skin folder
      • mvpcf The default skin folder
        • images skin images
        • mv_sequence.css the sequencer skin css file
        • styles.css the player and simple components skin. It works by extending jquery.ui classes and skin structure.