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.25wmf24
Database changes No
License MIT License
Download
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[edit | edit source]

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 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 (command : git clone -b REL1_24 https://gerrit.wikimedia.org/r/p/mediawiki/extensions/VisualEditor.git).
  • 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[edit | edit source]

Dependencies[edit | edit source]

VisualEditor depends on the following extension:

Setup a Parsoid service[edit | edit source]

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

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

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

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

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

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

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

Complete list of configuration options[edit | edit source]

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

See VisualEditor on a shared host

Troubleshooting[edit | edit source]

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