Extension:TinyMCE/Configuration

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:

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

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" =&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 WSForm 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

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

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

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.