Extension:VisualEditor

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
VisualEditor

Release status: beta

VisualEditor-logo.svg
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.24
Database changes No
License MIT
Download Download REL1_23 archive

Git:

Do not use Special:ExtensionDistributor as it cannot cope with submodules so VisualEditor will silently not load.
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
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.

Download[edit | edit source]

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

Via git

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

If you want to use the version for MediaWiki 1.23, then do:

git checkout REL1_23
git submodule update --init
A manual tarball snapshot made for MediaWiki 1.23

This should work with MediaWiki 1.23 if you wish to avoid using git.

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

For MediaWiki 1.23, as well as the Parsoid nodejs service, you will also need to install the the Parsoid PHP extension or VisualEditor will fail to load.

Basic setup instructions[edit | edit source]

With the "basic setup" (without the Parsoid node.js service, but with Parsoid helper extension, if required) 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 Note:Without the Parsoid node.js service you will not be able to edit existing pages or save pages!

Setup a Parsoid service[edit | edit source]

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[edit | edit source]

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, 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[edit | edit source]

Warning 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[edit | edit source]

// 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[edit | edit source]

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.