Extension:TinyMCE

TinyMCE is a MediaWiki extension that lets users edit wiki pages using the popular open source JavaScript-based WYSIWYG editor TinyMCE created by Ephox Corporation. It is based on the BlueSpice VisualEditor extension (not to be confused with the standard VisualEditor extension), developed as part of the BlueSpice package by [http://hallowelt.com Hallo Welt! GmbH]. It was then modified significantly by Duncan Crane and Yaron Koren to work as a standalone extension, and to work within forms defined by the Page Forms extension.

The current release (version 1.0) has undergone a further major rewrite to use TinyMCE 5 and to give much greater functionality in the editor. This includes significant enhancements to: the copy/paste and drag/drop functionality; the file upload functionality; editing html embedded in the wiki text; and editing plain text (pre and nowiki blocks).

Users are also given total control over the configuration of TinyMCE from LocalSettings.php. This includes the ability to have multiple editor instances on a single page (in both page view mode iand in page edit mode when using PageForms) with different configurations for each editor instance if desired.

The TinyMCE extension provides users with an alternative to the standard VisualEditor. For example, they may want to integrate their wikis in an environment where other tools may already use TinyMCE, such as Angular, Bootstrap Django, Rails, React, Swing, Vue, Joomla and Wordpress to name a few.

The extension also allows users to access TinyMCE plugins produced by Ephox or Third parties. For example, included with the extension is a Fontawesome plugin created by Josh Hunt ([mailto:joshhunt180@gmail.com joshhunt180@gmail.com]). Other TinyMCE plugins that have been integrated include the N1ED bootstrap editor (https://n1ed.com/) and a plugin for the CodeMirror code editor, developed by Marijn Haverbeke.

Planned developments include integration with Parsoid and the ability to interact intelligently with mediwiki templates when inserting them.

As well as the original authors, whose work I have built on, I am very grateful toYaron Koren for his help in creating and maintaining this extension and to the team at Wikibase bv, who helped with extensive testing and encouragement to be more ambitious with the functionality.

Those looking for documentation for earlier versions than V1.0 will find it here.

Download
To get Version 1.0 of this extension please download from the master branch using the link in the Extension factbox

Installation
Please note, this extension is only tested on versions from LTS 1.31, and may well not work on earlier versions. If you are using MediaWiki 1.27 or higher, add the following line to your LocalSettings.php file:

For earlier versions, you should call the following instead :

Configuration
The TinyMCE extension comes with a default configuration. You can run the TinyMCE extension straight 'out of the box 'just by setting $wgTinyMCEEnabled to 'true' in LocalSettings.php and enabling it in the user's preferences.

The default configuration is defined in the files 'MW_tinymce.js' and 'MW_tinymce.css' in the root folder of the extension. TinyMCE has a very rich configuration environment which also makes it very easy to break! It is strongly recommended that these default configuration files are not changed but that one uses the configuration variables described below. The following variables are available:

Using $wgTinyMCESettings to configure the TinyMCE editor
The use of the $wgTinyMCESettings array is perhaps most easily explained by an example. At the top level, $wgTinyMCESettings is broken down into a number of key value pairs, where each key is a list of one or more selectors and each value is an array of configuration settings for 'textareas' that are identified by one or more of the selectors in the key.

$wgTinyMCESettings = array(		".terrapin, #wpTextbox1" => array ( .			.		// This sub-array contains TinyMCE configuration parameters applied to .		// textareas with selectors '.terrapin' or '#wpTextbox1'. Note '#wpTextbox1' .		// is the selector used by default for editing wiki pages or sections .		),		".tinymce" => array ( .			.		// This sub-array contains TinyMCE configuration parameters applied to .		// textareas with selector '.tinymce'. This allows alternative configurations .		// for different textareas. The number of different configurations is unlimited. .		)	); The sub-array settings correspond to TinyMCE configuration variables which can be single values, arrays or objects.

For single value configuration variables, defining a value in the sub-array will cause the new value to overwrite the default value. If the new value is empty, then the variable is removed from the default configuration and the TinyMCE default is applied.

For array and object configuration variables, one can also add a '+' or a '-' to the end of the key. If a '+' is added to the key, then the value is added to the default configuration array or object. If a '-' is added to the key, then the value is removed form the default configuration array or object. If neither a '+' or '-' is added then the new value replaces the default configuration value. The following example illustrates this:

$wgTinyMCESettings = array(		".terrapin, #wpTextbox1" => array ( "external_plugins+" => array (	// this variable adds (+) the custom fontawesome plugin 							// to the list of plugins to load				'fontawesome' => $wgScriptPath.'/extensions/TinyMCE/custom_plugins/fontawesome/plugins/fontawesome/plugin.min.js'			), "external_plugins-" => array (				'advlist'		// this variable removes (-) the standard advlist plugin         						// form the list of plugins to load			), "content_css+" => array (	// this variable adds (+) the custom fontawesome css to the							// list of css files to load				$wgScriptPath.'/extensions/TinyMCE/custom_plugins/fontawesome/plugins/fontawesome/css/all.min.css'			), "toolbar+" => ' | fontawesome',	// this variable adds (+) the custom fontawesome button to							// the end of the button bar "linkDialogNameCategories" => array (	// a blank value removes the variable 							// 'linkDialogNameCategories' from the default settings			), "linkDialogNameSpaces" => array (	// this variable (without + or - ) replaces the default 							// settings for 'linkDialogNameSpaces'				'main',				'talk'			), "tinyMCETemplates" => array(	// this is an array of TinyMCE template definitions, they each 							// have the same format				array( 'title' => 'Draw.io PNG', 'description' => 'Insert a parser function for referencing a drawio PNG image for display and editing', 'content' => '' ),			)		),		".tinymce" => array ( "inline" =&gt; "true",		// only works for pages in view mode, see $wgTinyMCELoadOnView // in the documentation below "external_plugins+" => array (	// this variable adds (+) the custom fontawesome plugin to the 							// list of plugins to load				'fontawesome' => $wgScriptPath.'/extensions/TinyMCE/custom_plugins/fontawesome/plugins/fontawesome/plugin.min.js'			), "content_css+" => array (	// this variable adds (+) the custom fontawesome css to the list							// of css files to load				$wgScriptPath.'/extensions/TinyMCE/custom_plugins/fontawesome/plugins/fontawesome/css/all.min.css'			), "toolbar" => ' | fontawesome',	// this variable replaces the toolbar with one that only // has the fontawesome button "height-" => '', )	);

Using $wgTinyMCELoadOnView to enable the TinyMCE editor on viewed pages
This is currently an experimental feature and I'm not able to guarantee its operation. It is provided for those who are willing to support themselves if they decide to use it.

If the configuration variable $wgTinyMCELoadOnView is set to true on LocalSettings.php it is possible to have editable areas in a page that is being viewed in the wiki (eg without selecting the 'Edit' tab or equivalent). In order for this to work, one also needs to set $wgRawHtml to true in local setting.

One can then uses html tags to include 'textarea' or 'division' definitions that the TinyMCE editor will be loaded into. One uses 'textarea' if the editor is to operate in an iframe and 'division' if it is to operate 'in line'. To use 'in-line' one must also set the configuration variable "inline" to 'true' for the appropriate selectors. In either case, one would need to write a 'handler' to update the page once the edit is finished. Currently this can be done using the WSforms extension but no handler is bundled with the TinyMCE extension. The following example illustrates the two approaches.

Using $wgTinyMCEDisabledNamespaces and __NOTINYMCE__ to disable TinyMCE
It is possible to disable the use of TinyMCE on pages, even if it's your default editor. To disable it on any given page, include the switch __NOTINYMCE__ on the page. In order to disable TinyMCE on a complete namespace then include the the namespace in the $wgTinyMCEDisabledNamespaces array. This array should be added after the code for loading the TinyMCE extension in LocalSettings.php. Please note also that TinyMCE is disabled by default on the Template and Form namespaces.

The following example disables all standard namespaces except for NS_MAIN. Even if TinyMCE is disabled in a namespace or on a page, it is still possible to use it in PageForms on a page that uses a it for editing, provided the form is configured to do that. Please see the PageForms documentation on how to do this.

TinyMCE Templates
You can have TinyMCE display custom "templates". These are one or more options that insert a custom bit of wikitext or html into the page. These will show up as options under the menu item in the TinyMCE display. They produce text that can either be inserted by itself, or "wraps" around whatever piece of text is already highlighted in the editor.

The example above for $wgTinyMCESettings illustrates how these templates are configured. Here is another (but please note, there is a separate menu option for citing references so this is not required as a template):

The syntax for defining templates can be found here.

Using with WikiEditor
You can use the TinyMCE extension in conjunction with the WikiEditor extension. If both extensions are installed, WikiEditor is available from an 'Edit source' tab on pages where TinyMCE is available on the 'Edit' tab or equivalent. WikiEditor will also be displayed on pages where TinyMCE is disabled. To do this, you just need to add this small patch to the WikiEditor code; it is a pending change that will hopefully get merged into the main WikiEditor code in the future. Please take care though. The patch must be added to the WikiEditor extension code and not the TinyMCE extension code

Context Menu
The TinyMCE editor has a context menu containing commonly used commands. This can be invoked by using the right mouse button (or equivalent). The browser context menu is still available and can be invoked by using the CTRL key and right mouse button together.

Usage
The TinyMCE extension adds another tab to any TinyMCE-editable page, which points to "action=tinymceedit". In the vector skin, it gives this tab the name "Edit", and renames the standard "Edit" tab to "Edit source" (in whatever language the wiki is in), in the same way that the VisualEditor extension does it.

By default, all namespaces other than "Template:" and Page Forms' "Form:" namespace are editable with TinyMCE.

Any user can get rid of TinyMCE tabs when they view pages by going to "Preferences", then clicking the "Editing" tab and deselecting the checkbox labeled "Use the TinyMCE editor to edit pages".

Toolbar buttons
There are a number of buttons on the TinyMCE editor toolbar designed for use with MediaWiki. Depending on configuration, some or all of these buttons may be shown on the 'overflow' menu which can be accessed by clicking on the menu button.

Placeholders
Templates, parser functions, links etc. are displayed as they would be rendered by MediaWiki, but behind a non-editable box. Switches in the wiki text are displayed as the section character &sect; behind a non-editable box as these are non-displayed commands to MediaWiki. Comments in the wiki text are displayed similarly as &#x1F4AC;. Because images are often displayed in a different location on the page to where they appear in the text, a placeholder &#x1F4F7; is used to show where they are in the text. All of these placeholders can be toggled on or off using the button. To edit their wiki code, select them and double click.

Drag/drop copy/paste
If one has the right permissions, it is possible to drag and drop, or copy and paste, html content into the editor. Links in the content will be converted into wikilinks. Images in the content will be uploaded and a wiki code reference will be created in the content. If copying between TinyMCE editor windows, then the translation between html and wikitext will be preserved. If pasting into a plain text element (eg a &lt;pre&gt; block or a pseudo pre block created with spaces at the start of each line) the the content will be displayed as the raw html or wikitext as appropriate. It is also possible to copy content from MSWord and Adobe PDF documents although  formatting may not be reproduced.

Escaping from blocks at start and end of content
When the cursor is in certain block elements, like tables, or &lt;div&gt; blocks at the start or end of the content, it can be difficult to exit the block structure using return on the key-pad, as &lt;p&gt; blocks are valid content within these elements. Using up or down arrow at the start or end of the content will create a new &lt;p&gt; block before or after the element currently containing the cursor.

Keyboard shortcuts
Accessibility  shortcuts This is a list of available keyboard shortcuts within the editor user interface.

data-mwt-tableStartNewLines=1&gt;

TinyMCE custom plugins
As noted in the introduction, there are a number of plugins available for use with TinyMCE. In addition to the standard set the following have been implemented in this extension: