Extension:VisualEditor

MediaWiki extensions manual

VisualEditor Release status: beta
Implementation	Page action, Extended syntax, Beta Feature, Skin
Description	Integrates VisualEditor into MediaWiki for editing pages as rich content
Latest version	0.1.0
MediaWiki	1.25wmf20
Database changes	No
License	MIT License
Download	Download snapshot (Git master) Git [?]: repo summary browse file tree commit history code review README
Parameters $wgVisualEditorPluginModules $wgVisualEditorParsoidURL $wgVisualEditorParsoidPrefix $wgVisualEditorParsoidTimeout $wgVisualEditorNamespaces $wgVisualEditorSupportedSkins $wgVisualEditorUseChangeTagging $wgVisualEditorDisableForAnons $wgVisualEditorShowBetaWelcome $wgVisualEditorTabPosition $wgVisualEditorTabMessages
Hooks used BeforePageDisplay GetPreferences ListDefinedTags MakeGlobalVariablesScript ResourceLoaderTestModules GetBetaFeaturePreferences
Translate the VisualEditor extension if it is available at translatewiki.net
Check usage and version matrix; code metrics
Issues:	Open tasks · Report a bug

The VisualEditor project aims to create a reliable rich-text editor for the Web and for MediaWiki. More information can be found on the project page; this page is just about the VisualEditor-MediaWiki extension itself. The extension relies on the separate nodeJS-based Parsoid parser service to be up and running in order to edit pages. Stable release is planned for 2015.

Download

If you're using the latest stable version of MediaWiki you will need to download the VisualEditor-MediaWiki extension from the ExtensionDistributor page. The following download instructions are for use with the latest nightly build of MediaWiki only.

cd extensions
git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/VisualEditor.git
cd VisualEditor
git submodule update --init

 Note:

• VisualEditor-MediaWiki's master branch contains the latest code, as used at Wikimedia. This code is potentially slightly buggy or unstable, but is likely to have fewer bugs and more features than old builds.
• The master branch requires alpha builds of MediaWiki (currently, 1.25wmf16) and will not work with the older, official releases of MediaWiki like 1.24.1, for that use the REL1_24 branch.
• The git submodule update --init command is vital, as MediaWiki-VisualEditor needs the core VisualEditor submodule to work. If you do not use this command, VisualEditor will fail to work.

If you cannot use git (e.g. you are in an air-gapped installation), you can download a snapshot of VisualEditor-MediaWiki for master or for a release version of MediaWiki from the ExtensionDistributor page. After you've got the code, save it into the extensions/VisualEditor directory of your wiki.

Setting VisualEditor up

Dependencies

VisualEditor depends on the following extension:

• UniversalLanguageSelector

Setup a Parsoid service

 Note: Without the Parsoid node.js service you will not be able to edit existing pages or save pages!

If you want to be able to edit existing pages and save pages with VisualEditor you need a Parsoid service.

To setup your own Parsoid service follow the Parsoid installation instructions first. Note that it is particularly complicated to set up Parsoid in non-standard systems for running NodeJS, like those running Windows or Debian.

Basic configuration for MediaWiki-VisualEditor

For the initial setup, before you have installed the Parsoid node.js service you can experiment with loading MediaWiki-VisualEditor on your own wiki.

Add the following lines to your wiki's LocalSettings.php after you have downloaded the extension:

require_once "$IP/extensions/VisualEditor/VisualEditor.php";
 
// Enable by default for everybody
$wgDefaultUserOptions['visualeditor-enable'] = 1;
 
// Don't allow users to disable it
$wgHiddenPrefs[] = 'visualeditor-enable';
 
// OPTIONAL: Enable VisualEditor's experimental code features
#$wgDefaultUserOptions['visualeditor-enable-experimental'] = 1;

Other extensions which load plugins for VE (e.g. Math) should be loaded after VE for those plugins to work.

Linking with Parsoid

To get VisualEditor to talk to Parsoid, add the following code to your LocalSettings.php to specify your Parsoid instance:

// URL to the Parsoid instance
// MUST NOT end in a slash due to Parsoid bug
// Use port 8142 if you use the Debian package
$wgVisualEditorParsoidURL = 'http://localhost:8000';

Additionally, you may need to set the $wgVisualEditorParsoidPrefix prefix. If you only run a single wiki then you can leave its unique ID as "localhost" in parsoid's localsettings.js configuration file and do not need to set this. But if you are running multiple wikis on the same host then each will need a different interwiki name for parsoid (see Parsoid/Setup#Configuration for more detail), and you must set $wgVisualEditorParsoidPrefix to the interwiki name you give this wiki in parsoid's localsettings.js:

// Interwiki prefix to pass to the Parsoid instance
// Parsoid will be called as $url/$prefix/$pagename
$wgVisualEditorParsoidPrefix = 'myspecialwiki';

Linking with Parsoid in private wikis

Warning: The private wiki cookie forwarding feature described below does not appear to work for many private wikis. A solution using a modification to LocalSettings.php and the $_SERVER['REMOTE_ADDR'] variable appears to allow Parsoid to function with private wikis, by granting read access to connections that originate from the local server.

Forwarding Cookies to Parsoid

// Forward users' Cookie: headers to Parsoid. Required for private wikis (login required to read).
// If the wiki is not private (i.e. $wgGroupPermissions['*']['read'] is true) this configuration
// variable will be ignored.
//
// This feature requires a non-locking session store. The default session store will not work and
// will cause deadlocks when trying to use this feature. If you experience deadlock issues, enable
// $wgSessionsInObjectCache like this: 
//$wgSessionsInObjectCache = true;
//
// WARNING: ONLY enable this on private wikis and ONLY IF you understand the SECURITY IMPLICATIONS
// of sending Cookie headers to Parsoid over HTTP. For security reasons, it is strongly recommended
// that $wgVisualEditorParsoidURL be pointed to localhost if this setting is enabled.
$wgVisualEditorParsoidForwardCookies = true;

Note that this configuration is not available in the old version of VisualEditor that is compatible with MediaWiki 1.22.

Warning: ONLY enable this on private wikis and ONLY IF you understand the SECURITY IMPLICATIONS of sending Cookie headers to Parsoid over HTTP!

Note for MediaWiki 1.23 users

For MediaWiki 1.23, as well as the Parsoid nodejs service, you will also need to install the the Parsoid PHP extension. Without this, VisualEditor will fail to load (as it supplied key styling code until that was moved in MediaWiki itself in MediaWiki 1.24 onwards).

Note for Parsoid on Windows, Debian and other systems

Note that it is particularly complicated and time consuming to set up VisualEditor with Parsoid in non-standard systems, like those running Windows or Debian - those difficulties might even prevent the successful installation of VisualEditor for some people on some platforms.[1][2][3]

Complete list of configuration options

Each configuration option is shown without the $wgVisualEditor prefix for brevity.

Option	Default value	Useful for…	Documentation
PluginModules	[]	Extension developers	Array of ResourceLoader module names (strings) that should be loaded when VisualEditor is loaded. Other extensions that extend VisualEditor should add to this array. Warning: When removing a module on a production site (e.g. Wikimedia), first remove it from this array, wait for the change to propagate, and only then remove the module code and module registration. Otherwise there may be a period of time during which VisualEditor depends on a module that no/ longer exists.
PreferenceModules	'visualeditor-enable-experimental' => 'ext.visualEditor.experimental'	Extension developers	Associative array of ResourceLoader module names (strings) that should be loaded when VisualEditor is loaded if the current user has a preference set. Other extensions that extend VisualEditor should add to this array if they want their addition to be opt-in or opt-out. Keys are preference names, values are ResourceLoader module names. Remember to also set defaults in $wgDefaultUserOptions!
ParsoidURL	'http://localhost:8000'	Sysadmins	URL to the Parsoid instance if contacting it directly rather than through the REST service or via RESTbase. Warning: MUST NOT end in a slash due to a Parsoid bug
ParsoidHTTPProxy	false	Sysadmins	Proxy to use for curl requests to Parsoid; false means not to use a proxy.
ParsoidPrefix	'localhost'	Sysadmins	Interwiki prefix to pass to the Parsoid instance. Parsoid will be called as $url/$prefix/$pagename
ParsoidForwardCookies	false	Sysadmins of private wikis	Whether to forward users' Cookie: headers to Parsoid. This is currently required for private wikis (i.e., login is required to read). If the wiki is not private (i.e. $wgGroupPermissions['*']['read'] is true) this configuration variable will be ignored. This feature requires a non-locking session store. The default session store will not work and will cause deadlocks when trying to use this feature. If you experience deadlock issues, enable $wgSessionsInObjectCache. Warning: ONLY enable this on private wikis and ONLY IF you understand the MAJOR SECURITY IMPLICATIONS of sending Cookie headers to Parsoid over HTTP. For security reasons, it is very strongly recommended that wgVisualEditorParsoidURL be pointed to localhost if this setting is enabled.
ParsoidTimeout	100	Sysadmins	Timeout for HTTP requests to Parsoid in seconds
SerializationCacheTimeout	3600	Sysadmins	Serialization cache timeout, in seconds
RestbaseURL	false	Sysadmins	URL to use to access RESTbase. The page name will be appended directly to this value, so this needs to be set to something like 'https://rest.wikimedia.org/en.wikipedia.org/v1/page/html/' including the trailing slash. If this is set, the page HTML will be requested from RESTbase. If this is not set, the page HTML will be requested from the API, which will send an HTTP request to Parsoid or to RESTbase if available.
Namespaces	array_merge( $wgContentNamespaces, array( NS_USER ) )	Sysadmins	Namespaces in which to enable VisualEditor
EnableTocWidget	false	VisualEditor developers	Whether to enable the (experimental for now) Table Of Contents widget
SupportedSkins	array( 'vector', 'apex', 'monobook', 'minerva', 'blueprint' )	Skin developers	List of skins VisualEditor integration supports. If the user's skin is not matched, VisualEditor will refuse to load.
BrowserBlacklist	array( 'msie' => array ( array( '<=', 9 ) ), 'android' => array( array( '<', 3 ) ), 'firefox' => array( array( '<=', 14 ) ), 'safari' => array( array( '<=', 6 ) ), 'opera' => array( array( '<', 12 ) ), 'blackberry' => null, 'silk' => null, );	VisualEditor developers	List of browsers with which VisualEditor is incompatible. See jquery.Client for specification. If the user's browser is matched, VisualEditor will refuse to load. Internet Explorer – At or below version 8, there are various incompatibilities in layout and feature support; versions 10 & 11 have problems but mostly work OK-ish so they're greylisted; IE9 to come. Firefox – There are issues in versions 12 and below (task T52780); and a wikilink corruption ([[./]]) bug in Firefox 14 and below (task T52720) which prevent wider availability. Safari – Older versions of Safari suffered from corruption issues from various old browser plugins. Android – 2.x and below "support" CE but don't trigger keyboard input, making it useless for users. Opera – Below version 12 Opera was untested, and as its user base is almost nonexistent anyway it's blocked. Blackberry and Silk browsers are blacklisted at all versions due to reported issues and no appetite to support.
UseChangeTagging	true	Sysadmins	Whether to put a change tag on every edit made with VisualEditor.
DisableForAnons	false	Sysadmins	Whether to disable VisualEditor for logged-in users This allows you to enable the 'visualeditor-enable' preference by default, but still disable VisualEditor for logged-out users (by setting this to true).
ShowBetaWelcome	false	Sysadmins	Whether to show the "welcome to the beta" dialog the first time a user uses VisualEditor
TabPosition	'before'	Sysadmins	Where to put the VisualEditor edit tab in relation to the system (or WikiEditor) one: 'before': put it right before the old edit tab 'after': put it right after the old edit tab
EnableSplitTest	false	Analytics	Whether to enable VisualEditor for half of all new accounts (userID even).
TabMessages	'edit' => null, 'editsource' => 'visualeditor-ca-editsource', 'create' => null, 'createsource' => 'visualeditor-ca-createsource', 'editlocaldescriptionsource' => 'visualeditor-ca-ditlocaldescriptionsource', 'createlocaldescriptionsource' => 'visualeditor-ca-createlocaldescriptionsource', 'editsection' => null, 'editsectionsource' => 'visualeditor-ca-editsource-section', 'editsourceappendix' => null, 'createappendix' => null, 'createsourceappendix' => null, 'editsectionappendix' => null, 'editsectionsourceappendix' => null	Sysadmins	Configuration of what messages to use for the various kinds of edit tab users can see, and what appendices (if any) to show 'edit' – i18n message key to use for the VisualEditor edit tab; if null, the default edit tab caption will be used; the 'visualeditor-ca-ve-edit' message is available for this. 'editsource' – i18n message key to use for the old edit tab; if null, the tab's caption will not be changed 'create' – i18n message key to use for the VisualEditor create tab; if null, the default create tab caption will be used; the 'visualeditor-ca-ve-create' message is available for this 'createsource' – i18n message key to use for the old create tab; if null, the tab's caption will not be changed 'editlocaldescriptionsource' – i18n message key to use for the old edit tab on pages for files in foreign repos; if null, tab's caption will not be changed 'createlocaldescriptionsource' – i18n message key to use for the old create tab on pages for files in foreign repos; if null, tab's caption will not be changed 'editsection' – i18n message key to use for the VisualEditor section edit link; if null, the default edit section link caption will be used 'editsectionsource' – i18n message key to use for the source section edit link; if null, the link's caption will not be changed appendices – i18n message key(s) for an optional appendix to add to each of these from JavaScript; use this if you have HTML messages to add. The 'visualeditor-beta-appendix' message is available for this purpose. 'editappendix' – appendix to put on the VisualEditor edit tab; if null, show no appendix 'editsourceappendix' – appendix to put on the old edit tab; if null, show no appendix 'createappendix' – appendix to put on the VisualEditor create tab; if null, show no appendix 'createsourceappendix' – appendix to put on the old create tab; if null, show no appendix 'editsectionappendix' – appendix to put on the VisualEditor section edit link; if null, show no appendix 'editsectionsourceappendix' – appendix to put on the source section edit link; if null, show no appendix

Setting VisualEditor up on shared hosting

See VisualEditor on a shared host

Troubleshooting

parsoidserver-http-curl-error

couldn't connect to host.

Parsoid is not running, or $wgVisualEditorParsoidURL is not set correctly

parsoidserver-http-curl-error: Failed to connect to ....: Permission denied.

Can be caused by a cURL request on a Security-Enhanced Linux (SELinux, like CentOS) to a non standard port like 8000 in the example configuration above, see http://www.akashif.co.uk/php/curl-error-7-failed-to-connect-to-permission-denied

parsoidserver-http-bad-status: 401

Caused by read or edit restrictions. If you've set up a private wiki and don't want to use cookie forwarding, you can explicitly remove restrictions for Parsoid by IP address.

parsoidserver-http-not-found: 404 (or timeout)

Caused by wrong path to MediaWiki API endpoint. Set correct url to the right path to api.php in Parsoid's localsettings.js config file. If you have set up following the recommendations, your API path would be "http://localhost/w/api.php". Add this API path to "localsettings.js" like "parsoidConfig.setInterwiki( 'localhost', 'http://localhost/w/api.php' );".