mediawiki-extensions-Visual.../modules/ve-mw
Roan Kattouw e49df7f9d9 Infrastructure for loading plugins in the MW integration
Server-side, plugins can register themselves by adding to
$wgVisualEditorPluginModules. This is the recommended way for
MW extensions to extend VE. Client-side, plugins can register
themselves through mw.libs.ve.addPlugin(), which takes a string
(RL module name) or a callback.

When VisualEditor loads, we load the registered plugin modules in
parallel with ext.visualEditor.core. Note that they're loaded in
parallel, not after, and so the plugins should explicitly depend
on ext.visualEditor.core if they use or extend classes in VE core.
Once the modules finish loading and user and site scripts have run,
we execute the registered plugin callbacks. These callbacks can
optionally return a promise. We gather these promises and wait for
all of them to be resolved, then initialize the editor.

This allows Gadgets to extend VE by top-loading a small module that
depends on ext.visualEditor.viewPageTarget.init and calls
mw.libs.ve.addPlugin( 'ext.gadget.bottomHalfGadget' ); , the bottom
half being a hidden Gadget that depends on ext.visualEditor.core and
contains the actual code. The addPlugin() call needs to be in a
top-loading module because otherwise there's no guarantee that the
plugin will be registered before the user clicks edit and VE loads.

User and site scripts can extend VE by simply calling addPlugin()
directly, as mw.libs.ve is already present when user scripts run (since
it's top-loaded) and VE waits for 'user' and 'site' to run before
executing plugins.

If user/site scripts need to load additional JS files, they can load
these with $.getScript() and return the corresponding promise:
mw.libs.ve.addPlugin( function() { return $.getScript( 'URL' ); } );

For a diagram of all this, see
https://www.mediawiki.org/wiki/File:VE-plugin-infrastructure.jpg :)

VisualEditor.php:
* Add $wgVisualEditorPluginModules

VisualEditor.hooks.php:
* Expose $wgVisualEditorPluginModules in JS

ve.init.mw.ViewPageTarget.init.js:
* Add mw.libs.ve.addPlugin function that just stores the registered
  values in an array and passes them into the mw.Target when it's
  being initialized

ve.init.mw.Target.js:
* Add $wgVisualEditorPluginModules to the set of modules to load when
  initializing VE
* Add a Deferred (this.modulesReady) to track module loading
* Add addPlugin() and addPlugins() methods that add to either
  this.modules or this.pluginCallbacks
* In load(), instead of mw.loader.load()ing this.modules, use using()
  to load this.modules plus user and site, and fire onModulesReady()
  when they're loaded
* In onModulesReady(), execute the registered callbacks, gather the
  returned promises, wait for all of them to be resolved, then resolve
  this.modulesReady
* Fire onReady based on this.modulesReady being resolved, rather than
  using a second using() call

Bug: 50514
Change-Id: Ib7d87a17eaac6ecdb8b0803b13840d7ee58902df
2013-07-26 19:31:56 +00:00
..
ce Fix MWBlockImageNodes' default horizontal location code 2013-07-25 15:48:08 -07:00
dm doc: Clean up spacing that caused <pre> or broken <ul>/<ol> 2013-07-25 04:02:50 +02:00
init Infrastructure for loading plugins in the MW integration 2013-07-26 19:31:56 +00:00
test Handle meta-only transclusions as meta items 2013-07-24 14:27:24 +00:00
ui Merge "doc: Clean up spacing that caused <pre> or broken <ul>/<ol>" 2013-07-25 22:36:41 +00:00