MwEmbed

Note this documentation is outdated. I will try and update it and move to Extension:MwEmbedSupport Mdale 10:04, 13 February 2011 (UTC)

MwEmbed is a core library for JS2 mediaWiki interfaces. It supports localization, script-loader integration & provides a few useful helper functions. Built as a stand alone 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 stand alone version of mwEmbed see html5 library page on kaltura.org.

Core mwEmbed.js function overview

This documentation is mostly copied from the code for easy updates

Configuration Vars

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' : 'http://commons.wikimedia.org/w/api.php'

mwEmbed Object Documentation

/**
* 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

/**
* 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

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

Loader

/**
* 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

/*
* 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

/**
* 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: 
* http://stevenlevithan.com/demo/parseuri/js/
*/
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

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 archive.org 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 metavid.org 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
        • cortado.jar the latest cortado.jar from its upstream location: http://theora.org/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.