Wysiwyg Plugin

Support for the integration of WYSIWYG (What-You-See-Is-What-You-Get) editors. Comes bundled with a complete integration of the feature-rich Kupu editor.

The plugin is a generic framework that supports editing of TWiki topics using any browser-based HTML editor. It works by transforming TML (TWiki Meta Language) into HTML for the editor and then transforming HTML back into TML on save. These steps can be separated to support the import of HTML from external sources such as existing web pages.

The plugin should operate with TWiki20040904 as well as TWiki-4.0.0 and later.

Caveat: WysiwygPlugin is designed for editing TWiki topics, not as a general purpose HTML editor. It will work fine on topics that contain text, TML formatting, and most HTML. However, because of the complexity of transforming TML into HTML and back, complex TML, and mixing HTML and TML may not give the results you expect. You are recommended to use the standard browser textarea editor for editing existing topics that contain mixed HTML and TML, or complex %TML%-type variables.

How to use the editor

Basic help for most of the functions in the toolbar is available by "hovering" the mouse over the button.
Some functions require a bit more explanation:

"Insert No-Op" inserts a <nop> region. Any TWiki syntax such as wikiwords or variables inside the region will be disabled in the rgeion. $lt;nop> regions may not extend over line breaks.

The rightmost drop-down will give you a menu of TWiki variables that can be inserted. Any of these variables can be edited after they have been placed in the text, for example to add parameters.

"Insert a WikiWord" will give you a menu of topics in the current web that can be inserted. Topics are inserted as links, though typing wikiwords in plain text will work just as well.

Watch out for the <> button on the right of the toolbar. It lets you switch into an HTML view, which can be very useful when you can't get your formatting right.

In TWiki, a totally empty table cell causes the cell to be merged with the cell immediately to the left. To make this effect more transparent in the editor, these empty cells are shown with the text "%SPAN%" in them. In Kupu, if you add %SPAN% to a table cell, then all the rest of the content will be thrown away and the cell will be converted to an empty table cell. Note that this only applies to tables that are converted to TWiki syntax.

Kupu Notes

The version of Kupu shipped with this plugin is an uncustomised basic Kupu release. All the TWiki customisation is done as plugins and extensions to Kupu - the basic kupu code is shipped completely intact.

How it works

The plugin works by translating the topic text into HTML, which is then fed to the editor. The edited HTML is then run through the reverse translation before saving to the topic. TWiki syntax is used in preference to HTML in the stored topic wherever possible, though HTML may be used if the translator can't find a suitable TML equivalent..

The default rendering that TWiki uses to generate HTML for browsers is 'lossy' - information in the TWiki syntax is lost in the HTML output, and a round-trip (recovering the original TWiki syntax from the HTML) is impossible. To solve this problem the plugin instead uses its own translation of TWiki syntax to pure XHTML. The generated XHTML is annotated with CSS classes that support the accurate recovery of the original TWiki syntax.

(before you ask the obvious question, yes, the translator could be used to replace the TWiki rendering pipeline for generating HTML pages. In fact, the translator is taken almost directly from the implementation of the rendering pipeline for the TWiki 'Dakar' release)

Translation of the HTML back to TWiki syntax uses the CPAN:HTML::Parser. This parser is used in preference to a more modern XML parser, because the HTML may not generate fully compliant XHTML. A strict parser would risk losing content. CPAN:HTML::Parser is better at handling malformed syntax.

There is also the advantage that the translator can be used to import HTML from other sources - for example, existing web pages. Due to the simple nature of TWiki syntax and the complexity of HTML, this translation is lossy - i.e there will be HTML features that can be entered by editors that will be lost in this translation step. This is especially noticeable with HTML tables.

Using the translators from Perl scripts

Both translators can be used directly from Perl scripts, for example to build your own stand-alone translators.

An example stand-alone convertor script for HTML to TWiki is included in the installation. It can be found in the top-level tools directory and is called html2tml.pl.

(Dakar) Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.

To enable the editor in one of your skins, add the following link to the skin alongside or in place of the existing 'edit' link:<a href="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%WEB%/%TOPIC%?skin=kupu">Kupu</a>As you can see this is just a standard edit link with the 'kupu' skin in place of the usual edit skin. Here it is for this topic: Kupu. Try clicking on it, but do not save!

Plugin Configuration Settings

Web/Topic name of a help page. Change this to point to your local version of the help page, which is brought up when the .

Set HELPPAGE = TWiki/WysiwygPlugin

Other Settings

The editor template includes a number of files that can be used for other settings. These files are not defined in the distribution, so that you can create your own local content.

TWiki.WysiwygPluginIcons

You can define a list of icons that will be available in the Kupu editor when the toolbar button is pressed. This topic has to contain a list of <IMG> tags. If present, the 'alt' text will be used in place of the <IMG> tag when translating from HTML to TML. Example:

The bit between the > < value defines text in the drop-down box in the editor, and the value defines the actual string inserted in the topic.

TWiki.WysiwygPluginLocalHelp

If it exists, the contents of this topic will be included and shown on the edit screen below the status bar. It is intended to be used for site-specific quick help information.

Editor control

The global TWiki Variable 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 refuse to edit if

some or all of HTML tags (e.g. <br /> or <div>), or

simple variables (e.g. %VAR%) or

calls (e.g. %VARIABLE{...}%)

PRE blocks (<pre>)

HTML comments (<!-- ... -->)

are used in the topic. If the plugin detects an excluded construct in the topic, it will redirect to the default editor. Comma-separated list of one or more of html, variables, calls, pre or comments e.g.

Set WYSIWYG_EXCLUDE = variables,calls (inactive; you need to remove monospacing from this setting to enable it)

If you are using this plugin with TWiki-4.0.0 or later with pattern skin, the %COMPOSER% global TWiki variable is used to control the skin used for the WYSIWYG editor link. You can define this variable to the empty string to disable WYSIWYG editing on a site, per-web, per-user or per-topic basis.

Known Issues

Most of the known problems with the plugin are actually problems with the Kupu editor or the browser rather than the plugin.

Because TWiki uses a "best guess" approach to some formatting, it allows overlapping of tags in a way forbidden by HTML, it is impossible to guarantee 100% that formating in the original TWiki document will still be there when the same document is loaded and then saved through the WysiwygPlugin. The most obvious case of this is to do with styles. For example, the sentence

*bold _bold-italic* italic_

is legal in TML, but in HTML is represented by

<strong>bold <em>bold-italic</em></strong> <em>italic</em>

which gets translated back to TML as

*bold _bold-italic_* _italic_

which is correct by construction, but does not render correctly in TWiki. This problem is unfortunately unavoidable due to the way TWiki syntax works.

Support for PRE

Because of limitations in the browsers, the editor does not support PRE blocks. All PRE blocks will be converted to TWiki verbatim blocks on save. This can cause some confusion, especially when editor formatting controls (such as "bold") have been used to format text in a PRE block. Users are advised to use only plain text in PRE (verbatim) blocks.

Plugin Info

This plugin is heavily based on the TWiki::Plugins.KupuEditorAddOn, and the authors of that add-on are therefore also credited as authors of this plugin.

Item1529 evil, evil. The XMLSerializer in IE isn't happy serializing the DOM. I have no idea why. Kupu manages to get away with this because it passes the DOM through the XML validator, which I had to disable because it strips comments. So, for now, the IE implementation will strip comments - but at least you can save again

Item1259 changed comment handling; rather than trying to create HTML, which gets munged, create an HTML comment. This will only be editable by switching to source view, but hey, it's supposed to be WYSIWYG. Note that this also means that comments in pasted HTML should be retained now

Item1189 filter whitelist is not good enough; need to generate B and I nodes. templates/ pub/TWiki/WysiwygPlugin

7902

Item1189 it took bloody ages to track down, but finally discovered that bold and italic were being filtered out of spans by Kupu 1.3.2.... too smart for it's own good. So added them to the filter whitelist, and it works again.

7873

Item1189 added pre save filter to try and find where the attributes are disappearing to in FF

7872

Item1187 for lack of an s on an RE, the nation was lost (well, the multi-line comment actually). Thanks Kenneth!

7871

Item859 solved issue with non-display of inserted images. Was due to the use of an onSubmit handler to close the dialog, rather than an onLoad handler triggered when the IFRAME that contains the result is loaded.

7869

Item1172 had to rewrite big chunk of the table popup to get it working with 1.3.2

Navigation

This site is powered by the TWiki collaboration platform. All material on this collaboration platform is the property of the contributing authors. All material marked as authored by Eben Moglen is available under the license terms CC-BY-SA version 4.