Customization - Creating a plugin

Creating your own plugins

Creating you own plugins for the TinyMCE application is fairly easy if you know the basics of HTML, CSS and Javascript. The most easy way is to copy the "_template" directory or one of the other core plugins and work from there. The "_template" directory is a tutorial plugin that shows how to create a plugin. After you copy the template you need to change the red sections marked below to the name of your plugin this is needed so that plugins don't overlap in other words it gives the plugin a unique name. Then just alter the source code as you see fit remember that your custom plugins needs to be located in tiny_mce's "plugins" directory. If you want you may add plugin specific options/settings but remember to namespace them in the following format "<your plugin>_<option>" for example "yourplugin_someoption".

The example below has three functions, these are explained in greater detail below.

function TinyMCE_yourplugin_getInfo() {
	// Should return info about the plugin to be presented in about dialog
	return {
		longname : 'Some plugin name',
		author : 'Your name',
		authorurl : 'http://www.yoursite.com',
		infourl : 'http://www.yoursite.com/docs/..',
		version : '1.0'
	};
};

function TinyMCE_yourplugin_initInstance(inst) {
	// Gets executed when a editor instance is initialized
}

function TinyMCE_yourplugin_getControlHTML(control_name) {
	// Gets executed when a button is to be generated
}

function TinyMCE_yourplugin_handleNodeChange(editor_id, node, undo_index, undo_levels, visual_aid, any_selection) {
   // Gets executed when the selection changes
}

function TinyMCE_yourplugin_execCommand(editor_id, element, command, user_interface, value) {
   // Add your own custom commands here

   return false;
}

function TinyMCE_yourplugin_cleanup(type, content) {
	// Add your own custom cleanup here

	return content;
}

Creating popup HTML files

When creating a popup you need to include the "tiny_mce_popup.js" this enables you to retrive the tinyMCE global instance in all popup windows. All variables and language definitions gets replaced in the page when it loads. So language variables such as {$lang_something} can be places in the HTML code, if you need to get a language string in JavaScript simply use the tinyMCE.getLang function.

Example of simple popup file:

<html>
<head>
<title>{$lang_plugin_sample_title}</title>
<script language="javascript" src="../../tiny_mce_popup.js"></script>
<script language="javascript">
     // getWindowArg returns any arguments passed to the window
     alert(tinyMCE.getWindowArg('some_arg'));
</script>
<body>
     <strong>{$lang_plugin_sample_desc}</strong>
</body>

The TinyMCE_<plugin>_initInstance function (Optional)

This function is called when a editor instance gets initialized.

Parameters
inst	Reference to editor instance that was initialized.

The TinyMCE_<plugin>_handleNodeChange function (Optional)

This function is called when the cursor/selection of a editor instance changes. Then the currenly selected/focused node is passed to this function. This can be useful when you want to change the UI depending on what the user has selected.

Parameters
editor_id	Unique editor id, this is the same as the $editor_id variable in getEditorTemplate.
node	Reference to the Node element where the cursor is currenly located.
undo_index	Current undo index, this value is -1 if the custom undo/redo support is disabled.
undo_levels	Current number of undo levels, this value is -1 if the custom undo/redo support is disabled.
visual_aid	True/false state of visual aid/guidelines mode.
any_selection	Is any text or image selected.

The TinyMCE_<plugin>_execCommand function (Optional)

This function is called when a command is executed for example "bold" or "createlink" this callback/plugin function may then intercept plugin specific commands and do custom logic. If this command returns true the command handling is terminated and the default tinyMCE command handeling never gets executed.

Parameters
editor_id	Unique editor id, this is the same as the $editor_id variable in getEditorTemplate.
element	Reference to the document DOM root element of the editor instance.
command	Command that is to be executed for example "myCommand".
user_interface	true/false option if a user insterace is to be used or not.
value	Custom data value passed with command, may be any data type.

Returns:
true - Command intercepted and handled do not continue with command handling.
false - Continue with execCommand handling, bubble.

The TinyMCE_<plugin>_getControlHTML(control_name) function (Optional)

This function is called when a editor needs to render a specific control/button. This function should return the HTML template of that control or a empty string if the control_name wasn't recognized. Notice the variable {$pluginurl} gets replaced with the URL prefix for the current plugin directory.

Parameters
control_name	Control name to match against.

Returns: return the HTML template of that control or a empty string if the control_name wasn't recognized.

The TinyMCE_<plugin>_cleanup(type, content) function (Optional)

This function is called when a editor does cleanup of contents. This function has the same format as the one defined in the cleanup_callback option.

Parameters
type	Type of cleanup, insert_to_editor or get_from_editor. Insert to editor is passed when new content is placed within the editor and get_from_editor is when content is passed out from the editor. When dealing with the DOM representation of the same content insert_to_editor_dom or get_from_editor_dom gets passed as a type.
content	HTML contents to be cleaned up, this string contains the HTML code or with the _dom types the body DOM object gets passed instead.

Returns: return the cleaned up HTML code.