TinyMCEPlugin

Integration of the Tiny MCE WYSIWYG Editor

This is an integration of the fast and highly functional TinyMCE WYSIWYG editor. It supports a wide range of browsers, including Firefox, IE, Safari, Opera and Google Chrome (see compatibility chart). At the time of writing it doesn't work with Konqueror.

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

The editor uses a translator module to convert from Foswiki Topic Markup Language (TML) to HTML and back. The translator converts special macros - such as %MACROS% - to plain text, and encloses them within HTML spans using a special style called WYSIWYG_PROTECTED. In this way the editor can detect text that is not meant to be HTML formatted. This style is also used to protect special text you enter into the editor from being interpreted when the topic is translated back into TML. If you want to add any special features that are sensitive to formatting, such as Set statements, then you should format those regions using 'Protect on save' or 'Protect forever'.

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 WysiwygPlugin
• 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. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> 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 https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

• Enable the WysiwygPlugin in configure.
• Enable the TinyMCEPlugin in configure.
• Click on edit of any topic.

Preferences

The default configuration of TinyMCEPlugin should prove sufficient for most users. The TinyMCE editor itself is customised through a Javascript object holding a substantial number of initialisation parameters. In previous versions of TinyMCEPlugin, a text string making up the Javascript object was held in an ordinary Foswiki preference variable TINYMCEPLUGIN_INIT which should be removed and replaced with TINYMCEPLUGIN_INIT_TOPIC (described below) in most circumstances.

TINYMCEPLUGIN_INIT_TOPIC

To make configuration easier and less error-prone, configuration is held in a topic section. The name of the topic is set in the preference variable TINYMCEPLUGIN_INIT_TOPIC, from which the section named TINYMCEPLUGIN_INIT is used. TINYMCEPLUGIN_INIT_TOPIC is currently set to %=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 TinyMCEPlugin is upgraded.

TINYMCEPLUGIN_INIT

%STARTSECTION{"TINYMCEPLUGIN_INIT"}%
"mode" : "textareas",
"editor_selector" : "foswikiWysiwygEdit",
"save_on_tinymce_forms" : true,
"table_default_cellpadding" : 0,
"table_default_cellspacing" : 1,
"table_default_border" : 1,
"theme" : "advanced",
"convert_urls" : true,
"relative_urls" : false,
"remove_script_host" : false,
"dialog_type" : "modal",
"extended_valid_elements" : "li[type],a[rel|rev|charset|hreflang|tabindex|accesskey|type|name|href|target|title|class|onfocus|onblur|data*]",
"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_plugin_urls" : {
    "foswiki" : "%PUBURLPATH%/%SYSTEMWEB%/TinyMCEPlugin/plugins/foswiki/editor_plugin.js",
    "foswikibuttons" : "%PUBURLPATH%/%SYSTEMWEB%/TinyMCEPlugin/plugins/foswikibuttons/editor_plugin.js",
    "foswikiimage" : "%PUBURLPATH%/%SYSTEMWEB%/TinyMCEPlugin/plugins/foswikiimage/editor_plugin.js" },
"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, %IF{"context SUPPORTS_PARA_INDENT" then="fwexdent, fwindent" else="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"}%"
}%",
"entity_encoding" : "%IF{
    "defined 'TINYMCEPLUGIN_ENTITY_ENCODING'"
    then="%TINYMCEPLUGIN_ENTITY_ENCODING%"
    else="%STARTSECTION{"ENTITY_ENCODING"}%numeric%ENDSECTION{"ENTITY_ENCODING"}%"
}%",
"theme_advanced_toolbar_location" : "top",
"theme_advanced_resize_horizontal" : false,
"theme_advanced_resizing" : true,
"theme_advanced_path" : false,
"theme_advanced_statusbar_location" : "none",
"skin" : "%IF{
    "defined 'TINYMCEPLUGIN_MCESKIN'"
    then="%TINYMCEPLUGIN_MCESKIN%"
    else="%STARTSECTION{"MCESKIN"}%o2k7%ENDSECTION{"MCESKIN"}%"
}%",
%IF{
    "defined 'TINYMCEPLUGIN_MCESKIN_VARIANT' AND $'TINYMCEPLUGIN_MCESKIN_VARIANT'"
    then="\"skin_variant\" : \"%TINYMCEPLUGIN_MCESKIN_VARIANT%\",$n"
    else="%IF{
      "NOT defined 'TINYMCEPLUGIN_MCESKIN' OR $'TINYMCEPLUGIN_MCESKIN'='o2k7'"
      then="\\"skin_variant\\" : \\"%STARTSECTION{"MCESKIN_VARIANT"}%silver%ENDSECTION{"MCESKIN_VARIANT"}%\\",$dollarn"
    }%"
}%"keep_styles" : false,
"content_css" : "%PUBURLPATH%/%SYSTEMWEB%/TinyMCEPlugin/wysiwyg.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 SitePreferences or any WebPreferences:
  

     * Set TINYMCEPLUGIN_INIT_TOPIC = %HOMEWEB%.TinyMCEPlugin

Settings

Browser Specific Settings

Additional options may be set for specific browsers. You can define extra options for MSIE, OPERA, GECKO, UNKNOWN and SAFARI. For example,

   * Set TINYMCEPLUGIN_INIT_MSIE = "paste_auto_cleanup_on_paste" : false 

The defaults are:

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

TinyMCE Plugins & Toolbar Buttons

Documentation for standard plugins shipped with TinyMCE can be found at http://wiki.moxiecode.com/index.php/TinyMCE:Plugins.

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

These plugins are enabled by default in the standard distribution of Foswiki.

Additional Plugins

To enable extra plugins, set the TINYMCEPLUGIN_ADDITIONAL_MCEPLUGINS variable in your Main.SitePreferences. If the plugin also offers a toolbar button, you will need to add it into the appropriate place in the TINYMCEPLUGIN_ADDITIONAL_BUTTONS* variables.

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

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

Some notable plugins:

Frequently Asked Questions

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

WysiwygPlugin Settings

See WysiwygPluginSettings for more information

Upgrading from TinyMCEPlugin versions prior to 05 Mar 2010 release

The TINYMCEPLUGIN_INIT string needs to be built differently, due to the API change affecting the way custom formats are applied in TinyMCE 3.3.x since 3.2.x

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 TinyMCEPlugin

• Foswikitask:Item8475 - Foswiki introduces errant spaces into table cells
• Foswikitask:Item8582 - X11 environments: TinyMCEPlugin 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:Item9198 - After inserting new table at top of document: unable to position cursor above
  • Work-around: Use 'Save and continue' or switch to TML editing and back to WYSIWYG again to allow WysiwygPlugin to add an empty <p/> above the table
• Foswikitask:Item8085 - International characters (example, Š) are converted to HTML entities (IE. Š or Š)
  • Ensure you are using the latest version of WysiwygPlugin.
  • Work-around: Try changing the TINYMCEPLUGIN_ENTITY_ENCODING setting to raw. It's possible this may cause problems on older browsers.

Known Issues of WysiwygPlugin (partial list)

For the full list, consult WysiwygPlugin documentation

• Foswikitask:Item1396 - Anchors are not handled by WysiwygPlugin
• Foswikitask:Item5955 - WysiwygPlugin 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 WysiwygPlugin does not know how to preserve. If such attributes are necessary, please use VarTABLE 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 VarTABLE macro above the offending table that adds the desired attributes safely

Check regularly at Foswiki:Extensions.TinyMCEPlugin for updates.

Copyright

© 2007-2010 Crawford Currie http://c-dot.co.uk, © 2010-2017 Foswiki Contributors

This package also includes the complete sources for version 3.5.7 of the TinyMCE editor which is covered by its own license.

Info

Many thanks to the following sponsors for supporting this work:

• ILOG
• Carrier Corporation
• TWIKI.NET

Dependencies

Change History