Extension: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.27.0-alpha | ||
| Database changes | No | ||
| License | MIT License | ||
| Download |
README |
||
|
|||
|
|||
|
Translate the VisualEditor extension if it is available at translatewiki.net |
|||
| Check usage and version matrix. | |||
| 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.
Contents
User guide
See Help:VisualEditor/User guide.
Download
For the General User: If you're using the latest stable version of MediaWiki you will need to download the VisualEditor-MediaWiki extension from the ExtensionDistributor page.
For the Advanced User:
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.28-wmf.8) and will not work with the older, official releases of MediaWiki like 1.26.2; for that, use the REL1_26 branch (command:
git clone -b REL1_26 https://gerrit.wikimedia.org/r/p/mediawiki/extensions/VisualEditor.git). - The
git submodule update --initcommand 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
Set up a Parsoid service
If you want to be able to edit existing pages and save pages with VisualEditor you need a Parsoid service that converts between wikitext and the HTML that VisualEditor displays for editing.
To set up your own Parsoid service follow the Parsoid installation instructions before setting up VisualEditor. Note that it can be particularly complicated to set up Parsoid and Node.js in non-standard systems, like those running Windows or Debian.
Basic configuration for MediaWiki-VisualEditor
By default, MediaWiki-VisualEditor does not enable itself for users. To make it available, 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;
// Optional: Set VisualEditor as the default for anonymous users
// otherwise they will have to switch to VE
// $wgDefaultUserOptions['visualeditor-editor'] = "visualeditor";
// Don't allow users to disable it
$wgHiddenPrefs[] = 'visualeditor-enable';
// OPTIONAL: Enable VisualEditor's experimental code features
#$wgDefaultUserOptions['visualeditor-enable-experimental'] = 1;
Note that you can do this before you have installed the Parsoid node.js service to experiment with VE; this will mean that you can try the editor out in 'create' mode on your own wiki, but you will not be able to save or edit existing pages.
Other extensions which load plugins for VE (e.g. Math) can be loaded before or after VE if you are using MediaWiki 1.25 or later; the plugins should work either way.
Linking with Parsoid
To get VisualEditor to talk to Parsoid, add the following code to your LocalSettings.php to specify your Parsoid instance:
$wgVirtualRestConfig['modules']['parsoid'] = array(
// URL to the Parsoid instance
// Use port 8142 if you use the Debian package
'url' => 'http://localhost:8000',
// Parsoid "domain", see below (optional)
'domain' => 'localhost',
// Parsoid "prefix", see below (optional)
'prefix' => 'localhost'
);
A single Parsoid server can handle multiple wikis. The Parsoid domain setting identifies your wiki configuration to Parsoid. By default it is set to the hostname named by $wgCanonicalServer, but you can pick an arbitrary string. Older versions of Parsoid also used a unique "prefix" to identify the server; you may need to list that here as well.
Parsoid must have been configured to match, using a line in Parsoid's localsettings.js like:
parsoidConfig.setMwApi({ uri: 'http://path/to/my/wiki/api.php', domain: 'localhost', prefix: 'localhost' });
Again, the "domain" property is optional in the Parsoid configuration; it defaults to the hostname used in the uri property if not specified. The "prefix" property can also be omitted unless you are running an older version of Parsoid.
See Parsoid/Setup#Configuration for more details.
Servers with multiple virtual sites
If Apache2 is configured with multiple virtual sites, Parsoid is (in standard configuration) only able to access the default site. To check for this problem, run curl '[http://your-wiki-base-url]/api.php' on the server.
If the response starts with:
<!DOCTYPE html><html lang="en-GB" dir="ltr" class="client-nojs"><head><meta charset="UTF-8" /><title>MediaWiki API help - ['''''Name of your wiki''''']</title>
then you don't have the problem, but if it doesn't, you may need to configure a host alias that Parsoid can use:
Look at the apache2 configuration file for the virtual server hosting the wiki, near the top of the file there should be la line like:
<VirtualHost *:80>
If the '*' is present, then the alias can be to localhost, if there is an IP address replacing the '*' then the alias must be to that IP address.
In the same file add a line:
ServerAlias my_wiki_alias
In the hosts file of the server, add a route for my_wiki_alias, either for 127.0.0.1 (if the apache2 virtual server configuration had the '*' above, else to the IP address from the apache2 virtual server configuration.
Finally, in the Parsoid localsettings.js file, find the parsoidConfig.setMwApi setting, and set it to:
parsoidConfig.setMwApi({
uri: 'http://my_wiki_alias:80/path-to-my-wiki/api.php',
domain: '/* my Parsoid "domain" matching the value in LocalSettings.php */',
prefix: '/* my Parsoid "prefix" matching the value in LocalSettings.php */'
});
Reload the network config, apache config and Parsoid config, and retest the curl command above.
The same method works for multiple wikis hosted on multiple virtual servers on a host (use a different alias and add a parsoidConfig.setMwApi setting for each wiki).
Linking with Parsoid in private wikis
Forwarding Cookies to Parsoid
// This feature requires a non-locking session store. The default session store will not work and
// will cause deadlocks (connection timeouts from Parsoid) when trying to use this feature.
$wgSessionsInObjectCache = true;
// 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.
//
// 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 $wgVisualRestConfig['modules']['parsoid']['url'] be pointed to localhost if this setting is enabled.
$wgVirtualRestConfig['modules']['parsoid']['forwardCookies'] = true;
Warning:ONLY enable this on private wikis and ONLY IF you understand the SECURITY IMPLICATIONS of sending Cookie headers to Parsoid over HTTP! (but see the HTTPS section below)
An alternative to the approach above is explicitely giving read permissions to requests from the parsoid server as mentioned in: explicitly remove restrictions for Parsoid by IP address.
Parsoid over HTTPS
By default, Parsoid only supports HTTP connections. However, it's easy to provide HTTPS Parsoid by using Stunnel, a utility which offers SSL wrapping for arbitrary sockets. Most Unix distributions have 'stunnel' or 'stunnel4' package available from the repository. The following config file shard (e.g. /etc/stunnel/parsoid.conf) should do the trick:
cert = /etc/ssl/my_certs/parsoid.crt
key = /etc/ssl/my_keys/mykey.key
CAfile = /etc/ssl/my_ca/ca.crt
[parsoid]
accept = 8143
connect = 8142
Where [parsoid] is a new subdomain which is created. Once this is working, you can use the appropriate URL (e.g. 'https://parsoid.mydomain.com:8143') in your MediaWiki configuration for VisualEditor. You can use and existing subdomain (e.g. [wiki] if it's listed in yours .crt file and then the appropriate URL will become: https://wiki.mydomain.com:8143).
Setting up such a configuration allows you to avoid the security implications of transmitting parsoid cookies in cleartext.
Producing and installing SSL certificates is beyond the scope of this document.
Parsoid Authentication Without Forwarding Cookies
The forwarding of cookies (and the enabling of $wgSessionsInObjectCache and the forwardCookies property) can be avoided by adding a user (which may be called parsoid) to the wiki and then add the NetworkAuth Extension to the wiki with the configuration in LocalSettings.php:
require_once( "$IP/extensions/NetworkAuth/NetworkAuth.php" );
$wgNetworkAuthUsers[] = array(
'iprange' => array('127.0.0.1/32'),
'user' => 'parsoid');
Where the IP address matches that of the Parsoid server and the user matches the one you added to the wiki. This should of course only be done if the Parsoid server is on a 'trusted' network.
See also:
- Alternative solution using a modification to LocalSettings.php and the $_SERVER['REMOTE_ADDR'] variable, which grants read access to connections that originate from the local server.
Note for MediaWiki 1.23 users: For MediaWiki 1.23, as well as the Parsoid nodejs service, you will also need to install 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: It is particularly complicated and time consuming to set up VisualEditor with Parsoid in non-standard systems, like those running Windows or non-standard 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
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.
|
||
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 |
||
RestbaseURL |
false
|
Sysadmins | URL to use to access the main RESTbase call. The page name will be appended directly to this value, so this needs to be set to something like 'https://en.wikipedia.org/api/rest_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. |
||
FullRestbaseURL |
false
|
Sysadmins | URL to use to access the rest of RESTbase. The page name will be appended directly to this value, so this needs to be set to something like 'https://en.wikipedia.org/api/rest_' excluding the trailing slash. |
||
SerializationCacheTimeout |
3600
|
Sysadmins | Serialization cache timeout, in seconds | ||
AvailableNamespaces |
{
"2": true,
"_merge_strategy": "array_plus"
}
|
Sysadmins | Namespaces in which to enable VisualEditor (mapped from namespace ID to a boolean flag). | ||
UseChangeTagging |
true
|
Sysadmins | Whether to put a change tag on every edit made with VisualEditor. | ||
UseSingleEditTab |
false
|
Sysadmins | Whether to use only one edit tab, switching back and forth, or add a dedicated VisualEditor edit tab next to the existing one.
Note that the bi-directional switching functionality requires RESTbase installation rather than talking directly to Parsoid. |
||
SingleEditTabSwitchTime |
20160101000000
|
Sysadmins | From what timestamp to warn existing editors that the installation has switched from two edit tabs to one. In general you should ignore this. | ||
TabPosition |
'before'
|
Sysadmins | If showing two edit tabs, where to put the VisualEditor edit tab in relation to the system (or WikiEditor) one:
|
||
TabMessages |
{
"edit": null,
"editsource": "visualeditor-ca-editsource",
"create": null,
"createsource": "visualeditor-ca-createsource",
"editlocaldescriptionsource": "visualeditor-ca-editlocaldescriptionsource",
"createlocaldescriptionsource": "visualeditor-ca-createlocaldescriptionsource",
"editsection": null,
"editsectionsource": "visualeditor-ca-editsource-section"
}
|
Sysadmins | Configuration of what messages to use for the various kinds of edit tab users can see, if showing two edit tabs:
'edit' – i18n message key to use for the VisualEditor edit tab; if 'editsource' – i18n message key to use for the old edit tab; if 'create' – i18n message key to use for the VisualEditor create tab; if 'createsource' – i18n message key to use for the old create tab; if 'editlocaldescriptionsource' – i18n message key to use for the old edit tab on pages for files in foreign repos; if 'createlocaldescriptionsource' – i18n message key to use for the old create tab on pages for files in foreign repos; if 'editsection' – i18n message key to use for the VisualEditor section edit link; if 'editsectionsource' – i18n message key to use for the source section edit link; if |
||
AutoAccountEnable |
false
|
Sysadmins | Whether to enable VisualEditor for every new account.
This allows you to keep the ' |
||
DisableForAnons |
false
|
Sysadmins | Whether to disable VisualEditor for non-logged-in users
This allows you to enable the ' |
||
TransitionDefault |
false
|
Sysadmins | For wikis planning to use the 'visualeditor-betatempdisable' preference to auto-opt-out existing users whilst enabling by default for all existing users, whether to start recording explicit opt-outs against implicit ones. |
||
ShowBetaWelcome |
true
|
Sysadmins | Whether to show the "welcome to the beta" dialog the first time a user uses VisualEditor | ||
NewAccountEnableProportion |
false
|
Sysadmins running user analytics | Whether to enable VisualEditor for a proportion (Egyptian fraction) of all new accounts based on userID. | ||
FeedbackTitle |
false
|
Sysadmins | Whether to enable the MediaWiki feedback tool inside the help menu of VisualEditor. If enabled, the title of the page at which to point the MediaWiki feedback tool. | ||
FeedbackAPIURL |
false
|
Sysadmins | If set, the API of the remote wiki at which to point the MediaWiki feedback tool. | ||
SupportedSkins |
[
"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. | ||
SkinToolbarScrollOffset |
[]
|
Skin developers | An array of skin names mapped to pixel values to which to set the toolbar scroll offsets. | ||
BrowserBlacklist |
{
"msie": [
[
"<=",
8
]
],
"android": [
[
"<",
3
]
],
"firefox": [
[
"<=",
14
]
],
"safari": [
[
"<=",
6
]
],
"opera": [
[
"<",
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; version 9 has problems but mostly works OK-ish so they're it's greylisted. Versions 10 and 11 should work correctly. Firefox – There are issues in versions 12 and below (task T52780); and a wikilink corruption ( 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 non-existent anyway it's blocked. Blackberry and Silk browsers are blacklisted at all versions due to reported issues and no appetite to support. |
||
EnableTocWidget |
false
|
VisualEditor developers | Whether to enable the (currently experimental) Table Of Contents widget |
Old configuration parameters
As above, each configuration option is shown without the $wgVisualEditor prefix for brevity.
| Option | Default value | Documentation |
|---|---|---|
Namespaces |
|
List of namespaces IDs where is the VisualEditor is activated.
This parameter has been essentially replaced by |
See VisualEditor/Installation on a shared host
Troubleshooting
- Error loading data from server: HTTP 500. Would you like to retry?
- "curl", "php5-curl", or "php7.0-curl" is not installed or not accessible to your server.
- Or you setMwApi uri is set incorrectly with e.g. https instead of http. Or there is a rewrite rule in your apache configuration.
- parsoidserver-http-curl-error: couldn't connect to host.
- Parsoid is not running, or
$wgVisualEditorParsoidURLis 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 and https://www.centos.org/forums/viewtopic.php?f=47&t=53223&p=225372#p225372
- 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.phpin Parsoid'slocalsettings.jsconfig 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.setMwApi({uri: 'http://localhost/w/api.php' });". - No visible error (Appears to load forever)
- Check the parsoid log file, and consult Parsoid/Troubleshooting.
 |
This extension is being used on one or more Wikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's CommonSettings.php and InitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's Special:Version page. |
- MIT licensed extensions
- Beta status extensions
- Page action extensions
- Extended syntax extensions
- Beta Feature extensions
- Skin extensions
- Extensions in Wikimedia version control
- BeforePageDisplay extensions
- GetPreferences extensions
- ListDefinedTags extensions
- MakeGlobalVariablesScript extensions
- ResourceLoaderTestModules extensions
- GetBetaFeaturePreferences extensions
- SkinEditSectionLinks extensions
- All extensions
- Extensions used on Wikimedia
- WYSIWYG extensions
- VisualEditor
