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.25wmf13
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 2014-15.

§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 the parser, 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, the prefix needs to be set to the unique name you gave to the wiki in your localsettings.js parsoid configuration file. If you only run a single wiki then you will most likely have left it's unique ID as "localhost" and therefore will not need to set the prefix here. But if you are running multiple wikis on the same host then each will need to have a different unique ID (see Parsoid/Setup#Configuration for more detail), and you specify which one you're referring to here:

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

§Linking with Parsoid in private wikis

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

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

§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 configuration options

// URL to the Parsoid instance
// MUST NOT end in a slash due to Parsoid bug
$wgVisualEditorParsoidURL = 'http://localhost:8000';
 
// Proxy to use for curl requests.
// false: use direct connection to Parsoid daemon ($wgHTTPProxy is not used
// either)
$wgVisualEditorParsoidHTTPProxy = false;
 
// Interwiki prefix to pass to the Parsoid instance
// Parsoid will be called as $url/$prefix/$pagename
$wgVisualEditorParsoidPrefix = 'localhost';
 
// 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.
//
// NOTE: 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, causing you to receive "MWHttpRequest"
// errors. If you have a private wiki and are using the default session store in Apache, be sure to
// uncomment this line.
// $wgSessionsInObjectCache = true;
//
// WARNING: ONLY enable forwarding users' cookies 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 = false;
 
// Timeout for HTTP requests to Parsoid in seconds
$wgVisualEditorParsoidTimeout = 100;
 
// Serialization cache timeout, in seconds
$wgVisualEditorSerializationCacheTimeout = 3600;
 
// Namespaces to enable VisualEditor in
$wgVisualEditorNamespaces = array_merge( $wgContentNamespaces, array( NS_USER ) );
 
// Whether to enable the (experimental for now) TOC widget
$wgVisualEditorEnableTocWidget = false;
 
// List of skins VisualEditor integration supports
$wgVisualEditorSupportedSkins = array( 'vector', 'apex', 'monobook', 'minerva' );
 
// Whether to use change tagging for VisualEditor edits
$wgVisualEditorUseChangeTagging = true;
 
// Whether to disable for logged-in users
// This allows you to enable the 'visualeditor-enable' preference by default
// but still disable VE for logged-out users (by setting this to false).
$wgVisualEditorDisableForAnons = false;
 
// Whether to show the "welcome to the beta" dialog the first time a user uses VisualEditor
$wgVisualEditorShowBetaWelcome = false;
 
// Where to put the VisualEditor edit tab
// 'before': put it right before the old edit tab
// 'after': put it right after the old edit tab
$wgVisualEditorTabPosition = 'before';
 
$wgVisualEditorTabMessages = array(
	// 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
	'edit' => null,
	// i18n message key to use for the old edit tab
	// If null, the tab's caption will not be changed
	'editsource' => 'visualeditor-ca-editsource',
	// 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
	'create' => null,
	// i18n message key to use for the old create tab
	// If null, the tab's caption will not be changed
	'createsource' => 'visualeditor-ca-createsource',
	// i18n message key to use for the VisualEditor section edit link
	// If null, the default edit section link caption will be used
	'editsection' => null,
	// i18n message key to use for the source section edit link
	// If null, the link's caption will not be changed
	'editsectionsource' => 'visualeditor-ca-editsource-section',
 
	// i18n message key for an optional appendix to add to each of these from JS
	// Use this if you have HTML messages to add
	// The 'visualeditor-beta-appendix' message is available for this purpose
	'editappendix' => null,
	'editsourceappendix' => null,
	'createappendix' => null,
	'createsourceappendix' => null,
	'editsectionappendix' => null,
	'editsectionsourceappendix' => null,
);

§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' );".