Extension:VisualEditor

MediaWiki extensions manual - list

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.22.2
Database changes	No
License	MIT
Download	Download snapshot (Git master) Git [?]: repo summary tree code changes 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 possible
Check usage and version matrix; code metrics
Bugs: list open list all report

The VisualEditor project aims to create a reliable rich-text editor for MediaWiki. More information can be found on the project page; this page is just about the 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.

Use at your own risk; it's not ready for production deployment except for experts! Patches welcome.

Download

You can download the extension directly from the MediaWiki source code repository (browse code). You can get:

One of the extensions tags

Not all extensions have tags. Some extensions have tags for each release, in which case those tags have the same stability as the release. To download a tag

• Go to the tags list
• Click the name of the tag you want to download
• Click "snapshot"

The latest version of one of the extensions branches

Each extension has a master branch containing the latest code (might be unstable). Extensions can have further branches as well.

• Go to the branches list
• Click the branch name
• Click "snapshot"

A snapshot made during the release of a MediaWiki version.

This might be unstable and is not guaranteed to work with the associated MediaWiki version.

• Download snapshot

After you've got the code, save it into the extensions/VisualEditor directory of your wiki.

If you are familiar with git and have shell access to your server, you can obtain the extension, with all its tags and branches, as follows:

cd extensions
git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/VisualEditor.git  

cd VisualEditor
git submodule update --init

Basic setup instructions

With the "basic setup" (without Parsoid) you can experiment with this extension on your own wiki. To do this add the following lines to your wiki's LocalSettings.php after you have downloaded the extension:

require_once("$IP/extensions/VisualEditor/VisualEditor.php");
 
// OPTIONAL: Enable VisualEditor in other namespaces
// By default, VE is only enabled in NS_MAIN
//$wgVisualEditorNamespaces[] = NS_PROJECT;
 
// 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
//$wgVisualEditorEnableExperimentalCode = true;

Congratulations, you should now have VisualEditor up and running! To test it you need to create a new page, depending on your setup you might end up in the standard editor or wikieditor but when you press the "Create" tab you should end up in the Visual editor.

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

Setup a Parsoid service

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.

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
$wgVisualEditorParsoidURL = 'http://localhost:8000';

Additionally, if you want to use a Parsoid instance with a wiki that isn't running on localhost, you will need to edit the following line (the default is fine for most people's configurations):

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

Configuration

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