TinyMCEPlugin

The integration uses the Foswiki:Extensions.WysiwygPlugin to translate text to and from a format that TinyMCE can edit.

This plugin is able to swap out standard text areas and replace them with WYSIWYG editors. This means you get WYSIWYG editors for textareas in forms, as well as for the main text of the topic. It can also co-exist alongside other WYSIWYG editors.

The editor automatically "switches itself off" (i.e. reverts to the old text-only window) when editing topics that contain Foswiki content it can't handle, such as complex macros.

Editor Notes

Installation Instructions

NOTES:

• This plugin comes pre-installed on Foswiki. You should only need to re-install if there is an upgrade to the plugin.
• It requires the very latest revision of Wysiwyg Plugin
• When installed, it replaces the old "textarea" editor. You may still access the plaintext editor with the "Wiki Text" button provided in the toolbar, however this does not necessarily give you the original raw/wiki text version of the topic content. To bypass the TML to HTML conversion process entirely, use the Edit wiki text link provided by the default Foswiki skin at the bottom of the page.

First follow the installation instructions to install the Plugin:

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

• Enable the Wysiwyg Plugin in configure.
• Enable the Tiny MCEPlugin in configure.
• Click on edit of any topic.

Preferences

TINYMCEPLUGIN_INIT_TOPIC

For a full explanation and guidance on configuration of available TinyMCE options, see the Moxicode TinyMCE Wiki.

Below is the default configuration. If it is to be modified, it should be copied (including %START/ENDSECTION{}% macros) to a different topic to avoid customisations being overwritten when Tiny MCEPlugin is upgraded.

TINYMCEPLUGIN_INIT

%STARTSECTION{"TINYMCEPLUGIN_INIT"}%
"mode" : "textareas",
"editor_selector" : "foswikiWysiwygEdit",
"save_on_tinymce_forms" : true,
"cleanup" : true,
"theme" : "advanced",
"convert_urls" : true,
"relative_urls" : false,
"remove_script_host" : false,
"dialog_type" : "modal",
"extended_valid_elements" : "li[type]",
"setupcontent_callback" : "FoswikiTiny.setUpContent",
"urlconverter_callback" : "FoswikiTiny.convertLink",
"foswikipuburl_callback" : "FoswikiTiny.convertPubURL",
"save_callback" : "FoswikiTiny.saveCallback",%IF{
    "$TINYMCEPLUGIN_DEBUG"
    then="
\"debug\" : true,"
}%
"plugins" : "%IF{
    "defined 'TINYMCEPLUGIN_MCEPLUGINS'"
    then="%TINYMCEPLUGIN_MCEPLUGINS%"
    else="%STARTSECTION{"MCEPLUGINS"}%contextmenu, table, searchreplace, autosave, paste, legacyoutput, inlinepopups, fullscreen, foswiki, foswikibuttons, foswikiimage%ENDSECTION{"MCEPLUGINS"}%"
}%%IF{
    "defined 'TINYMCEPLUGIN_ADDITIONAL_MCEPLUGINS'"
    then=", %TINYMCEPLUGIN_ADDITIONAL_MCEPLUGINS%"
}%",
"foswiki_secret_id" : "%WYSIWYG_SECRET_ID%",
"foswiki_vars" : {
    "PUBURLPATH" : "%PUBURLPATH%",
    "PUBURL" : "%PUBURL%",
    "WEB" : "%BASEWEB%",
    "TOPIC" : "%BASETOPIC%",
    "ATTACHURL" : "%PUBURL%/%BASEWEB%/%BASETOPIC%",
    "ATTACHURLPATH" : "%PUBURLPATH%/%BASEWEB%/%BASETOPIC%",
    "VIEWSCRIPTURL" : "%SCRIPTURL{view}%",
    "SCRIPTSUFFIX" : "%SCRIPTSUFFIX%",
    "SCRIPTURL" : "%SCRIPTURL%",
    "SYSTEMWEB" : "%SYSTEMWEB%"
},
"theme_advanced_toolbar_align" : "left",
"foswikibuttons_formats" : {
    /* Use 'attributes : { class : "foo" }' instead of 'classes: "foo"'
     * because this is how it's done in the default advanced theme shipped
     * with TinyMCE which seems to be a few ms faster on cursor movement
     */
    "Normal" : { "remove" : "all" },
    "Heading 1" : { "block" : "h1",  "remove" : "all" },
    "Heading 2" : { "block" : "h2",  "remove" : "all" },
    "Heading 3" : { "block" : "h3",  "remove" : "all" },
    "Heading 4" : { "block" : "h4",  "remove" : "all" },
    "Heading 5" : { "block" : "h5",  "remove" : "all" },
    "Heading 6" : { "block" : "h6",  "remove" : "all" },
    "VERBATIM"  : { "block" : "pre", "remove" : "all", "attributes" : { "class" : "TMLverbatim" } }, 
    "LITERAL"   : { "block" : "div", "remove" : "all", "attributes" : { "class" : "WYSIWYG_LITERAL" } },
    "Protect on save" : { "block" : "div", "remove" : "all", "attributes" : { "class" : "WYSIWYG_PROTECTED" } },
    "Protect forever" : { "block" : "div", "remove" : "all", "attributes" : { "class" : "WYSIWYG_STICKY" } }
},
"foswikibuttons_cursoridletime" : 250,
"paste_create_paragraphs" : true,
"paste_create_linebreaks" : false,
"paste_convert_middot_lists" : true,
"paste_convert_headers_to_strong" : false,
"paste_remove_spans" : true,
"paste_remove_styles" : true,
"paste_strip_class_attributes" : "all",
"theme_advanced_buttons1" : "%IF{
    "defined 'TINYMCEPLUGIN_BUTTONS1'"
    then="%TINYMCEPLUGIN_BUTTONS1%"
    else="%STARTSECTION{"BUTTONS1"}%foswikiformat, separator, bold, italic, tt, colour, removeformat, separator, bullist, numlist, outdent, indent, blockquote, separator, link, unlink, anchor, separator, undo, redo, separator, search, replace%ENDSECTION{"BUTTONS1"}%"
}%%IF{
    "defined 'TINYMCEPLUGIN_ADDITIONAL_BUTTONS1'"
    then=", %TINYMCEPLUGIN_ADDITIONAL_BUTTONS1%"
}%",
"theme_advanced_buttons2" : "%IF{
    "defined 'TINYMCEPLUGIN_BUTTONS2'"
    then="%TINYMCEPLUGIN_BUTTONS2%"
    else="%STARTSECTION{"BUTTONS2"}%tablecontrols, separator, attach, image, charmap, hr, separator, restoredraft, fullscreen, code, hide%ENDSECTION{"BUTTONS2"}%"
}%%IF{
    "defined 'TINYMCEPLUGIN_ADDITIONAL_BUTTONS2'"
    then=", %TINYMCEPLUGIN_ADDITIONAL_BUTTONS2%"
}%",
"theme_advanced_buttons3" : "%IF{
    "defined 'TINYMCEPLUGIN_BUTTONS3'"
    then="%TINYMCEPLUGIN_BUTTONS3%"
}%%IF{
    "defined 'TINYMCEPLUGIN_ADDITIONAL_BUTTONS3'"
    then=", %TINYMCEPLUGIN_ADDITIONAL_BUTTONS3%"
}%",
"autosave_interval" : "%IF{
    "defined 'TINYMCEPLUGIN_AUTOSAVE_INTERVAL'"
    then="%TINYMCEPLUGIN_AUTOSAVE_INTERVAL%"
    else="%STARTSECTION{"AUTOSAVE_INTERVAL"}%180s%ENDSECTION{"AUTOSAVE_INTERVAL"}%"
}%",
"autosave_retention" : "%IF{
    "defined 'TINYMCEPLUGIN_AUTOSAVE_RETENTION'"
    then="%TINYMCEPLUGIN_AUTOSAVE_RETENTION%"
    else="%STARTSECTION{"AUTOSAVE_RETENTION"}%4320m%ENDSECTION{"AUTOSAVE_RETENTION"}%"
}%",
"theme_advanced_toolbar_location" : "top",
"theme_advanced_resize_horizontal" : false,
"theme_advanced_resizing" : true,
"theme_advanced_path" : false,
"theme_advanced_statusbar_location" : "bottom",
"keep_styles" : false,
"content_css" : "%PUBURLPATH%/%SYSTEMWEB%/TinyMCEPlugin/wysiwyg%IF{
    "$TINYMCEPLUGIN_DEBUG"
    then="_src"
}%.css,%PUBURLPATH%/%SYSTEMWEB%/SkinTemplates/base.css,%FOSWIKI_STYLE_URL%,%FOSWIKI_COLORS_URL%"
%ENDSECTION{"TINYMCEPLUGIN_INIT"}%

Example:

• Create Main.TinyMCEPlugin, copying the text above
• Update the TINYMCEPLUGIN_INIT_TOPIC variable to point to the newly created topic, Eg. in Site Preferences or MyWeb.WebPreferences:
  

     * Set TINYMCEPLUGIN_INIT_TOPIC = Main.TinyMCEPlugin

Settings

Browser Specific Settings

   * Set TINYMCEPLUGIN_INIT_MSIE = "paste_auto_cleanup_on_paste" : false 

    MSIE => '',
    OPERA => '',
    GECKO => '"gecko_spellcheck" : true',
    SAFARI => '',
    CHROME => ''

TinyMCE Plugins & Toolbar Buttons

Documentation for standard theme_advanced toolbar buttons (Eg. superscript/subscript, strikethrough, highlight colours etc) can be found at http://wiki.moxiecode.com/index.php/TinyMCE:Control_reference.

Default Plugins

Additional Plugins

For example, to make use of the emotions and wordcount plugins add the following to Main.Site Preferences:

---++ TinyMCE customisations
   * Set TINYMCEPLUGIN_ADDITIONAL_MCEPLUGINS = emotions, wordcount
   * Set TINYMCEPLUGIN_ADDITIONAL_BUTTONS2 = emotions

Some notable plugins:

Frequently Asked Questions

The topic Tiny MCEFrequently Asked Questions contains more help with things like: "How do I configure the buttons in my skin?", "How do I disable the WYSIWYG?" etc.

Wysiwyg Plugin Settings

WYSIWYG_EXCLUDE - Prevent WYSIWYG editing

This is not supported currently by the TinyMCE Editor. This setting is not used.

The global preference setting WYSIWYG_EXCLUDE can be set to make the plugin sensitive to what is in a topic, before allowing it to be edited. You can set it up to veto an edit if the topic contains:

• html - HTML tags (e.g. <div>, not including <br>), or
• macros - simple macros (e.g. %VAR%) or
• calls - macros with parameters e.g. %MACRO{...}%
• pre blocks (<pre>)
• HTML comments (<!-- ... -->)

WYSIWYG_EDITABLE_CALLS - Exceptions to WYSIWYG_EXCLUDE

You should set WYSIWYG_EXCLUDE and WYSIWYG_EDITABLE_CALLS in Site Preferences, or in Web Preferences for each web.

WYSIWYGPLUGIN_PROTECT_EXISTING_TAGS - Protect specific tags originally in the topic text

The default setting for this preference is defined within the plugin. It corresponds to div, span.

This feature may be disabled by setting the preference to a single comma. Thi does not guarantee that HTML markup will be removed; the conversion of HTML tags to TML markup remains subject to the other controls provided by the WysiwygPlugin, including the WYSIWYGPLUGIN_STICKYBITS preference, <sticky> blocks, <literal> blocks and the rules applied to tables and lists.

WYSIWYGPLUGIN_STICKYBITS - Protect tags based upon their arguments

This preference setting is used to tell the translator which attributes, when present on a tag, make it "stick" i.e. block conversion back to TML.

For example, setting it to table=background,lang;tr=valign will stop the translator from trying to convert any table tag that has background or lang attributes, and any tr tag that has a valign attribute back to Foswiki | table | column | markup (regardless of where that table tag comes from).

This setting is used only after the page has been processed by the editor. If the editor does not support a particular tag or attribute and the editor corrupts the tag, this setting will not be helpful. It is only used to prevent an HTML tag from being converted back to TML.

Format of the setting is tag1=attrib,attrib;tag2=attrib. Attributes delimited by comma, and tags delimited by semicolon.

• The left side of the equal sign is the tag.
• The right side of the equal sign is a comma delimited list of attributes to be matched.

The default setting for this preference are hard coded in the plugin. If you wish to change the settings, the following list is the default setting coded in the plugin:

   * Set WYSIWYGPLUGIN_STICKYBITS = 
        .*=id,lang,title,dir,on.*;
        A=accesskey,coords,shape,target;
        BDO=dir;
        BR=clear;
        COL=char,charoff,span,valign,width;
        COLGROUP=align,char,charoff,span,valign,width;
        DIR=compact;
        DIV=align,style;
        DL=compact;
        FONT=size,face;
        H[0-9]=align;
        HR=align,noshade,size,width;
        LEGEND=accesskey,align;
        LI=value;
        OL=compact,start,type;
        P=align;
        PARAM=name,type,value,valuetype;
        PRE=width;
        Q=cite;
        TABLE=align,bgcolor,frame,rules,summary,width;
        TBODY=align,char,charoff,valign;
        TD=abbr,align,axis,bgcolor,char,charoff,headers,height,nowrap,rowspan,scope,valign,width;
        TFOOT=align,char,charoff,valign;
        TH=abbr,align,axis,bgcolor,char,charoff,height,nowrap,rowspan,scope,valign,width,headers;
        THEAD=align,char,charoff,valign;
        TR=bgcolor,char,charoff,valign;
        UL=compact,type

If you edit using the plain-text editor, you can use the <sticky>..</sticky> tags to delimit HTML (or TML) that you do not want to be WYSIWYG edited.

Upgrading from Tiny MCEPlugin versions prior to 05 Mar 2010 release

If a customised TINYMCEPLUGIN_INIT string is in use, it should be re-built based on the content of this documentation. The customisations should be reviewed to determine if they are still necessary.

Known Issues of Tiny MCEPlugin

• Foswikitask:Item8475 - Foswiki introduces errant spaces into table cells
• Foswikitask:Item8582 - X11 environments: Tiny MCEPlugin editor copies current topic onto the "Primary Selection"
• Foswikitask:Item8712 - Outdenting list items in Firefox soemtimes does not work correctly
  • Description: The list symbol (number, bullet, etc) sometimes disappears from the item after being outdented. When this happens, it is also not possible to outdent the item another level.
  • Work-around: Position the cursor to the beginning of the line (where the symbol should appear) and press the enter key. The symbol should be restored and another outdent will be possible.
• Foswikitask:Item8981 - Copy & paste of list items into a list breaks up the list
  • Description: Consult the task linked above. After the operation described, the list is broken into three.
  • Work-around: Users may elect to persist with this behaviour, or alternatively, override TINYMCEPLUGIN_MCEPLUGINS to omit the paste plugin: however, this solution may introduce its own problems.
• Foswikitask:Item9198 - After inserting new table at top of document: unable to position cursor above
  • Work-around: Use 'Save and continue' or switch to Wiki Text? and back to WYSIWYG again to allow Wysiwyg Plugin to add an empty <p/> above the table

Known Issues of Wysiwyg Plugin (partial list)

• Foswikitask:Item2174 - Wysiwyg Plugin removes line breaks
  • Work-around: Use the * Set NOWYSIWYG = 1 setting to disable WYSIWYG on line-sensitive topics
• Foswikitask:Item1396 - Anchors are not handled by Wysiwyg Plugin
• Foswikitask:Item5955 - Wysiwyg Plugin fails to roundtrip tables with align="center", border attributes, etc.
  • Description: Sometimes tables will fail to be converted to TML syntax (will stay as HTML) because there are attributes on the table (such as alignment or border decorations) that Wysiwyg Plugin does not know how to preserve. If such attributes are necessary, please use Var TABLE instead.
  • Work-around:
    • Click inside the offending table
    • Click the table toolbar button (usually used to create a new table)
    • With the exception of Cols and Rows, delete/reset all content from the fields on the 'General' and 'Advanced' tabs.
    • Write a Var TABLE macro above the offending table that adds the desired attributes safely

Check regularly at Foswiki:Extensions.TinyMCEPlugin for updates.

Plugin Info

Another great Foswiki extension from the WikiRing - working together to improve your wiki experience!

Many thanks to the following sponsors for supporting this work:

• ILOG
• Carrier Corporation
• TWIKI.NET

Attachments of TinyMCEPlugin

I	Attachment	Action	Size	Date	Who	Comment	Attribute
png	screenshot.png	manage	0.1 K	01 Jan 1970 - 00:00	Unknown User		h
gif	tinymce.gif	manage	0.1 K	01 Jan 1970 - 00:00	Unknown User	screenshot	h
png	wikiringlogo20x20.png	manage	0.1 K	01 Jan 1970 - 00:00	Unknown User		h