For beginning Drupal developers, zombification threats include hooks, render arrays, and the entities-bundles-types-instances maze. And the tax code. A-r--g---h! M-o-r-e b-r-a-i-n-s!

Users have different threats. For most, HTML reeks of zombie juice. You can't expect users to type HTML to create content. You need to give them something easier. GUI is the answer.

Lest you feel too superior, remember this: some of those users understand the tax code. At least better than you.

The goal

You can see this widget in the comments section at the bottom of this page:

Figure 1. GUI editor

This is CKEditor, glued into Drupal by the WYSIWYG module. The WYSIWYG module is the brainchild of Dan Kudwien, aka sun, a prolific Drupal contributor.

The WYSIWYG module (stands for "what you see is what you get") lets you use many different editors. CKEditor is just one of them.

Except for the width, Figure 1 is the way CKEditor looks when it's first displayed on this site. But that's not the way it normally shows. There are two differences:

• The widget is about a third of the regular height.
• SCAYT is enabled. That means "spell check as you type." Normally, the user has to turn it on manually, but here, it's already turned on by default.

Starting out this way makes things a little easier for users.

So, that's out goal. Change the way CKEditor is configured by default. When a comment widget is first shown, it will be short, and SCAYT will be on.

Hooking

We need to get the WYSIWYG module to run some code. Here's what the WYSIWYG module does, kind of:

Figure 2. WYSIWYG module showing CKEditor

The WYSIWYG module grabs the code (HTML, JavaScript, CSS) for the right editor. How does it know which editor to use? You told it which one, when you were configuring the module:

Figure 3. Telling the WYSIWYG module which editor to use

To change things, we need to interrupt the normal configuration, and add our own:

Figure 4. Adding custom code

How to add our code? We can't just throw it into the WYSIWYG module. Well, we could, but that's grounds for a Severe Spanking from the Super Friends.

Instead, we use a hook. A hook is a place we can hang our own code. The WYSIWYG module defines a number of hooks. When it runs, the module looks to see if any modules have hung code at the hooks. If there's code hanging there, the module will run it.

Figure 5. WYSIWYG module checks hooks

Note that we don't get to choose where the hooks are. The humans who wrote the WYSIWYG module chose where to put the hooks. Suppose they wrote code like this (they didn't, but let's pretend):

1. Initialize something.
2. run_hook('init');
3. Process something.
4. Process even more.
5. Process yet some more.
6. run_hook('after_everything');

Figure 6. Code-like substance

If we wanted to run our own code after initialization, we would create a module, and add a PHP function called HOOK_init. We'd replace HOOK with the name of our module. So, if our module was named dog, we'd name the function dog_init.

What if we wanted to run some code after the WYSIWYG module had done its work? We'd create a function named dog_after_everything.

What if we wanted to run some code after Process something and before Process even more? We can't. Without risking a Super Spanking. But we could add an issue to the WYSIWYG module's issue queue, requesting someone to add a hook call at that point. Or change the WYSIWYG module's code ourselves, and submit a patch.

The WYSIWYG module's writers didn't really create HOOK_init or hook_after_everything. They're bad names for hooks, anyway. They did create a hook called HOOK_wysiwyg_editor_settings_alter. The WYSIWYG module looks for code for that hook after it's done configuring the editor:

Figure 7. Calling our code

To add our own code, we create a function with the right name, and the WYSIWYG module will call it. When our code has done its groovy thing, the WYSIWYG module will resume where it left off.

Our code needs access to the data it is going to change, that is, the configuration settings for the editor. How that is done varies across modules and hooks, depending on what makes sense in the situation. Here's the function signature for the hook we care about:

function hook_wysiwyg_editor_settings_alter(&$settings, $context)

This is from wysiwyg.api.php, a file that's part of the WYSIWYG module. $settings is an array containing (you guessed it) the settings for the editor. This is what we change. The & in front of the name means that the array is "passed by reference." Huh? It means that if our code changes $settings, those changes will be passed back to the WYSIWYG module, which will use the new $settings.

The parameter $context tells us, among other things, which editor we are configuring. Could be CKEditor, or something else.

There is no way to know what $settings and $context mean without looking at the documentation. Or finding an example, and copying it.

Coding

Speaking of copying, that's what I did to get started. The post at http://drupal.org/node/1012050 has code for setting the height of the editor. This code is from the user TwoD, whose zombie name is Henrik Danielsson:

1. <?php
2. function MYMODLENAME_wysiwyg_editor_settings_alter(&$settings, $context) {
3.   if ($context['profile']->editor == 'ckeditor') {
4.     $settings['height'] = 500;
5.    }
6. }
7. ?>

Line 4 shows how to change CKEditor's configuration. Line 3 makes the change only if we're working with CKEditor. Each editor has its own configuration.

What about SCAYT? A CKEditor forum post had this:

config.scayt_autoStartup = true;

This is JavaScript. What about our code? I figured this was a good bet:

$settings['scayt_autoStartup'] = TRUE;

I tried it, and it worked!

The final module

OK, let's package the code into a module. Called Dog. A good name? No, it's a bad name for this module. But I love dogs, and dogs never turn into zombies. You can call your module whatever you want. Like Configure CKEditor, or Madeleine Albright.

First, let's create a directory for the module. Let's make /sites/all/modules/custom/dog/.

The module has two files:

• dog.info: has data about the module, like its name.
• dog.module: our code.

Here's the .info file:

1. name = Dog
2. description = Changes to CKEditor's default configuration.
3. core = 7.x
4. files[] = dog.module
5. hidden = FALSE
6. package = Custom

Figure 8. The .info file

Line 3 says that this is for D7. Line 4 lists the files that make up the module (other than .info). There's only one: the code. Line 6 is the section the module appears in on the module list at Admin > Modules > List.

Here's dog.module:

1. <?php
2. //Change initialization settings for CKEditor.
3. //  Set the height of the editor smaller.
4. //    See http://drupal.org/node/1012050
5. //  Turn on SCAYT.
6. //    See http://cksource.com/forums/viewtopic.php?f=11&t=17091
7. function dog_wysiwyg_editor_settings_alter(&$settings, $context) {
8.   if ($context['profile']->editor == 'ckeditor') {
9.     $settings['height'] = 200;
10.     $settings['scayt_autoStartup'] = TRUE;
11.   }
12. }

Figure 9. The code

Why 200 (line 9)? I just tried different values until it seemed right.

Notice that the <?php tag in line 1 is not closed. That's standard practice.

Now we just enable the Dog module, and Bob's your uncle.

That's all, folks

Our goal was to improve the usability of the comment widget, by (1) sizing the area, and (2) turning on SCAYT. That meant changing the way the WYSIWYG module configured CKEditor. We used a hook the developers of the WYSIWYG module created. How to make sure our code was called? By making a function with the right name.

The code itself was adapted from forum posts. All hail forums! Bubbling fonts of Wise Guidance.

Finally, we put the code into a module. The module has two files. One to describe the module to Drupal, the other containing the code.