Extension:TinyMCE

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manualManual:Extensions
Crystal Clear action run.svg
TinyMCE

Release status:Extension status beta

ImplementationTemplate:Extension#type Hook
DescriptionTemplate:Extension#description Allows for editing pages using the TinyMCE JavaScript-based WYSIWYG editor
Author(s)Template:Extension#username Ephox Corporation, Hallo Welt! GmbH, Duncan Crane, Yaron Koren
Latest versionTemplate:Extension#version 0.2 (May 2018(2018-05))
MediaWikiTemplate:Extension#mediawiki 1.23+
LicenseTemplate:Extension#license GNU General Public License 2.0 or later
Download

See here

ExampleTemplate:Extension#example An example of TinyMCE on discoursedb.org
Hooks usedTemplate:Extension#hook
MakeGlobalVariablesScriptManual:Hooks/MakeGlobalVariablesScript
SkinTemplateNavigationManual:Hooks/SkinTemplateNavigation
SkinEditSectionLinksManual:Hooks/SkinEditSectionLinks
LinkEndManual:Hooks/LinkEnd
EditPageBeforeEditToolbarManual:Hooks/EditPageBeforeEditToolbar
AdminLinksManual:Hooks/AdminLinks
GetPreferencesManual:Hooks/GetPreferences

Translate the TinyMCE extension if it is available at translatewiki.net

Check usage and version matrix.

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 Hallo Welt! GmbH. It was then modified significantly by Duncan Crane and Yaron Koren to work better as a standalone extension, and to work within forms defined by the Page Forms extension.

TinyMCE will never work as well as the standard VisualEditor extension - among other things, its handling of template calls is quite primitive compared to VisualEditor's. However, it does have several advantages:

  • It is easier to install, since it does not require any outside libraries or services, like the Parsoid service required for VisualEditor.
  • There are a wide variety of outside plugins that have been developed for the TinyMCE editor, like spellcheckers; these may provide helpful functionality that VisualEditor does not provide.
  • It works within Page Forms, unlike VisualEditor; though VE support for Page Forms may be coming by mid-2018.

Download[edit]

You can download the TinyMCE code, in .zip format, here.

You can also download the code directly via Git from the MediaWiki source code repository (see available tags). From a command line, you can call the following:

git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/TinyMCE

To view the code online, including version history for each file, go here.

Installation[edit]

If you are using MediaWiki 1.27 or higher, add the following line to your LocalSettings.php file:

wfLoadExtension( 'TinyMCE' );

For earlier versions, you should call the following instead:

require_once( "$IP/extensions/TinyMCE/TinyMCE.php" );

To get TinyMCE working within textarea inputs in forms defined by Page Forms, you must use Page Forms version 4.3 or higher. Then, add "|editor=tinymce" to the field tag for any textarea input that you want to have editable with TinyMCE.

Preserving HTML tags in wiki code[edit]

Some HTML tags are permitted in wikicode which have equivalent markup in mediawiki, for example <li> or <hr> tags. In order to preserve these when processed by the TinyMCE parser so they aren't converted to their mediawiki equivalents, a configuration variable, $wgTinyMCEPreservedTags can be added to LocalSettings.php. In fact, any arbitrary tag can be added to this variable and the markup between it will not be converted to HTML by the TinyMCE parser. The TinyMCE editor will display the content of the tags as it would be displayed by mediawiki but behind an non-editable box. In order to edit this code in the TinyMCE editor use the {;} menu option. An example of a fairly typical selection of tags is:

$wgTinyMCEPreservedTags = array ( 
		'ol',
		'ul',
		'li',
		'h1',
		'h2',
		'h3',
		'h4',
		'h5',
		'h6',
		'ta',
		'div'
	);

Macros[edit]

You can have TinyMCE display custom "macros": one or more options that insert a custom bit of wikitext 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.

To add a macro, you need to add a few lines to LocalSettings.php. Here is one example:

$wgTinyMCEMacros[] = array(
        'name' => 'Reference',
        'image' => 'http://www.pvhc.net/img19/ssvwsbotkkiyjmkteonc.png',
        'text' => '<ref>!INSERT TEXT HERE!</ref>'
);

Let's go through these values:

  • 'name' is the text that appears for that macro in the dropdown menu.
  • 'image' is the icon image that appears alongside the text; it is optional. It can be either a full URL (like above), or just an image name; if it is an image name, the code will look in the wiki for an uploaded file with that name.
  • 'text' is the actual text that gets inserted into the page. It has a mini-syntax, involving "!" - if two exclamation marks are found within the text, then the parts outside the exclamation marks will get wrapped around whatever text is highlighted on the page. If no text is highlighted, then the whole 'text' value will get inserted, without the exclamation marks. For example, if the macro above is used, and it is pressed while the text "The Wind in the Willows by Kenneth Graham, pg. 98" is highlighted, then the resulting text on the page will be "<ref>The Wind in the Willows by Kenneth Graham, pg. 98</ref>". If, on the other hand, no text is highlighted, then the resulting text on the page will be "<ref>INSERT TEXT HERE</ref>".

Using with WikiEditor[edit]

You can use the TinyMCE extension in conjunction with the WikiEditor extension - by having WikiEditor displayed on pages where TinyMCE is disabled, if both extensions are installed. 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.

Disabling on selected pages[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 form, if the form is configured to do that.

$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
);

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. The TinyMCE context menu also contains an option to disable the TinyMCE context menu for the current session. If this is invoked the browser context menu reverts to its normal operation.

Usage[edit]

A TinyMCE toolbar, and some sample output

The TinyMCE extension adds another tab to any TinyMCE-editable page, which points to "action=tinymceedit". 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 unselecting the checkbox labeled "Use the TinyMCE editor to edit pages".

There are 5 buttons on the TinyMCE editor toolbar designed for use with MediaWiki:

  • 🔗 - inserts and/or edits a link, including both "external" and "internal" (wiki page) links.
  • ¶ - inserts a non-rendered newline into the wikicode.
  • Picture icon BLACK - allows uploading an image to the wiki, at the same inserting the image on the page. (With the right permissions, it is also possible to drag and drop pictures and text from web pages into the editor window, with the pictures also being uploaded to the wiki.)
  • {;} - allows inserting and/or editing parser tags, templates etc.
  • <> - allows viewing and editing the source wikicode.

Templates, parser functions, links etc. are displayed as they would be rendered by MediaWiki, but behind a non-editable box. Switches in the wikicode are displayed as the section character § behind a non-editable box as these are non-displayed commands to MediaWiki. In order to edit the wikicode for these, you can either double-click on the box or select the box and use the {;} button on the menu bar (which will be highlighted).

Non rendered new lines are displayed as the paragraph character ¶ and are inserted using the menu button with the same icon. These are otherwise treated as any other character.

Images can be uploaded and inserted into the page using the Picture icon BLACK button. To edit the placement, size and format of the image you can either double-click on the box or select the box and use the Picture icon BLACK button on the menu bar (which will be highlighted).