In Drupal, there are actually a number of ways to add a WYSIWYG editor to a text area. The new “Drupal way”, used on over 150,000 Drupal sites and arguably not so “new” anymore, is to use the Wysiwyg integration module, which has support for several of the editor libraries. I would personally suggest using it, if your needs can be met by it, since it's becoming more and more powerful and offers a fair bit of flexibility to easily change the configuration or editor used. That said, there may still be reason, in Drupal 7, to use one of the single-library integration modules, such as the still-popular CKEditor project. The TinyMCE integration module development has already been abandoned in favor of Wysiwyg, but it's good to have alternatives. Note: In this post, we assume you already know your way around Text formats. Text format configuration can be one of the most tricky parts of properly setting up your WYSIWYG experience, so if you don't already feel you know your way around this common stumbling
If you happen to like the more “minimalist” editors, and your site's users won't be freaked out by having to see actual HTML code, you may wish to consider using BUEditor instead of any of those which integrate with Wysiwyg. We will cover using it in another post, since I've personally been convinced that it's maybe even more awesome than a “WYSIWYG” editor. This post will simply cover setting up TinyMCE or CKEditor with the Wysiwyg integration module.
sites/all/modules directory. It's activated on the Drupal
admin/modules page in the “User interface” fieldset, which you should see near the bottom of the page.
sites/all/modules directory and also activate them at
admin/modules. This blog post will not delve deeply into configuring images or associated modules — this can be a rather complicated topic, so it should also be covered in a separate post. So, while we'll be integrating IMCE and Lightbox2 for display of embedded images in this tutorial post, the full configuration of these modules will be covered separately.
If you aren't already sure that you want to use TinyMCE or CKEditor, it's a good idea to take a little time to experiment with at least some of the different alternatives to determine which you like the best for your use case. CKEditor and TinyMCE are the two editors which integrate best with the Wysiwyg module and IMCE (to allow uploading and adding images to text areas). You could try some of the others, but bear in mind that, at least at this stage, many of the editors are not very fully supported by the Wysiwyg integration and may not have support for the full button sets available, nor for integrated image upload, etc.
Editor libraries are added to Drupal by extracting their code files and putting them in the
sites/all/libraries directory, as per the directions:
As you can see it offers most tags you'd want for any HTML content and you'd only need to hand-code a few tags, here and there. You can experiment with this configuration on the Markitup "examples" page.
And that's with ALL available buttons selected… so Wysiwyg integration supports only a fraction of Markitup's standard Filtered HTML button set. Most disappointing! Well, having read up on the topic, I believe that it's just some work, currently, to integrate each button, so some editors that many people use are much better supported while others may still be more of a “development stub” example that the community can build on. It may just be that those of us interested in Markitup will have to help complete its integration with Wysiwyg (or help complete the port of the Markitup module to Drupal 7). But the search for a better “non-WYSIWYG” editor (text editor) did lead me to the BUEditor, a nice alternative which can be used with Drupal 7.
If we stopped now, we would only have an empty editor, one with no buttons — which would be much like no editor at all. Don't make the mistake of stopping now and thinking the defaults are probably good enough. Unfortunately, they aren't. Be sure to click on the “Edit” link which is now active for Filtered HTML and TinyMCE in the “Operations” column.
Just select buttons which will be useful and appropriate for the limits of the text format. In this image, you can see what should be an appropriate selection of buttons for a Filtered HTML text format. I would be sure to add the
<p>, and to be safe, both
<br /> tags to the allowed list of tags for your Filtered HTML text format. (See related article for more info about configuring text formats). Why? Now you can turn off the “turn line breaks into HTML” filter (which turns double line-breaks into
<p> tags and single ones into
<br />). You will probably find that any WYSIWYG editor is going to add those tags, anyway. And people will try to add them (in code view) and be annoyed by having them stripped out on output. Plus, you'll probably find that your code gets re-formatted, no matter what settings you use in configuring the editor.
I personally can normally accept all the other default settings, but change the Cleanup and Output settings, as shown. Verify HTML should be good, but I don't like the editor to add lots of styling when people paste. Let's try to keep that in the CSS files. I also don't like all the linebreaks removed, since I tend to look at the code, and I'm sure many others are like me and will also want to see or adjust the code. Assuming you don't have the “convert line breaks to HTML” turned on (you shouldn't if using a WYSIWYG editor), it’s safe to leave “Apply source formatting” on. It will give you some appropriate line breaks (hopefully) so that it’s easier to read through the code. The “Force cleanup on standard paste” option helps clear out some of the garbage that people might attempt to paste in. I’ve seen no reason to disable that feature.
Provided you are configuring TinyMCE and selected the same buttons I did, your editor should look something like this, at least to your regular users who probably will only have a limited set of HTML tags they are using.
To make sure that your editor and corresponding text formats are properly configured, you should test the different buttons and pay attention to the preview. Here, we can see that the
<strike> tag is not allowed by the current format (Filtered HTML) and should be added to the list of allowed tags for Filtered HTML if we want to have that button available for use*. Nothing is much more confusing and annoying to users than when they add the proper code, can see it in the code view, but don't see the same result in the saved output. Look at what tags are output by the editor (for each button used) and either disable the button or add the corresponding tag to the text format's allowed tags. Use the node preview button (at the bottom of the page, next to the “Save” button) to check [*Note: Actually, in the current TinyMCE, the “strikethrough” text treatment is accomplished by wrapping text in
<span> tags with a style attribute which achieves the same effect. In the current version of CKEditor, it's
<strike> tags. In other editors, you may find the “same” button adds
<del> tags. All three achieve the same effect and if you want to include the strike-through button, you may wish to add more than one of these tags to those allowed for your text format.]
There is a common issue across various editors integrated by Wysiwyg. If the editor provides a “preview” button, and most do, the preview will render any HTML, regardless of tag limitations imposed by the current text format. For example, this means that images and
<strike> tags used for strikethrough text will work as expected in a preview, but since the tags are not part of the default “Filtered HTML” text format, the
<img> tags will actually be removed on output instead of displaying an image or the text between the
<strike> tags with “
strikethrough” styling. You can still preview by clicking on the “Preview” node button, before saving, but the “preview” provided by the editor can be misleading. Hopefully future development of the Wysiwyg module might implement something like Ajax markup, which integrates with BUEditor (but not with the Wysiwyg module) to display text with correct output, i.e., according to active text format filter settings, etc.
It should be easier to set up your editor for Full HTML. You may also wish to create a filtered html text format for trusted users, e.g. a “Filtered+” HTML. Just follow the same steps. Add a few more tags to the allowed set (perhaps you trust these users to add images or sub-headings). My only advice is to follow the KISS principle and “keep it super simple”. It's easy to get carried away and add all buttons available for Full HTML. Resist the urge. You are more likely to run into bugs and you'll end up with an overwhelming user experience. I'd suggest keeping the button-set limited to the most useful tags.
This is what the button-set looks like if you select them all:
My recommendation would be to add just a few more buttons to the set you created for Filtered HTML. If you want users to be able to simply add images within their text and you've turned on the IMCE module, be sure to select both the Image and IMCE checkboxes. Working with images and IMCE is complex enough that we'll cover that in the next post.
Now you should check your filters. Make sure the appropriate filters are enabled and that text is processed by the filters in a reasonable order. The Filtered HTML Text format normally includes the “convert line breaks to HTML” filter, which doesn't make sense if you are using a WYSIWYG editor (just be sure to include the
<br /> /
<br> tags in your allowed set). For Full HTML or other text formats with images, you'll probably want to include other filters, such as the Image Resize Filter and/or Lightbox. Again, we'll cover image-related tips in the next post.
Be sure to test that everything works the way you want it to. Be sure to test that all of your user roles have the expected access to the editors and text formats and that features are working as expected. If you are working on a local development environment, it can be helpful to turn on the Devel module's “switch users” block and give all user roles permissions to use it. This will allow you to easily switch between a user of one role and your user-1 admin to tweak permissions or other configuration.
Be sure to check back for our next post about working with images in a WYSIWYG editor, which should be posted in the next few days.