Catrope has uploaded a new change for review.
https://gerrit.wikimedia.org/r/75271
Change subject: Infrastructure for loading plugins in the MW integration
......................................................................
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
Change-Id: Ib7d87a17eaac6ecdb8b0803b13840d7ee58902df
---
M VisualEditor.hooks.php
M VisualEditor.php
M modules/ve-mw/init/targets/ve.init.mw.ViewPageTarget.init.js
M modules/ve-mw/init/ve.init.mw.Target.js
4 files changed, 108 insertions(+), 6 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/VisualEditor
refs/changes/71/75271/1
diff --git a/VisualEditor.hooks.php b/VisualEditor.hooks.php
index e3795bc..8d23441 100644
--- a/VisualEditor.hooks.php
+++ b/VisualEditor.hooks.php
@@ -148,13 +148,14 @@
* Adds extra variables to the global config
*/
public static function onResourceLoaderGetConfigVars( array &$vars ) {
- global $wgVisualEditorEnableEventLogging,
+ global $wgVisualEditorEnableEventLogging,
$wgVisualEditorPluginModules,
$wgVisualEditorEnableExperimentalCode,
$wgVisualEditorTabLayout;
$vars['wgVisualEditorConfig'] = array(
'enableExperimentalCode' =>
$wgVisualEditorEnableExperimentalCode,
'enableEventLogging' =>
$wgVisualEditorEnableEventLogging,
'tabLayout' => $wgVisualEditorTabLayout,
+ 'pluginModules' => $wgVisualEditorPluginModules,
);
return true;
diff --git a/VisualEditor.php b/VisualEditor.php
index 1ea12f7..a929dc5 100644
--- a/VisualEditor.php
+++ b/VisualEditor.php
@@ -10,6 +10,10 @@
/* Configuration */
+// Array of ResourceLoader module names (strings) that should be loaded when
VisualEditor is
+// loaded. Other extensions that extend VisualEditor should add to this array.
+$wgVisualEditorPluginModules = array();
+
// URL to the Parsoid instance
// MUST NOT end in a slash due to Parsoid bug
$wgVisualEditorParsoidURL = 'http://localhost:8000';
@@ -38,6 +42,7 @@
// upon signup.
// Depends on GuidedTour and EventLogging extensions.
$wgVisualEditorEnableGenderSurvey = false;
+
/* Setup */
$wgExtensionCredits['other'][] = array(
diff --git a/modules/ve-mw/init/targets/ve.init.mw.ViewPageTarget.init.js
b/modules/ve-mw/init/targets/ve.init.mw.ViewPageTarget.init.js
index e736e6f..14f8113 100644
--- a/modules/ve-mw/init/targets/ve.init.mw.ViewPageTarget.init.js
+++ b/modules/ve-mw/init/targets/ve.init.mw.ViewPageTarget.init.js
@@ -20,7 +20,8 @@
*/
( function () {
var conf, uri, pageExists, viewUri, veEditUri, isViewPage,
- init, support, getTargetDeferred;
+ init, support, getTargetDeferred,
+ plugins = [];
/**
* Use deferreds to avoid loading and instantiating Target multiple
times.
@@ -37,6 +38,9 @@
// Transfer methods
ve.init.mw.ViewPageTarget.prototype.setupSectionEditLinks =
init.setupSectionEditLinks;
+
+ // Add plugins
+ target.addPlugins( plugins );
getTargetDeferred.resolve( target );
} )
@@ -98,6 +102,44 @@
'blackberry': null
},
+ /**
+ * Add a plugin module or function.
+ *
+ * Plugins are run after VisualEditor is loaded, but before it
is initialized. This allows
+ * plugins to add classes and register them with the factories
and registries.
+ *
+ * The parameter to this function can be a ResourceLoader
module name or a function.
+ *
+ * If it's a module name, it will be loaded together with the
VisualEditor core modules when
+ * VE is loaded. No special care is taken to ensure that the
module runs after the VE
+ * classes are loaded, so if this is desired, the module should
depend on
+ * ext.visualEditor.core .
+ *
+ * If it's a function, it will be invoked once the VisualEditor
core modules and any
+ * plugin modules registered through this function have been
loaded, but before the editor
+ * is intialized. The function can optionally return a
jQuery.Promise . VisualEditor will
+ * only be initialized once all promises returned by plugin
functions have been resolved.
+ *
+ * @example
+ * // Register ResourceLoader module
+ * ve.libs.mw.addPlugin( 'ext.gadget.foobar' );
+ *
+ * // Register a callback
+ * ve.libs.mw.addPlugin( function () {
+ * ve.dm.Foobar = .....
+ * } );
+ *
+ * // Register a callback that loads another script
+ * ve.libs.mw.addPlugin( function () {
+ * return $.getScript( 'http://example.com/foobar.js' );
+ * } );
+ *
+ * @param {string|Function} plugin Module name or callback that
optionally returns a promise
+ */
+ addPlugin: function( plugin ) {
+ plugins.push( plugin );
+ },
+
skinSetup: function () {
init.setupTabLayout();
init.setupSectionEditLinks();
diff --git a/modules/ve-mw/init/ve.init.mw.Target.js
b/modules/ve-mw/init/ve.init.mw.Target.js
index 7e382f8..8e363e9 100644
--- a/modules/ve-mw/init/ve.init.mw.Target.js
+++ b/modules/ve-mw/init/ve.init.mw.Target.js
@@ -41,7 +41,10 @@
document.createElementNS && document.createElementNS(
'http://www.w3.org/2000/svg', 'svg' ).createSVGRect ?
['ext.visualEditor.viewPageTarget.icons-vector',
'ext.visualEditor.icons-vector'] :
['ext.visualEditor.viewPageTarget.icons-raster',
'ext.visualEditor.icons-raster']
- );
+ )
+ .concat( mw.config.get( 'wgVisualEditorConfig' ).pluginModules
|| [] );
+ this.pluginCallbacks = [];
+ this.modulesReady = $.Deferred();
this.loading = false;
this.saving = false;
this.serializing = false;
@@ -123,6 +126,28 @@
/* Static Methods */
/**
+ * Handle the RL modules for VE and registered plugin modules being loaded.
+ *
+ * This method is called within the context of a target instance. It executes
all registered
+ * plugin callbacks, gathers any promises returned and resolves
this.modulesReady when all of
+ * the gathered promises are resolved.
+ */
+ve.init.mw.Target.onModulesReady = function () {
+ var i, len, callbackResult, promises = [];
+ for ( i = 0, len = this.pluginCallbacks.length; i < len; i++ ) {
+ callbackResult = this.pluginCallbacks[i]();
+ if ( callbackResult && callbackResult.then ) { // duck-type
jQuery.Promise using .then
+ promises.push( callbackResult );
+ }
+ }
+ // Dereference the callbacks
+ this.pluginCallbacks = [];
+ // Create a master promise tracking all the promises we got, and wait
for it
+ // to be resolved
+ $.when.apply( $, promises ).done( this.modulesReady.resolve ).fail(
this.modulesReady.reject );
+};
+
+/**
* Handle response to a successful load request.
*
* This method is called within the context of a target instance. If
successful the DOM from the
@@ -167,8 +192,8 @@
this.baseTimeStamp = data.basetimestamp;
this.startTimeStamp = data.starttimestamp;
this.revid = data.oldid;
- // Everything worked, the page was loaded, continue as soon as
the module is ready
- mw.loader.using( this.modules, ve.bind(
ve.init.mw.Target.onReady, this ) );
+ // Everything worked, the page was loaded, continue as soon as
the modules are loaded
+ this.modulesReady.done( ve.bind( ve.init.mw.Target.onReady,
this ) );
}
};
@@ -455,6 +480,31 @@
/* Methods */
/**
+ * Add a plugin module or callback.
+ *
+ * @param {string|Function} plugin Plugin module or callback
+ */
+ve.init.mw.Target.prototype.addPlugin = function ( plugin ) {
+ if ( typeof plugin === 'string' ) {
+ this.modules.push( plugin );
+ } else if ( $.isFunction( plugin ) ) {
+ this.pluginCallbacks.push( plugin );
+ }
+};
+
+/**
+ * Add an array of plugins
+ * @see addPlugin
+ * @param {Array} plugins
+ */
+ve.init.mw.Target.prototype.addPlugins = function ( plugins ) {
+ var i, len;
+ for ( i = 0, len = plugins.length; i < len; i++ ) {
+ this.addPlugin( plugins[i] );
+ }
+};
+
+/**
* Get HTML to send to Parsoid. This takes a document generated by the
converter and
* transplants the head tag from the old document into it, as well as the
attributes on the
* html and body tags.
@@ -500,7 +550,11 @@
return false;
}
// Start loading the module immediately
- mw.loader.load( this.modules );
+ mw.loader.using(
+ // Wait for site and user JS before running plugins
+ this.modules.concat( [ 'site', 'user' ] ),
+ ve.bind( ve.init.mw.Target.onModulesReady, this )
+ );
data = {
'action': 'visualeditor',
--
To view, visit https://gerrit.wikimedia.org/r/75271
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ib7d87a17eaac6ecdb8b0803b13840d7ee58902df
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/VisualEditor
Gerrit-Branch: master
Gerrit-Owner: Catrope <[email protected]>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
