# 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.

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".

Specific callback functions that you don't need or doesn't do anything can be removed.

### Plugin directory structure

File/Directory | Description
--- | ---
css | Plugin specific CSS files
docs | Plugin specific documentation
images | Plugin specific images
jscripts | Plugin specific jscripts for HTML dialogs
langs | Plugin specific language files
editor_plugin.js | Editor plugin file (compressed).
editor_plugin_src.js | Editor plugin file (source).
somedialog.htm | Plugin specific dialog HTML file.

### Plugin example source

The example below shows a simple empty plugin and all possible callbacks.

    var TinyMCE_SomeNamePlugin = {
        /**
         * Returns information about the plugin as a name/value array.
         * The current keys are longname, author, authorurl, infourl and version.
         *
         * @returns Name/value array containing information about the plugin.
         * @type Array
         */
        getInfo : function() {
            return {
                longname : 'Your plugin',
                author : 'Your name',
                authorurl : 'http://www.yoursite.com',
                infourl : 'http://www.yoursite.com/docs/template.html',
                version : "1.0"
            };
        },

        /**
         * Gets executed when a TinyMCE editor instance is initialized.
         *
         * @param {TinyMCE_Control} Initialized TinyMCE editor control instance.
         */
        initInstance : function(inst) {
            // You can take out plugin specific parameters
            alert("Initialization parameter:" + tinyMCE.getParam("somename_someparam", false));

            // Register custom keyboard shortcut
            inst.addShortcut('ctrl', 't', 'lang_somename_desc', 'mceSomeCommand');
        },

        /**
         * Returns the HTML code for a specific control or empty string if this plugin doesn't have that control.
         * A control can be a button, select list or any other HTML item to present in the TinyMCE user interface.
         * The variable {$editor_id} will be replaced with the current editor instance id and {$pluginurl} will be replaced
         * with the URL of the plugin. Language variables such as {$lang_somekey} will also be replaced with contents from
         * the language packs.
         *
         * @param {string} cn Editor control/button name to get HTML for.
         * @return HTML code for a specific control or empty string.
         * @type string
         */
        getControlHTML : function(cn) {
            switch (cn) {
                case "SomeControl":
                    return tinyMCE.getButtonHTML(cn, 'lang_someplugin_button_desc', '{$pluginurl}/images/someimage.gif', 'mceSomeCommand');
            }

            return "";
        },

        getControlHTML : function(cn) {
            switch (cn) {
                case "advhr":
                    return tinyMCE.getButtonHTML(cn, 'lang_insert_advhr_desc', '{$pluginurl}/images/advhr.gif', 'mceAdvancedHr');
            }

            return "";
        },

        /**
         * Executes a specific command, this function handles plugin commands.
         *
         * @param {string} editor_id TinyMCE editor instance id that issued the command.
         * @param {HTMLElement} element Body or root element for the editor instance.
         * @param {string} command Command name to be executed.
         * @param {string} user_interface True/false if a user interface should be presented.
         * @param {mixed} value Custom value argument, can be anything.
         * @return true/false if the command was executed by this plugin or not.
         * @type
         */
        execCommand : function(editor_id, element, command, user_interface, value) {
            // Handle commands
            switch (command) {
                // Remember to have the "mce" prefix for commands so they don't intersect with built in ones in the browser.
                case "mceSomeCommand":
                    // Do your custom command logic here.

                    return true;
            }

            // Pass to next handler in chain
            return false;
        },

        /**
         * Gets called ones the cursor/selection in a TinyMCE instance changes. This is useful to enable/disable
         * button controls depending on where the user are and what they have selected. This method gets executed
         * alot and should be as performance tuned as possible.
         *
         * @param {string} editor_id TinyMCE editor instance id that was changed.
         * @param {HTMLNode} node Current node location, where the cursor is in the DOM tree.
         * @param {int} undo_index The current undo index, if this is -1 custom undo/redo is disabled.
         * @param {int} undo_levels The current undo levels, if this is -1 custom undo/redo is disabled.
         * @param {boolean} visual_aid Is visual aids enabled/disabled ex: dotted lines on tables.
         * @param {boolean} any_selection Is there any selection at all or is there only a cursor.
         */
        handleNodeChange : function(editor_id, node, undo_index, undo_levels, visual_aid, any_selection) {
        },

        /**
         * Gets called when a TinyMCE editor instance gets filled with content on startup.
         *
         * @param {string} editor_id TinyMCE editor instance id that was filled with content.
         * @param {HTMLElement} body HTML body element of editor instance.
         * @param {HTMLDocument} doc HTML document instance.
         */
        setupContent : function(editor_id, body, doc) {
        },

        /**
         * Gets called when the contents of a TinyMCE area is modified, in other words when a undo level is
         * added.
         *
         * @param {TinyMCE_Control} inst TinyMCE editor area control instance that got modified.
         */
        onChange : function(inst) {
        },

        /**
         * Gets called when TinyMCE handles events such as keydown, mousedown etc. TinyMCE
         * doesn't listen on all types of events so custom event handling may be required for
         * some purposes.
         *
         * @param {Event} e HTML editor event reference.
         * @return true - pass to next handler in chain, false - stop chain execution
         * @type boolean
         */
        handleEvent : function(e) {
            return true;
        },

        /**
         * Gets called when HTML contents is inserted or retrived from a TinyMCE editor instance.
         * The type parameter contains what type of event that was performed and what format the content is in.
         * Possible valuses for type is get_from_editor, insert_to_editor, get_from_editor_dom, insert_to_editor_dom.
         *
         * @param {string} type Cleanup event type.
         * @param {mixed} content Editor contents that gets inserted/extracted can be a string or DOM element.
         * @param {TinyMCE_Control} inst TinyMCE editor instance control that performes the cleanup.
         * @return New content or the input content depending on action.
         * @type string
         */
        cleanup : function(type, content, inst) {
            return content;
        },

        // Private plugin internal methods

        /**
         * This is just a internal plugin method, prefix all internal methods with a _ character.
         * The prefix is needed so they doesn't collide with future TinyMCE callback functions.
         *
         * @param {string} a Some arg1.
         * @param {string} b Some arg2.
         * @return Some return.
         * @type string
         */
        _someInternalFunction : function(a, b) {
            return 1;
        }
    };

    // Adds the plugin class to the list of available TinyMCE plugins
    tinyMCE.addPlugin("someplugin", TinyMCE_SomePluginPlugin);