Extension:TinyMCE/Archive Documents/Pre V 1.1
TinyMCE is a MediaWiki extension that lets users edit wiki pages using the popular open source JavaScript-based WYSIWYG editor TinyMCE created by Ephox corp. The editor can be added to the standard edit page, to forms defined by the Page Forms extension, and to regular pages in view mode. Users are 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 and in forms) 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 this extension is a plugin for Fontawesome. Other plugins available include the N1ED bootstrap editor and the CodeMirror code editor.
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 embedded plain text (pre and nowiki blocks); and inserting and editing references and comments inline.
Those looking for documentation for earlier versions than V1.0 will find it here.
Planned developments include integration with Parsoid and the ability to interact intelligently with MediaWiki templates when inserting them.
Download
[edit]To get Version 1.0 of this extension please download from the master branch using the link in the Extension factbox
Installation
[edit]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:
wfLoadExtension( 'TinyMCE' );
$wgTinyMCEEnabled = true;
For earlier versions, you should call the following instead ():
require_once "$IP/extensions/TinyMCE/TinyMCE.php";
$wgTinyMCEEnabled = true;
You must then elect to use TinyMCE in you 'editing' preferences.
.
Configuration
[edit]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:
| Variable | Function |
|---|---|
| $wgTinyMCEEnabled = true; | This makes the TinyMCE editor available for users to use if they have selected it in their preferences. The default is 'false' |
| $wgTinyMCESettings = array( ... ) | This passes TinyMCE configuration parameters to the TinyMCE editor. More detail is provided below. |
| $wgTinyMCELoadOnView = true; | This makes the TinyMCE editor available in textareas when pages are being viewed. More detail is provided below. |
| $wgTinyMCEDisabledNamespaces = array (... ) | An array of namespaces where the TinyMCE editor is disabled |
Using $wgTinyMCESettings to configure the TinyMCE editor
[edit]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' => '{{#drawio:<span class="selectedcontent">INSERT_NAME_HERE</span>|type=png}}'
),
)
),
".tinymce" => array (
"inline" => "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
[edit]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.
{{#tag:html|
<form action="get">
<div id="test-0" class="terrapin" name="test0" >Click here to edit</div>
<input type="submit" value="Submit">
</form>
<form action="get">
<textarea id="test-1" class="tinymce mcePartOfTemplate" name="test0" >Testing edit on page read tab</textarea>
<input type="submit" value="Submit">
</form>
}}
Using $wgTinyMCEDisabledNamespaces and __NOTINYMCE__ to disable TinyMCE
[edit]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.
$wgTinyMCEDisabledNamespaces = array(
NS_TALK,
NS_USER,
NS_USER_TALK,
NS_PROJECT,
NS_PROJECT_TALK,
NS_IMAGE,
NS_IMAGE_TALK,
NS_FILE,
NS_FILE_TALK,
NS_MEDIAWIKI,
NS_MEDIAWIKI_TALK,
NS_TEMPLATE,
NS_TEMPLATE_TALK,
NS_HELP,
NS_HELP_TALK,
NS_CATEGORY,
NS_CATEGORY_TALK
);
TinyMCE Templates
[edit]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):
'TinyMCETemplates' => array(
array(
'title' => 'Reference',
'description' => 'Insert an reference into the text',
'content' => '<ref>!INSERT TEXT HERE!</ref>'
),
);
The syntax for defining templates can be found here.
Using with WikiEditor
[edit]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
[edit]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
[edit]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
[edit]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.
| Toolbar Button | Action performed |
|---|---|
|
invokes a dialog for inserting or editing a link, including both "external" and "internal" (wiki page) links. If anything is selected when the button is pressed it will form the label part of the link. A link can be broken by selecting it and clicking the  button. Double-clicking an existing link will invoke the link dialog on that link, allowing parameters to be changed
|
|
invokes a dialog which allows editing the selected content as wiki text. If nothing is selected then the whole content is inserted into the dialog. Double clicking elements that are formatted by the wiki parser (eg templates, parser functions, switches, comments) will invoke the wiki text editor on these elements. |
|
invokes a dialog for uploading a file. One can upload from a local disk, from a url or just link to another file already uploaded to the wiki, depending on the permissions granted to the user. If the file is an image, a second page of the dialog allows one to set the parameters for how the file is displayed. On upload the width defaults to 300 and the format to 'thumb'. Double clicking an file embedded in the page will invoke the file upload dialog on it. |
|
will toggle the display of visible placeholders for non-rendered new lines, switches, comments and on-breaking spaces. |
|
will insert a non-breaking space into the content at the cursor position. |
|
will insert a non rendering (single) new line into the content at the cursor position. These are used in formatting the raw wiki text but otherwise not displayed in the rendered html. If the language you use is 'right-to-left' the image on the bitton (and the visible placeholder if displayed) will be rotated around the vertical axis. |
|
will insert a citation or reference into the content at the cursor position. If anything is selected when the button is pressed it will form the content of the reference. The reference is initially displayed as [[n]] in the editor. If one double clicks this placeholder the content of the reference is made available for editing in a box surrounded by a red line next to it. Double clicking the placeholder again will hide the reference content again. References can contain formatted text, but mustn't include other references. On saving, the placeholder will be replaced by the appropriate sequence number for the reference in the text. |
|
will insert a comment into the content at the cursor position. If anything is selected when the button is pressed it will form the content of the comment. The comment is initially displayed
as 💬 in the editor. If one double clicks this placeholder the content of the comment is made available for editing in a box surrounded by a red line next to it. Double clicking the placeholder again will hide the comment content again. Comments are plain text only. Because comments are not displayed in the rendered page, display of comment placeholders can be toggled on or off using the |
|
invokes a dialog for inserting TinyMCE templates (see TinyMCE Templates above). |
|
invokes a dialog for insert fontawesome symbols, if you have that plugin enabled. The plugin ships with the extension but isn't enabled by default. The second part of the example in Using $wgTinyMCESettings to configure the TinyMCE editor above shows the settings for doing this in LocalSettings.php. |
|
Selecting the format dropdown menu, provides some mediawiki specific formats. these are:
|
Placeholders
[edit]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 § behind a non-editable box as these are non-displayed commands to MediaWiki. Comments in the wiki text are displayed similarly as 💬. Because images are often displayed in a different location on the page to where they appear in the text, a placeholder 📷 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
[edit]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 <pre> 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
[edit]When the cursor is in certain block elements, like tables, or <div> 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 <p> blocks are valid content within these elements. Using up or down arrow at the start or end of the content will create a new <p> block before or after the element currently containing the cursor.
Keyboard shortcuts
[edit]| Action | PC | Mac | Core/Plugin</thead> |
|---|---|---|---|
| Bold | Ctrl+B | Command+B | core |
| Italic | Ctrl+I | Command+I | core |
| Underline | Ctrl+U | Command+U | core |
| Select All | Ctrl+A | Command+A | core |
| Redo | Ctrl+Y / Ctrl+Shift+Z | Command+Y / Command+Shift+Z | core |
| Undo | Ctrl+Z | Command+Z | core |
| Header 1 | Alt+Shift+1 | Ctrl+Option+1 | core |
| Header 2 | Alt+Shift+2 | Ctrl+Option+2 | core |
| Header 3 | Alt+Shift+3 | Ctrl+Option+3 | core |
| Header 4 | Alt+Shift+4 | Ctrl+Option+4 | core |
| Header 5 | Alt+Shift+5 | Ctrl+Option+5 | core |
| Header 6 | Alt+Shift+6 | Ctrl+Option+6 | core |
| Paragraph | Alt+Shift+7 | Ctrl+Option+7 | core |
| Div | Alt+Shift+8 | Ctrl+Option+8 | core |
| Address | Alt+Shift+9 | Ctrl+Option+9 | core |
| Focus to menu bar | Alt+F9 | Option+F9 | core |
| Focus to toolbar | Alt+F10 | Option+F10 | core |
| Focus to element path | Alt+F11 | Option+F11 | core |
| Focus to contextual toolbar | Ctrl+F9 | Ctrl+F9 | core |
| Open the help dialog | Alt+0 | Option+0 | help |
| Insert link | Ctrl+K | Command+K | wikilink |
| Insert link | Ctrl+[ | Command+[ | wikilink |
| Insert link | Ctrl+] | Command+] | wikilink |
| Inser non-breaking space | Ctrl+space | Command+space | wikinonbreakingspace |
| Insert Reference | Ctrl+Shift+* | Command+Shift+* | wikireference |
| Toggle Fullscreen | Ctrl+Shift+F | Command+Shift+F | fullscreen |
| Save | Ctrl+S | Command+S | save |
| Find | Ctrl+F | Command+F | searchreplace |
| Insert paragraph after block | Ctrl+Return | Command+Return | wikiparser |
| Insert paragraph after block | Shift+Alt+Return | Ctrl+Option+Return | wikiparser |
Accessibility' sho'rtcuts
This is a list of available keyboard shortcuts within the editor user interface.
data-mwt-tableStartNewLines=1>
| Action | PC | Mac</thead> |
|---|---|---|
| Execute command | Enter / Spacebar | Enter / Spacebar |
| Focus on next UI Element (such as: Menu bar, Toolbar, Toolbar Group, Status Bar Item) |
Tab | Tab |
| Focus on previous UI Element (such as: Menu bar, Toolbar, Toolbar Group, Status Bar Item) |
Shift+Tab | Shift+Tab |
| Focus next Control (such as: toolbar button, menu, or menu item) |
Right Arrow / Down Arrow | Right Arrow / Down Arrow |
| Focus previous Control (such as: toolbar button, menu, or menu item) |
Left Arrow / Up Arrow | Left Arrow / Up Arrow |
| Open menu or toolbar menu button | Down Arrow / Spacebar | Down Arrow / Spacebar |
| Open group toolbar button | Spacebar | Spacebar |
| Open split toolbar button | Down Arrow | Down Arrow |
| Open the popup menu on split toolbar buttons | Shift+Enter | Shift+Enter |
| Open submenu | Right Arrow | Right Arrow |
| Close submenu | Left Arrow / Esc | Left Arrow / Esc |
| Close dialog | Esc | Esc |
| Close menu | Esc | Esc |
| Move focus back to editor body | Esc | Esc |
TinyMCE custom plugins
[edit]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:
| Plugin name | Notes |
|---|---|
| fontawesome | This is based on the fontawesome plugin for TinyMCE created by Josh Hunt (https://github.com/josh18/TinyMCE-FontAwesome-Plugin). There is an icon added to the TinyMCE toolbar which allows the user to insert a fontawesome icon into the page. In order for mediawiki to display these icons on the wiki page the following should be inserted at the top of the mediawiki:common.css page in the wiki:
@import url("extensions/TinyMCE/tinymce/plugins/fontawesome/css/font-awesome.min.css");
|
Authors and credits
[edit]The TinyMCE extension of course includes the TinyMCE JavaScript-based editor, created by Ephox Corporation. This extension is based on the BlueSpice VisualEditor extension (not to be confused with the standard VisualEditor extension), developed as part of the BlueSpice package by 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. Duncan Crane is this extension's current maintainer.
The Fontawesome plugin was created by Josh Hunt (joshhunt180@gmail.com). The CodeMirror code editor plugin was developed by Marijn Haverbeke.
Thanks also to the team at Wikibase bv, who helped with extensive testing and encouragement to be more ambitious with the functionality.