Extension:TinyMCE

From mediawiki.org
MediaWiki extensions manual
TinyMCE
Release status: stable
Implementation Hook
Description Allows for editing pages, sections, form fields etc. using the TinyMCE JavaScript-based WYSIWYG editor
Author(s) Duncan Crane, Yaron Koren, Ephox Corporation, Hallo Welt! GmbH
Latest version 1.1 (May 2021)
Compatibility policy Master maintains backward compatibility.
MediaWiki 1.31+
Composer mediawiki/tinymce
License GNU General Public License 2.0 or later
Download See here
Example An example of TinyMCE on discoursedb.org
  • $wgTinyMCEUnhandledStrings
  • $wgTinyMCETemplates
  • $wgTinyMCEExtensionTags
  • $wgTinyMCEDefaultTags
  • $wgTinyMCEDisabledNamespaces
  • $wgTinyMCELoadOnView
  • $wgTinyMCEEnabled
  • $wgwgTinyMCESettings
  • $wgTinyMCEPreservedTags
Quarterly downloads 81 (Ranked 74th)
Translate the TinyMCE extension if it is available at translatewiki.net
Issues Open tasks · Report a bug

TinyMCE is a MediaWiki extension that lets users edit wiki pages using version 5 of 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.

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.

TinyMCE can be used 'out of the box' by following the installation instructions below. However, for more advanced uses, developers 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 and in forms) with different configurations for each editor instance if desired. The extension also allows users to access TinyMCE plugins produced by Ephox or third parties.

Those looking for documentation for earlier versions will them in the following locations for versions before V1.0 and version V1.0. Instructions for advance configuration can be found 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.1 as a 'zip' file please click here.

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;

If you install this extension, It is very important you applicate this patch.

Note: The patch is not necessary for MediaWiki 1.37 or higher.

You must then elect to use TinyMCE in your 'editing' preferences.

.

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:" namespaces 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 Additional menu items button menu button.

Toolbar Button Action performed
Link button 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 Unlink button button. Double-clicking an existing link will invoke the link dialog on that link, allowing parameters to be changed
Edit wikitext button 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.
Image button 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.
Toggle placeholder button will toggle the display of visible placeholders for non-rendered new lines, switches, comments and on-breaking spaces.
Non-breaking space button will insert a non-breaking space into the content at the cursor position.
No rendering new line button 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.
Reference button 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.
Comment button 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 Toggle placeholder button button.
Template button invokes a dialog for inserting TinyMCE templates (see TinyMCE Templates above).
Icon button 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.
Block markup options menu items Selecting the format dropdown menu, provides some mediawiki specific formats. these are:
  • Pre (without markup) - equivalent to <pre> block in wiki text
  • Pre (with markup) - equivalent to a psuedo pre, formed by placing a space at the start of each line
  • Code - equivalent to a wiki <code> block
  • Nowiki - equivalent to a <nowiki> block

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 Toggle placeholder button 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
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 shortcuts

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


Action PC Mac
Execute command ↵ Enter / Space ↵ Enter / Space
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)
/ /
Focus previous Control
(such as: toolbar button, menu, or menu item)
/ /
Open menu or toolbar menu button / Space / Space
Open group toolbar button Space Space
Open split toolbar button
Open the popup menu on split toolbar buttons ⇧ Shift+↵ Enter ⇧ Shift+↵ Enter
Open submenu
Close submenu / Esc / 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 button 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.