mediatribe.net -- Drupal et développement web

Update May 3, 2010 -- Please see the first comment, below. Some of the hacks in this article are outdated. Please proceed carefully and report your results here!

Installing a WYSIWYG (what-you-see-is-what you get) editor in Drupal 6.x is a convoluted process, with numerous pitfalls. Here is my way of getting it to work with image upload and link upload functionality.

(Notes: (1) you will find much simpler tutorials, but often they use the IMCE module which my clients often find too complicated to use; (2) this solution uses a patch which is frowned upon by the wysiwyg api maintainers because we allow FCKEditor, and not Drupal modules, to upload files in certain circumstances. We do this because the user experience is much better this way).

What you need:

• drush (recommended)
• Intermediate Drupal knowledge
• SSH (shell) access to your server and basic knowledge of the command line.
• Knowledge of how to patch Drupal

First, in the command line, navigate to the root of your Drupal installation in SSH.

Then, download some modules.

• wysiwyg is the API which lets you associate a wysiwyg editor to an input format. This is the most logical way to implement wysiwyg: it doesn't make sense for wysiwyg to be associated with a field output as filtered HTML, say, as all images you enter will disappear.
• fckeditor implements the visual editor on pages which do not have input formats associated with them, like the contacts settings page and the mission statement. Important: fckeditor should be in your sites/[your site or default]/modules folder, not sites/all. This is because we want each site in a multisite environment to have its own copy of fckeditor, so that images for different sites don't get mixed up.
• better_formats allows you to have certain users automatically have a non-default input format selected. This is so that anonymous users enter text using the "filtered HTML" input format, and admins or editors use "wysiwyg".
• imagecache allows you to define small, medium, and large sizes for entering images; this is useful because in many cases novice users enter images from a digital camera and you don't want them taking up 3000 pixels of screen real estate.
• imageapi: imagecache relies on this to work.
• image_resize_filter is for those cases where a user chooses to enter an image in the original format (possibly very large and very heavy), then resizing it using the resize handles in fckeditor. This module resizes the images on the server rather than sending a large image to a visitor's computer and then resizing it. With this module enabled, the site will load a lot faster in certain circumstances.
• htmlcomment is a solution for a quirk in Drupal. Normally, the initial "less than" (<) symbol before comments is escaped, so that the entire comment becomes visible on the screen. This is often just annoying and users who entered comments just remove them when they realize that the comments appear to the end user. However, with a wysiwyg editor, this problem becomes critical when pasting from Mirosoft Word. What happens is this: many users copy a text they wrote in Microsft Word and paste into the visual text editor. All looks great, but when you save your post, Drupal escapes the comments, and you see a comment, often beginning with "if gte mso 9", on-screen. (Search "if gte mso 9" and you'll find tons of sites which have this problem). With this module enabled, the pages and pages of commented code inserted by Microsoft Word are never escaped so the end-user never sees it.

Here's the drush code:

Let's enable a few of these right away (a few notes: (1) with my version of drush I need to perform the following code twice to not get any errors; (2) imageapi_gd is one of the libraries which implement imageapi -- you can also use another one):

Now, in admin/user/roles, make sure you have a role for users who can access the wysiwyg editor (I call mine "wysiwyg editor", and we'll use that name for the rest of this article). Create a new user for that role, give him all permissions, log out of your user 1 and log into your new user. This is because user 1 is often treated as a special case, and works a bit differently from other users. (It is a good practice to not use user 1 too much regardless of whether or not you use a wysiwyg editor).

Now, create a new input format you will associate with your wysiwyg editor. Let's call it 'wysiwyg' and provide any filters you want to it. Make sure the filters are as follows:

• [yes] HTML comments
• [yes] HTML corrector
• [yes] HTML filter
• [yes] Image resize filter
• [no] Line break converter
• [no] Private comments
• [yes] URL filter

Make sure your new format is available to users with the "wysiwyg editor" role.

Save, then click the configure tab. Add "<p> <img>" to the list of allowed tags. This prevents your users from entering tags and so on which break your design (this isn't foolproof, though).

Save, then go back to the Input Formats page at admin/settings/filters. Go to the defaults page. Make sure the order of roles in the nodes and blocks groups start with editor (this is because the system checks all roles and stops as soon as a match is found). Now, set the default input format for editor to "wysiwyg". Other roles won't use the wysiwyg editor.

Save.

Now, we'll download fckeditor itself (change the following for the latest version of fckeditor if the version has changed).

Note: download FCKEditor into the site directory (located at sites/mediatribe.net or sites/whatever.your.site.is.com) because we'll need a separate FCKeditor for each site in a multisite environment. This is because FCKEditor defines where uploaded files should go, and we don't want all files in a multisite environment to go to the same place.

Now we're going to create a profile for wysiwyg:

• Go to admin/settings/wysiwyg/profile
• Next to wysiwyg, select FCKEditor and save
• Click "edit"
• Under buttons and plugins, select Bold, Italic, Align Left, Align Right, Align Center, Source Code, Link, Table, teaser break, bullet list, numbered list (or any other combination you like -- but don't select "image" because we will use another implementation for images).
• Under CSS, select "Editor Default CSS". This is because "Theme CSS" doesn't work with themes which define a background color or image. (There are other issues with themes that define a dark background, though; so if you are experiencing theme-related problems, just choose Garland as an administration theme and check the "use administration theme for editing" checkbox.)

Go to the "create page" page (node/add/page) and make sure you see the editor. (We're still far from done, but if you don't see the editor go through all the steps above and make sure you didn't skip anything).

Now, we're going to download the latest version of wysiwyg_imageupload and jquery_ui_dialog. Drush is a bit finicky with these, so you might have to include the latest version in your drush command:

These require jquery_ui and jquery_update 6.x-2.x or above (so make sure you download the right version):

We now need to modify jquery_ui a bit for it to work. This raises the question of what happens during security updates. Because we will be making a few changes to modules during this installation, it is a good idea to create a UPDATE_INSTRUCTIONS.txt document at the root of your Drupal installation as well as a patches_and_modifications directory, as a courtesy to the next person to perform security updates on your Drupal installation.

Just enter "Additional instructions for applying security updates to this Drupal installation" and save it. We'll add instructions there in a minute.

Let's download the latest version of jquery_ui 1.7. It is very important that it be version 1.7, or else our image upload system won't work. Here is an example with 1.7.2 (you might want to change the version if a later version is available):

Now add to UPDATE_INSTRUCTIONS.txt the following point:

When updating jquery-ui, move to the root of your drupal installation and:

cp -r patches_and_modifications/jquery_ui/jquery.ui sites/all/modules/jquery_ui/

Perform that command now:

We now need to move some files from jquery_update to core (this is known as "killing kittens"):

Add to UPDATE_INSTRUCTIONS.txt:

When updating core, move to the root of your drupal installation and:

/bin/cp sites/all/modules/jquery_update/replace/*.js misc/

You will now perform that command yourself (use /bin/cp rather than cp in order to force your system to overwrite the existing files):

Now, enable some modules (for some reason I have to do this twice with the current HEAD version of drush to not get any errors):

Now, give your editor or super-administrator (depending on which role you are using to perform the installation) all permissions in admin/user/permissions.

OK, now we are going to create some presets for wysiwyg in imagecache: Go to admin/build/imagecache/add and create a preset called wysiwyg_Small_100 with a width of 100. Repeat the process with wysiwyg_Medium_200 and wysiwyg_Large_350, as well as wysiwyg_Original (no action).

Now, go to admin/settings/wysiwyg/profile and edit your profile for wysiwyg, and check the checkbox for Image uploading.

We will need to apply a patch for this (and the Drupal-break) functionality to webkit browsers such as Chrome and Safari.

Add to UPDATE_INSTRUCTIONS.txt:

For each patch, do the following: the patch should contain the affected module name as well as an URL or a number. If it's a number, it corresponds to http://drupal.org/project/[put number here]. When the module (or core) is updated, check the URL or patch page and determine whether you should apply the patch. If so, apply it like so (example given with a wysiwyg patch):

cd sites/all/modules/wysiwyg
patch -p0 < ../../../../patches_and_modifications/wysiwyg-commands-497654.patch

It is important that the patch apply, even with fuzz. If not, you might be breaking some of your site's functionality and you might want to revert to the previous version of your site.

You will now patch wysiwyg as described above:

Clear your browser's cache and Drupal's cache, and the upload function should work in Safari and other webkit browsers.

We now will make a wysiwyg editor work with the mission statement and contact form intro (which don't use input formats). For this we need to download FCKeditor library inside the fckeditor module. While it is tempting to put the fckeditor library in sites/mediatribe.net/libraries and create a symlink, this doesn't work because FCKEditor module expects FCKLibrary to inside the module folder. If not, it will work but give you an ugly error message in admin/reports/status:

Add the above code to your UPDATE_INSTRUCTIONS.txt file under the section "updating fckeditor script in fckeditor module (not in sites/mediatribe.net/libraries)"

Now go to admin/settings/fckeditor/editg (make sure you have the right permissions if you see "access denied"), set visibility settings to "include", erase everything in all text fields, and include the elements admin/build/contact/settings.edit-contact-form-information and admin/settings/site-information.edit-site-mission

Save.

Now edit the default profile, in basic setup, check the "editor" role. In the style and template section, choose "editor default" so it's compatible with themes with dark backgrounds. Under "file browser settings" select yes on "allow quick uploads".

Now remove the administer FCKEditor permission from your editor role so you won't see the "The ID for excluding or including this element" message below each field.

We still need to add some patches to FCKEditor and wysiwyg module for this to work. The patches are available here:

• FCKEditor Library patch
• FCKEditor Library within module patch
• wysiwyg patch

We'll need to execute the following (UPDATE_INSTRUCTIONS.txt already tells updators to refer to patches so we don't need to update that). Note that your system will probably ask you which file you want to patch, just find the corresponding path.

Now, uncomment the cookie domain in settings.php and put your domain name there:

...edit your cookie domain...

People who use a wysiwyg editor will invariably put in an image aligned left (or float left), and some text next to it which has a smaller height than the image. This will cause the rest of the content on the page to move next to the image. To prevent this, we will need to add some CSS. If you are using a custom theme, you can do it in there, or you can use the css_injector module if you don't want to modify your theme.

Give your user permission to use css_injector, then head over to admin/settings/css_injector and add a new rule. In it, add the following (this might change on which modules you're using and the active theme -- the idea is that whatever class encloses content generated with the wysiwyg editor must be float left width 100%). Also, most people won't be satisfied with the default margin to the left of right of the images, so increase that:

Finally, make sure your editor user has the permission to use "wysiwyg image upload."

Now let's flush Drupal's caches, run cron and flush your browser's cache.

It should work!

My UPDATE_INSTRUCTIONS.txt file looks like:

(To do: allow entering HTML (youtube embedded), and paypal.)