Composr Tutorial: WYSIWYG editing

Composr's multi-line Comcode content is, by default, edited using a WYSIWYG editor. This makes things easier for beginners to edit.

This tutorial provides some guidance on the WYSIWYG editor, including advanced information for those wanting to push it to the limit.

WYSIWYG editors on the web

The Composr WYSIWYG editor. See the disable button in the top-right.

(Click to enlarge)

A WYSIWYG (What You See Is What You Get) editor is a document editor where the editor's editing interface roughly mirrors the appearance of the final document. Websites deploy WYSIWYG editors via a combination of JavaScript and built-in editing features that are present in the popular modern web browsers. Online WYSIWYG editors are HTML editors: the document created is manipulated and transmitted as HTML.

Integrated editor

The Composr WYSIWYG editor is CKEditor. It is enabled by default via the "Enable WYSIWYG editing" configuration option.

For programmers: Composr can, in principle, support almost any WYSIWYG editor component. Composr binds itself to the editor via JavaScript code stored in Composr's WYSIWYG_LOAD.tpl, _wysiwyg_settings.js, and posting.js templates. The editor itself is stored in data/ckeditor.

Link parsing

Automatic link parsing, and some other minor Comcode features, are not guaranteed to work when using the WYSIWYG editor. This is due to a complex set of conditions for what depth/type of Comcode parsing Composr goes into. These conditions are designed to minimalise corruption through incorrect or unnecessary assumptions made by Composr.
You should use the features of the editor to explicitly mark up your content as you want it and think of it as mainly an alternative to writing Comcode, rather than a supplement to it.

One scenario where automatic link detection runs is when an explicit anchor tag has already been added. Composr will assume you want any written URLs to display literally and that you'll use anchor tags explicitly when you want them.

Highlighting of Comcode tags

Comcode tags that can not be represented visually in the editor will be shown either as:

1. raw Comcode, and highlighted with a yellow background;
2. a button that you can click to edit the parameters there-of (usually for tags that insert something, rather than being markup), with preview tooltips
3. As a fake XML tag in the editor, with the Comcode tag name highlighted

If you put the mouse over the Comcode you will see a tooltip showing how it looks (shown in the bottom-right of the browser window).

Do not worry if this yellow background spreads around (this can happen if you type in certain places) – it will be stripped when you save.

Staff editor

By default, certain WYSIWYG features will only be given to staff users. This is because we generally want to show a simpler editor to regular users.

If you want to change it you can customise the _wysiwyg_settings.js template. For example, changing the second line of that template to var precision_editing=true; would force the full editor to be available for everybody.

The clipboard (copy & paste)

Operating systems (such as Windows) hold different kinds of data in the clipboard. Often when you copy something it will be held in multiple formats.
For our purposes, consider the following kinds of data and how they are handled by CKEditor (actually by the web browser itself, CKEditor has no direct control over it):

1. Plain text – pasted exactly
2. Rich text (e.g. from Microsoft Word) – converts to HTML, often has some loss
3. HTML – pastes exactly, but when put into the clipboard it usually is simplified and made standalone (e.g. CSS class references are replaced with inline styles)
4. Files – just pastes the filename; except in Firefox, which will paste image contents if it is an image (see below)
5. Images – pastes the image in inline, but may not work in all browsers (confirmed working in Firefox and Chrome and Internet Explorer 11 – not working in Safari and older versions of IE)
6. Spreadsheet cells – typically pastes a raw table with no special formatting

It is worth noting that for copy & paste to work, the following are all involved (in order):

1. Source application (e.g. web browser): takes the data and puts it into the clipboard, potentially in multiple formats (e.g. plain text, rich text, and HTML)
2. Operating system: manages the clipboard system
3. Web browser: takes the most appropriate supported data format, and feeds it through as HTML
4. WYSIWYG editor (Ckeditor): takes/holds the HTML, and potentially manipulates it a bit

Different operating systems, source applications, and web browsers, may lead to inconsistencies in how copy & paste operations are handled.

You will notice when you press the paste button from the WYSIWYG toolbar, it makes you paste using a keypress. This is because the web browser won't allow the editor's JavaScript code to directly access the clipboard – for security reasons.
If you directly use the keypress to paste this is not an issue. However it is better to paste via the paste button as it has special provisions for cleaning up the pasted data. For example, it will allow spreadsheet data to come through correctly.

Sometimes you will want to paste plain text into the editor, which is a problem when the browser puts priority on pasting rich text / HTML versions. A novice user might not even understand why peripheral styles have come along with what they pasted.
You can solve this a number of ways…

1. Manually type rather than using copy & paste
2. Copy & paste into Windows notepad (or equivalent, e.g. TextEdit on a Mac), then copy out of Windows notepad, then paste into the editor
3. Turn off WYSIWYG
4. Use the "Paste as plain text" button in the WYSIWYG editor

The final option is usually the most sensible one, but for the sake of thoroughness, I wanted to expound on different approaches users take.

Tables

By default Composr does not show table borders (†). This is to make things very plain by default, and also so that WYSIWYG-edited tables can be used for laying things out spatially in columns.
Using tables for layout is not ideal (professional web developers use CSS techniques), but if it's only within some content it won't harm your SEO.

† Actually within the editor table borders are shown as dotted, via specific styling rule for this. This is just so you can see what you are editing.

You can set the border when you add the table in CKEditor, or when you edit the table properties. You can also edit the cell spacing and cell padding from here.

If you set a border of "1" then Composr makes sure that borders between cells become visible again, rather than it only being a border around the whole table. This is done via a special rule within our default CSS file.

Another technique you can use is to edit the HTML source within the editor. You can removing the default border/spacing/padding/width/style that CKEditor added, and use class="results-table" instead. This will activate some of Composr's default styling for visually attractive tables.

Embedding files

There are currently 6 ways to get images (and other files) into the WYSIWYG editor:

1. Attachments
2. URLs
3. Pasting within HTML (typically will lead to embedded URLs)
4. Pasting within rich text (typically will lead to "base64" embedded images, which Composr will turn into inline attachments)
5. Drag and drop (this may be sporadic, JavaScript support for this is very new and prone to a variety of bugs, as a lot of cutting-edge browser subsystems are involved)
6. Direct pasting of raw image data (see "The clipboard (copy & paste)" section above)

Attachments

Composr has its own system for making attachments. If the WYSIWYG editor is for a 'Post area' then there will be either:

1. an attachment facility beneath it
2. attachment upload via the WYSIWYG's image button; if the "Simplified attachments UI" configuration option (Admin Zone > Setup > Configuration > Content editing options > Comcode) is on, which is the default

Once files are chosen you may get the attachment options. Attachment options let you do things like 'float' the attachment. Whether you get the options or not depends on the code written in the _attachment_ui_defaults.js template. By default image attachments bypass the options to simplify things (you can use the editor to change how attached images look anyway).

After the options are set either a marker will be placed into the editor (non-image attachments) or the image will appear after a few seconds.

You may move this marker/image around by cutting and pasting it – placing it anywhere you desire within the editor.

URLs: Referencing uploaded images

This is not available via direct-WYSIWYG if the "Simplified attachments UI" configuration option (Admin Zone > Setup > Configuration > Content editing options > Comcode) is on.

Another way to embed images is to use the image icon that exists within the WYSIWYG editor (or manually via the Comcode img tag if you prefer).
With this, you may reference any image that already exists on the web, via URL.

The drawback with this is that the file must already exist, and be stored outside of the context of the Composr website that it is being referenced on.

However, one handy convention for Composr website administrators, is to upload the file to the uploads/website_specific directory using FTP, and then referencing the image from there. This precreated directory is designed for storing this kind of file, and will help you keep things tidy. As long as you backup this directory with the rest of your website, the URLs should not break.

We go to specific measures to make sure that URLs are defined relative to the website's base URL, regardless of where the editor is running from.
This is really important for content portability. We then actually save using absolute URLs (i.e. we include the domain name etc).

Manually editing HTML source

Toward the top-left of the editor is a button to toggle HTML source view in the editor. When in HTML source view, you may manually enter and edit the HTML that will be used. This is useful:

• in circumstances where things have not pasted into the editor as you expected
• when you have some specific HTML in mind that is hard to recreate visually, such as HTML involving JavaScript (note that only super-administrators may input JavaScript)

HTML filtering

Composr does not accept the HTML from the WYSIWYG editor directly as input for Composr content. This is for three reasons:

1. This poses a severe security risk
2. The HTML generates via WYSIWYG is often a mess
3. Composr rich content is defined in Comcode, not HTML

Security filtering

HTML acts as a container for numerous technologies, including CSS and JavaScript. JavaScript can be used as a vehicle for attacking websites via a technique called 'XSS' (Cross Site Scripting). Basically an XSS attack can be used to steal logins; it works by a user submitting content that includes malicious JavaScript code that causes hijacking of the web browser of the viewer of the said-content. This is a major issue, and means that Composr has to go to great lengths to protect against it.

The HTML is treated to one of two possible security filters, depending on circumstances:

1. The safelist filter (more finicky)
2. The blocklist filter (more liberal)

(super-administrators are not subject to any filter)

The safelist filter is subjected to those users who do not have the "Use Dangerous Comcode" permission, and blocks any HTML that is not known as safe. Users subjected to the safelist filter will find that some complex formatting may be lost.

The blocklist filter is subjected to the users who do have the "Subject to a more liberal HTML filter" permission, and will go to great lengths to try and strip any JavaScript from the HTML. There are no known problems with the blocklist filter, but the developers can not accept any liability for the consequences of using it (although we have gone to great lengths to make the blocklist filter very safe).

Cleanup

The HTML that comes from directly from the WYSIWYG editor is often very messy for a number of reasons:

• If it was created via pasting from Microsoft Word, there is a high likelihood that it contains great amounts of superfluous code
• The process of visual editing itself often results in code complexity, as formatting changes are often made that override existing formatting, yet leave both sets of formatting code in-place.

Messiness presents numerous problems:

• Slow-down on the server
• Extra bandwidth usage
• Bad "semantics" (difficulties for users of screen-readers)
• Challenges for anyone hand-editing the code

In addition, Composr works via XHTML5, not HTML5; for the cases where HTML and XHTML are non-equivalent, it is best that Composr clean things up.

The rest of this section explains how to clean things up.

Within the editor

The remove styles button in the editor is very useful for removing junk styles.

Additionally, the source-code view can be used to manually clean things up.

Comcode conversion (advanced)

It is the view of the developers that, where possible, content should be able to be hand-edited, and usable in different contexts (e.g. on mobile phones as well as on the web).

You may choose to enable the Comcode conversion configuration option if you wish, but honestly we no longer like or recommend this option, as it can mangle any non-trivial styling. The rest of this section applies only if conversion is enabled…

Composr will thus go to great efforts to turn complex HTML into equivalent simple Comcode, where possibly fully eliminating all direct usage of HTML.

Where HTML cannot be fully eliminated, Composr will encapsulate it with Comcode semihtml tags, within the wider Comcode.

Sometimes the Comcode conversion is imperfect. For example, line breaks can be introduced, or some custom formatting can be lost.

If you do not want Comcode conversion, you can either:

1. Disable the Composr "Convert XHTML to Comcode" configuration option (Admin Zone > Setup > Configuration > Content editing options > WYSIWYG editor)
2. Un-tick (un-check) "Aggressive HTML conversion" under the Comcode posting field (if it's a posting field)
3. Include this hint in your content:
   

   Code

   {$,page hint: no_smart_conversion}


Problem areas, and turning the editor off

Sometimes WYSIWYG editing is more trouble than it's worth. When particularly complex layouts are produced, or code pasted from documents, it can still result messy and slow code; especially when content is long. This is particularly bad for websites that favour very high web standards (such as perfect WCAG accessibility), which will always need to have a degree of hand-coding in them, to maintain those high standards.

Generally it's also not a good idea to have anything that is not directly WYSIWYG in the WYSIWYG editor, including careful use of tags to apply custom CSS styles, or JavaScript. Various things can relate to it getting stripped or corrupted.

For these situations it is best to simply turn the WYSIWYG editor off. You can do this on a per document basis by pasting this bit into your code:

If you turn off the WYSIWYG editor when editing something, Composr may actually add this automatically. You may notice then that the enable/disable button disappears from alongside that field. This is to stop other content editors going in, and then accidentally corrupting carefully constructed Comcode via WYSIWYG.

CKEditor skins (advanced)

We bundle 3 skins that we like:

1. kama
2. moono (the default)
3. moonocolor

To change skins you need to edit the _wysiwyg_settings.js template. Change the skin name in the obvious place.

If you want to download other CKEditor skins and place them in data/ckeditor/skins/ there's nothing stopping you. That said, we test/optimise for the above skins only (including having different icons for our custom plugins for the different skins, defined in forms.css).

See also

• Comcode and the attachment system

Feedback

Have a suggestion? Report an issue on the tracker.