Plugin Name: Advanced TinyMCE Editor
Plugin URI: http://www.mkbergman.com/advancedTinyMCE
Description: Adds advanced features to the standard TinyMCE WordPress rich-text editor. Originally developed by Assaf Arkin, now updated many times.  Not tested for prior to WP v 2.2 or IE
Version: 0.4
Date: 6/12/2007
Author: Michael K. Bergman
Author URI: http://www.mkbergman.com/
License: Creative Commons Attribution-ShareAlike
Tags: wordpress tinymce

Download and Installation
-------------------------

Download the zipped Advanced TinyMCE Editor.

Installation instructions are:

   1. Back-up the files in the two specific sub-directories used by the Advanced TinyMCE Editor as noted below
   2. Download the zip file; unzip into a temporary reference location
   3. First, copy over the plug-in file -- advanced-tinyMCE.php -- into your standard plug-in directory:

		/wordpress home or root - that is, your WP starting point/

			/wp-content/

				/plug-ins/

					advanced-tinyMCE.php [copied here]

   4. Second, update the TinyMCE js plug-ins directory by copying the multiple files in the subdirectory created for the extracted download.  The target location for these files on your local system may be found at:

		/wordpress home or root - that is, your WP starting point/

			/wp-includes/

				/js/

					/tinymce/

						/plug-ins/

							[subdirectories for plug-in additions -- copy here]

Please note that your target subdirectory will itself already include a number of additional TinyMCE plug-ins that came as part of the standard WP installation; do not erase these!  They supplement the new functionality you just added.

   5. Under plug-ins in your WP administration center, activate the Advanced TinyMCE Editor option (if this plug-in does not display, you did not correctly finish Step #3 above)
   6. Go to the Visual editor under the Write or Manage menu options within your WP administation console, and begin editing and then Enjoy!

Unlike normal plug-ins, the addition of Step #4 arises from the tighter integration with TinyMCE in WordPress.

Known Issues
------------

These are the known issues with WordPress v. 2.2 and this plug-in.

   Possible WordPress v. 2.2 Issues
   --------------------------------

As an earlier post by me summarized (with other external references), there are issues of compatibility with many current plug-ins and WordPress v. 2.2.   You may encounter problems with the Advanced TinyMCE Editor for these reasons, which may have nothing to do with the plug-in itself and may be devilishly difficult to diagnose and remedy.

I expect releases after WP v. 2.2 to get increasingly stable.

   Standard Advanced Toggle
   ------------------------

Apart from this plug-in, which corrects this hidden requirement, the standard WordPress distribution requires a toggle of Alt-V (IE) or Shift-Alt-V (Firefox) to toggle the standard editor's advanced buttons on and off.

   A Firefox Gotcha
   ----------------

One problem common to the Firefox browser is the need to clear the cache before you see the plug-in buttons display properly.  To do so, go to the main menu Tools > Clear Private Data and then clear the data.

   Color Picker
   ------------

The 'More Colors' option on the Advanced TinyMCE brings up a blank popup.  (See http://trac.wordpress.org/ticket/4288.)

In part to overcome this issue, I added an additional color picker from this source:  http://tinymce.moxiecode.com/punbb/viewtopic.php?pid=16270.  See B15 below.

Functional Description
----------------------

The result of the complete installation is shown in this figure. Each of the buttons is described below. Note if you modify your actual file (see below) that the number of your buttons and their order may change.

This image shows three rows (A, B, C) of 60 buttons and dropdown lists, each of which is described below by row and number from left-to-right.  New functionality added by virtue of this Advanced TinyMCE plug-in above the standard advanced options in WordPress is shown with an asterisk (*).

From top-to-bottom and left-to-right, these buttons are:

    A1 -- 'Undo" levels, typically set to 10 steps
    A2 -- 'Redo' levels, typically set to 10 steps
    A3 -- standard 'Print' for the post/page in the editor *
    A4 -- standard 'Cut'; may be limitations in some browser configurations *
    A5 -- standard 'Copy'; may be limitations in some browser configurations *
    A6 -- standard 'Paste'; may be limitations in some browser configurations
    A7 -- 'Paste Text' for pasting without formatting; may be limitations in some browser configurations *
    A8 -- 'Paste Word' for pasting Word with some formatting retained; may be limitations in some browser limitations *
    A9 -- 'Select All' in the editor window *
    A10 -- 'Format' dropdown according to standard CSS styles
    A11 -- 'Font Family' dropdown to select font typeface *
    A12 -- 'Font Size' dropdown to select font size *
    A13 -- 'Styles' dropdown to pick existing styles *
    A14 -- 'CSS Style' brings up a comprehensive popup dialog for editing or entering new styles, enabling styles to be edited visually *
    A15 --  the 'HTML' button brings up a direct HTML editing window, with all code shown.  Unlike the Code tab, all HTML codes are shown (but with conversion errors corrected; see discussion above) *
    B1 --  'Bold'; standard function
    B2 -- 'Italics'; standard function
    B3 -- 'Underline'; standard function
    B4 -- 'Strikeout'; standard function
    B5 -- 'Bullet List' is a standard function per existing CSS formatting
    B6 -- 'Number List' is a standard function
    B7 -- 'Justify Left', applied to highlighted text
    B8 -- 'Justify Center', applied to highlighted text
    B9 -- 'Justify Right', applied to highlighted text
    B10 -- 'Justify Full', stretch text to margins for highlighted text
    B11 -- 'Indent' highlighted text, sometimes treated as <blockquote>
    B12 -- 'Outdent' to return indented text to standard left margin
    B13 -- 'Text Color' enables highlighted text to have color changed *
    B14 -- 'Background Color' enables background for highlighted area to have color changed *
    B15 -- 'Text/Background Color Selector' is a more general option for choosing any RGB value for text or background *
    B16 -- 'Subscript' enables that for the highlighted text *
    B17 -- 'Superscript' enables that for the highlighted text *
    B18 -- the 'Character Map' brings up a popup dialog to insert special characters and symbols *
    B19 --  the 'Emotions' button brings up a popup for a choice of emoticons *
    B20 -- 'Insert Date' provides a date insert at the point of the cursor; format is settable *
    B21 -- 'Insert Time' provides a time insert at the point of the cursor; format is settable *
    B22 -- the 'Horizontal Rule' inserts a standard rule at the point of the cursor *
    B23 -- the 'Advanced Horizontal Rule' allows the rule to have its formatting set via a popup menu *
    B24 -- 'Image' brings up an advance image dialog, including image swaps *
    B25 -- 'Media' enables Flash, Shockwave, etc., to be inserted at cursor position with settable parameters (not fully tested) *
    B26 -- 'Link' is a more advanced link insertion and settings popup *
    B27 -- 'Unlink' removes existing link settings *
    B28 -- 'Anchor' enables anchor tags to be set in the current document *
    C1 -- 'Table' insert or edit an existing table; major functionality, with specifics covered in the next few buttons *
    C2 -- 'Table Row' for modifying entire table rows at a time *
    C3 -- 'Table Cell' for setting specific table cell properties *
    C4 -- 'Insert Row Before' *
    C5 -- 'Insert Row After' *
    C6 -- 'Delete Row' *
    C7 -- 'Insert Column Before' *
    C8 -- 'Insert Column After' *
    C9 -- 'Delete Column' *
    C10 -- 'Split Merged Table Cells', as described *
    C11 -- 'Merge Table Cells' for the highlighted selection *
    C12 -- 'Citation' provides a means to put <cite> tags on highlighted text *
    C13 -- 'Abbreviation' provides a means to put <abbr> tags on highlighted text *
    C14 --'Insert' provides a means to put <ins> tags on highlighted text *
    C15 -- 'Delete' proovides a means to put <del> tags on highlighted text *
    C16 -- 'Attributes' provides a means to put <attr> tags on highlighted text *
    C17 --  'Direction LtR' sets scrolling and editing from left-or-right *
    C18 -- 'Direction RtL' sets scrolling and editing from right-to-left *
    C19 -- 'Spellchecker' toggles spell checking off or on; may work off of IE spell lists; also see documentation about spelling lists *
    C20 -- 'Visual Characters' provides screen display of hidden characters like spaces (via &nbsp; and tab, etc) *
    C21 -- 'Remove Formatting' actually has fairly minimal impact by removing cell and related spacing and formatting.  Apparently has minimal effect on embedded codes; it's use needs better documentation *
    C22 -- 'Cleanup' is also not apparent, likely requires poor code base; not yet fully tested *
    C23 -- 'Find' brings up a popup to search for the given string *
    C24 -- 'Replace' allows replacement of the found search string *
    C25 -- 'Fullscreen' expands the current editor space to occupy to full screen *
    C26 -- the 'More' tag is a specific WordPress option for splitting posts into a summary and detailed entry, split at the point of insertion
    C27 -- 'Help' brings up a minimal (unfortunately) WP-specific help on the editor; not very useful.

Please note that the behavior and functionality of the image (B24) and link (B26) are also improved over the standard WordPress distribution.

If you would like more information on the various button names, see the initial TinyMCE documentaton at:  http://wiki.moxiecode.com/index.php/TinyMCE:Control_reference.

Instructions for Your Own Modifications
---------------------------------------

The actual Advanced TinyMCE Editor plug-in is quite simple, even though installation is a little more complicated than for a standard WordPress plug-in.  This complication is because of the added step of adding the new plug-in subdirectories to TinyMCE's own JavaScript listings (see Step #4 under 'Download and Installation' above).

But, with a little bit of familiarity, the simplicity of all of this becomes quite clear, which should enable you to make your own modifications and extensions.

There are two simple parts to the plug-in.  The first part is to place changed or added functionality into the plug-in subdirectories to TinyMCE's own JavaScript listings (see Step #4 under 'Download and Installation' above).  (Note simple re-ordering or removal of buttons does not require this part.)  The second part is that the WordPress plug-in file -- advanced-tinyMCE.php -- (see Step #3 under 'Download and Installation' above) may also require some modifications.  These are straightforward and described below for a couple of scenarios.

With the instructions below, you should be ablto to remove, add, change the order of buttons, change editor behavior when in 'code' mode and update the system on your own when new releases of TinyMCE or WordPress are issued.

   Removing Buttons, Changing Menu Orders
   --------------------------------------

To remove editor buttons or change their display order you will need to edit the advanced-tinyMCE.php file (the one placed into your standard /plug-ins/ directory).  The basic layout of this portion of the file is shown below:

function extended_editor_mce_buttons($buttons) {
    return array(
        "undo", "redo", "separator", "print", "separator", "cut", "copy", "paste", "pastetext", "pasteword",
          "selectall", "separator", "formatselect", "fontselect", "fontsizeselect", "styleselect", "styleprops",
          "separator", "code");
}

function extended_editor_mce_buttons_2($buttons) {
   // the second toolbar line
    return array(
        "bold", "italic", "underline", "strikethrough", "separator", "bullist", "numlist", "separator",
        "justifyleft", "justifycenter", "justifyright", "justifyfull", "separator",
          "indent", "outdent", "separator", "forecolor", "backcolor", "advcolor", "separator",
        "sub", "sup", "charmap", "emotions",
          "separator", "insertdate", "inserttime", "separator", "hr", "advhr", "separator",
          "image", "media", "separator", "link", "unlink", "anchor");
}

function extended_editor_mce_buttons_3($buttons) {
   // These are the buttons for third toolbar line
return array(
        "tablecontrols", "separator", "cite", "abbr", "acronymn", "ins", "del", "attribs", "separator",
          "ltr", "rtl", "separator", "iespell", "spellchecker", "separator", "visualchars", "removeformat",
          "cleanup", "separator", "search", "replace", "separator", "fullscreen", "separator", "wp_more", "wp_help");
}

This layout corresponds to the rows (A, B, C) and order.   The naming correspondence between a button label and its actual button should be evident in comparison with the functional listings above.  (Note, a couple of the named array items are "extra" in that they do not result in a corresponding button display; these should be evident.)

To remove a button, simply erase its name, quotes and comma; to move it, make sure the quotes and commas remain in order and intact.

When you make such changes, always be careful about your use and location of quotes, syntax characters and spelling!  Note each array listing must start and end with the parentheses.

   Adding Functionality
   --------------------

If you discover new functionality that you want to add to the editor, three steps are necessary.

   1. First, you must copy the functionality file or subdirectory to the TinyMCE JS /plug-ins/ subdirectory (not your standard WP one!) (see Step #4 under 'Download and Installation' above).

   2. Second, add the new function to the extended function array in the same advanced-tinyMCE.php file:

function extended_editor_mce_plug-ins($plug-ins) {
   array_push($plug-ins,
         "advcolor", "advhr", "advimage", "advlink", "cleanup", "contextmenu", "directionality", "emotions",
          "fullscreen", "iespell", "insertdatetime", "media", "print", "searchreplace", "style", "table",
          "visualchars", "wphelp", "xhtmlxtras");
   return $plug-ins;
}

The name corresponds directly with the file name entered under the plug-ins subdirectory.  The order of entry does not matter.

   3. And, then, third, add the associated button name (it should be described in the add-in functionality) to one of the three arrays noted above for 'Removing Buttons, Changing Menu Orders'.

That's it!

You should note that Moxiecode maintains a wiki with listings of additional plug-ins, and also keeps a series of look-up pages (check out all of the dropdown list pages!) for TinyMCE's own included advanced functionality.  There are also other add-ins that you might find at SourceForge or with a Google search.

   Changing Code Processing
   ------------------------

Since at least the WordPress 2.1 release, the TinyMCE editor has had the nasty habit of removing <div> tags when toggling between 'Visual' and 'Code' views.

This comes from the WP team's (arbitrary) decision about this matter (and many others, see below).  The code causing this nasty change is in the initial configuration file for TinyMCE, generally found under this path:

/path-to-wordpress/wp-includes/js/tinymce/tiny_mce_config.php

In that file you'll see this code:

$valid_elements =
p/-div[*],-strong/-b[*],-em/-i[*],-font[*],-ul[*],-ol[*],-li[*],*[*];

What this code basically says is to replace all <div> tags with <p> tags, <b> and <i> with <strong> and <em> respectively, keep all font and bullet tags, and then, as a capper, keep all remaining all other tags not specifically listed (*[*]).

Actually, this is all pretty good practice to use valid XHTML, except for the curious <div> replacement.

TinyMCE offers nice control of such parsing matters, but it definitely is not a good idea to make changes directly to the WordPress supplied configuration files.  Rather, I isolated such changes to the Advanced TinyMCE plug-in code itself.  Thus, this code is now added to the plug-in advanced-tinyMCE.php file:

function extended_editor_mce_valid_elements($valid_elements) {
   $valid_elements = '-strong/-b[*],-em/-i[*],-font[*],-ul[*],-ol[*],-li[*],*[*]';
   $valid_elements = apply_filters('extended_editor_mce_valid_elements', $valid_elements);
   return $valid_elements;
}

Note that the only change I made was to remove the unwanted <div> with <p> replacement.

Note, you could make your own changes within these same lines of code.  For example, Moxiecode provides a set of instructions to make your code inspection be completely XHTML compliant.  That documentation and related material on the TinyMCE wiki site are probably worth inspecting if you are going to get aggressive about making your own code changes (but, proceed with caution!).

Of course, these are fairly fundamental changes in that they act to re-write underlying page code.  Use at your own risk and you are on your own! :)

BTW, I'd like to thank Tim Rohrer for pointing me in the right direction for this fix.

What to Do in the Case of Future Upgrades?
------------------------------------------

To keep current with new releases in either WP or TinyMCE, you can follow the same steps as what was outlined for 'Adding Functionality' above.  Simply inspect the current TinyMCE functions, those supplied with the new version (as they come out) of WP, and make your desired updates and corrections.

General WP Comments
-------------------

I think that the WP team has, overall, exercised way too much paternalism in how they have handled adding rich-text editing from the outset.  When I first discussed using the external Xinha editor, I was pointing out a severe lack in the basic WordPress distribution.

When I posted my first TinyMCE extension, that was an attempt to overcome WP team decisions as to what should and should not be in a rich-text, WYSIWYG editor.  While I applaud the choice of TinyMCE, why was all of this "father knows best" stuff going on?

The fact is, WP users should be able to choose any external editor they like.  The WP team should only be providing API hooks, and little else, to allow the market to decide what it wants or not.

It is completely cool to include TinyMCE in the baseline WP distribution (again, so long as it is merely an exemplar for standard hooks).  But, why embed it in a difficult way, why change the basic TinyMCE operations and parsing, and why change what is included in an advanced functional option??

Moreover, why make it so obscure that you have to use Alt-V or Shift-Alt-V or some other Easter Egg combination even to get the advanced options to display?

I don't think there are any compelling answers to all of these whys.  And, whomever was making the decisions, was certainly not doing it for me or with any consultation.

I posted earlier about my disappointing experience in upgrading to WP 2.2.  I strongly urge the core WP development team to get off of its high horse on this issue of a rich-text visual editor, and just give all of us simple hooks.  We can figure it out from there.

Another Option
--------------

When completing this write-up, I also came across this similar plug-in called TinyMCE Advanced.  If you have problems with what I've provided, you may want to check this version out.  BTW, it seems to have cleaner styles linkages.  Also, BTW, I have not tested or installed it.