Taming the WYSIWYG Editor in 3 Steps

Drupal's WYSIWYG editor was once described to me by a colleague as "where the rubber meets the road" for clients. In other words, its the part of the website that your clients will be interacting with the most. You can spend hours or days perfecting a theme, configuring modules, and writing custom code to make a site as beautiful and useful as possible, but if the WYSIWYG editor does not work as advertised, it can ruin the experience for a client. When they call you for help, they're not going be thinking about that beautiful theme you designed our that useful custom module you wrote; all they're going to be thinking about how the table they added is formatted strangely, or that no matter how hard they try, they cannot right align that darn paragraph. In this post, I'll list some tips I've used to help avoid these pitfalls.

For this tutorial, we'll be using Drupal 7, the WYSIWYG module, the WYSIWYG Filter module and the TinyMCE plugin. If you prefer to use a different editor plugin such as CKEditor, OpenWYSIWYG, etc., the instructions for step one will differ, but the principals remain the same.

Step One: Simplify the Interface

First and foremost, its a good idea to remove all buttons from the WYSIWYG editor that are not absolutely needed. This has many benefits:

• Provides editors with an uncluttered interface with which to create content
• Prevents editors from inadvertantly messing up the look of pages by using too much formatting, or styles that are inconsistent with the theme
• Saves time and effort when configuring the HTML Filter and creating new CSS styles (See steps 2 and 3)

To remove buttons from editor, simply go to Configuration > Content Authoring > Wysiwyg Profiles, and click Edit next to the Filtered HTML WYSIWYG profile. (You only need to worry about the Filtered HTML profile because you should never give your clients permission to use the Full HTML text format anyway, for myriad security reasons I won't go into in this post.)

Expand the Buttons and Plugins fieldset, and uncheck any extraneous buttons and plugins. The buttons you should leave will vary depending on your project requirements, but a good rule of thumb is that if you're not sure about it, remove it. You can always re-add buttons later if the need arises. The buttons I use most frequently are:

• Bold, Italic, Underline, Strikethrough
• Align: Left, Center, Right, Justify
• Bullet List, Numbered List
• Outdent, Indent
• Link, Unlink, Anchor
• Image
• Blockquote
• Source Code
• Horizontal Rule
• Cut, Copy, Paste

That's it. It can be tempting to think in terms of "more is better" and but resist the urge to add too many buttons...you'll see why this is so important in steps 2 and 3. When you're finished trimming the list, click Save.

Step Two: Configure the Text Format

Next, we'll need to make sure that all the tags, attributes, and CSS attributes that can be generated by the WYSIWYG editor will not be filtered out. This is where the WYSIWYG Filter module comes in. After installing and enabling this module, go to Configuration > Text Formats > Filtered HTML > Configure. In the Enabled Filters section, check WYSIWYG Filter, and uncheck Limit allowed HTML tags, as its redundant.

In the Filter Settings section further down the page, click the WYSIWYG Filter. In the HTML Elements and Attributes textarea, you'll need to list each and every element and attribute that could could be present in nodes, given the buttons and widgets we made available to the client in step 1. The syntax to use here is the same as the TinyMCE Valid Elements syntax, so be sure to read up before filling this field in.

For example, if you added the left/right/center/justify alignment buttons to the editor in step 1, you'll need to add the following text here:

div[style|align<center?justify?left?right]

Below the HTML Elements and Attributes text area, you'll see an array of checkboxes for CSS styles. Check off any styles that could be generated from the WYSIWYG editor, given the buttons and widgets we added in step 1. These allowed styles, combined with the allowed elements and attributes we defined above, combine to form our "safe list". Any WYSIWYG generated content that isn't on the list will be filtered out.

Step Three: Test, Style, Repeat

So far, we've:

• Given the client a specific, finite set of tools for creating content in the WYSIWYG editor
• Ensured that these tags, attributes, and styles (but no others) make it into the final output by specifying them in the Filtered HTML Text Format configuration

What's missing? We need to make sure that styles have been defined correctly for the content we've allowed in the first two steps. If styles aren't defined correctly, content in nodes may look differently than the client intended when he or she created that content in the WYSIWYG editor, leading to confusion and frustration.

The best method I've found for this step is to first create a test node that includes examples of each and every formatting option provided in the editor, verifying that the content is being displayed properly on the node, and if not- define additional styles as necessary. This is the time to be extremely thorough. For example, if you decided to add the table widget to the interface back in step one, you'll need to add a table to the test node that contains each and every one of the options available to the client in the table widget. That means entering data for each one of the fields in the table widget popup (e.g. width, height, cellpadding, cellspacing, etc.), not just the basic ones. If your client has access to an option, it needs to be tested and working. Given how time-consuming this can be, you can start to see why its so important to keep the WYSIWYG interface lean and mean back in step one.

Save and view your test node. If any WYSIWYG content within is not formatted as you expected it to be, you'll likely need to add some CSS definitions to your theme. Its also possible that attributes, elements, and CSS styles are being filtered out if you missed anything in step 2. You'll have to view the source code to figure out whether each formatting issue is due to filtering or incorrect CSS style definitions. As with most things web development related, Firebug is invaluable here.

You'll likely have to go through several iterations here of testing, modifying CSS, and modifying the WYSIWYG filter settings. You'll know you're done when you can fully utilize all buttons and widgets in the WYSIWYG filter, and the resulting node output displays exactly as expected.

It can be a lot of work, but the end result is an interface that your client will enjoy working in, and one that creates beautiful, secure content.