20 Taming WordPress smilies

The emoticons used by WordPress can be a rowdy bunch. Read this to learn how to replace them with your own smilies, and, most important, how to control the way they behave and look.

Note: This tutorial applies to both WordPress 1.5.x and 2.x. I haven’t tried older series so I don’t know if any of this applies.

1. Introduction

So, what’s the problem with smilies? First of all, you may not like how they look and/or what codes they respond to. Perhaps, like me, you’d like some emoticons that integrate better with the colors on your blog, or you’d like to be able to use :lol: instead of :mrgreen: (Who is Mr. Green, anyway? :confused:)

Furthermore, if you’re using a plugin such as my Smiley JS Buttons 8), and if you have more than one code for the same smiley, it’s pretty hard to guess which one will actually be used when you click the smiley button. They seem to use a logic all of their own.

2. Explanations for experts

This is a small run-through for the more advanced WP users. If you’re a PHP (and WP) veteran, the pointers below are all you need. If you’re an amateur, you’d better jump straight to the examples, below.

2.1. The WP source code

The good news is that there’s only one file that needs to be modified, and that the modifications are rather simple. It’s wp-config.php, which can be found at the root of your blog.

Even better news: this file holds special blog configuration which doesn’t change when you upgrade WP, so it will never be overwritten when you upgrade WP.

The correspondence between emoticon codes and actual smiley images is done with an array, $wpsmiliestrans, which has a default defined in wp-includes/vars.php (wp-includes/functions.php in later versions in the 2.x series). The array has codes as keys and image file names (without the path) as values.

There’s also a function, smiliescmp($a, $b), which is applied to this array via uksort().

Although not widely known, WP versions 1.5.x and 2.x already expect and allow you to define both the function and the array in wp-config.php, thus imposing whatever you want on it. That’s all the trick, really: define them there, between the following two lines:

define('ABSPATH', dirname(__FILE__).'/');
require_once(ABSPATH.'wp-settings.php');

2.2. The smiley images

The images are held under wp-images/smilies/ (in WP 1.5.x) or under wp-includes/images/smilies/ (under WP 2.x).

Unfortunately, this path cannot be easily changed, as it is used hardcoded in several places (not counting plugins). This means that if you want to change the default set you will have to rename or delete the directory and replace it with a new smilies/ dir with the new images. You can also replace the images directly with other ones.

Caution: Don’t forget to backup the original smilies!

3. Actual examples (for everybody)

3.1. Just changing the default images

You don’t need to mess with wp-config.php if you just want the images to look different. Get new images and overwrite the default ones in wp-images/smilies/ (for WP 1.5.x) or in wp-includes/images/smilies/ (for WP 2.x). That’s all.

Be careful what images you choose. If you use images that are too big, they will produce gaps between the lines of your text. If they are too small, people will have trouble understanding what they mean. Also try to pick some images that can be recognized easily. The default images may be a bit on the ugly side, but at least they are small and easily recognizable.

3.2. Changing both the images and the codes

This second example is a bit more complex, but it will let you do more things with the smilies.

Suppose you’ve just downloaded a set of Becca’s smilies. Their names differ quite a bit from those in the default WP set. Plus, you want to assign them more sensible codes, but also keep some of the most widely used. Also, it wouldn’t hurt if you could control what codes are produced when you use my Smiley JS Buttons.

You probably already know what to do with the images: backup the original wp-images/smilies/ (for WP 1.5.x) or wp-includes/images/smilies/ (for WP 2.x), and put the new images in there. That’s it as far as they are concerned.

Now, edit wp-config.php. Locate the following two lines (should be easy enough, it’s a small file):

define('ABSPATH', dirname(__FILE__).'/');
require_once(ABSPATH.'wp-settings.php');

You have to go between them and add something like this:

function smiliescmp($a, $b) {
  if ($a == $b) return 0;
  global $wpsmiliestrans;
  static $keys;
  if (!$keys) $keys = array_keys($wpsmiliestrans);
  $x = array_search($a, $keys);
  $y = array_search($b, $keys);
  return ($x < $y ? -1 : 1);
}

$wpsmiliestrans = array(
  ':mrgreen:' => 'biggrin.gif',
  ':biggrin:' => 'biggrin.gif',
  ':lol:' => 'biggrin.gif',
  ':blank:' => 'blank.gif',
  ' :|' => 'blank.gif',
  ' :-|' => 'blank.gif',
  ':neutral:' => 'blank.gif',
  ':oops:' => 'blush.gif',
  ':blush:' => 'blush.gif',
  ':bored:' => 'bored.gif',
  ' @.@' => 'confused.gif',
  ':confused:' => 'confused.gif',
  ' 8)' => 'cool.gif',
  ':cool:' => 'cool.gif',
  ' >:)' => 'evil.gif',
  ':evil:' => 'evil.gif',
  ' :(' => 'frown.gif',
  ':sad:' => 'frown.gif',
  ' :D' => 'grin.gif',
  ' :-D' => 'grin.gif',
  ':grin:' => 'grin.gif',
  ':grr:' => 'grr.gif',
  ':laidback:' => 'laidback.gif',
  ':left:' => 'left.gif',
  ':mad:' => 'mad.gif',
  ':right:' => 'right.gif',
  ' :~(' => 'sad.gif',
  ':cry:' => 'sad.gif',
  ':secret:' => 'secret.gif',
  ' 8O' => 'shock.gif',
  ':shock:' => 'shock.gif',
  ' :)' => 'smile.gif',
  ':smile:' => 'smile.gif',
  ' :-)' => 'smile.gif',
  ':stress:' => 'stress.gif',
  ' :P' => 'tongue.gif',
  ':tongue:' => 'tongue.gif',
  ':roll:' => 'up.gif',
  ':up:' => 'up.gif',
  ' ;)' => 'wink.gif',
  ':wink:' => 'wink.gif',
  ' ;-)' => 'wink.gif',
  ' :O' => 'yawn.gif',
  ' :-O' => 'yawn.gif',
  ':yawn:' => 'yawn.gif',
);

Some explanations are probably in order. :) There are two parts in the example above.

First, we have a part which defines a function called smiliescmp(). You don’t need to worry about that. If you really have to know, it will be used later to sort the array below. We’re rigging it so that it leaves the codes in the same order.

The array is what you really care about. It contains pairs formed with emoticon codes and actual images. Basically, it says “if this code is found, replace with this image”. The images are taken from the well known directory, of course.

As you can see, you can give the image files whatever names you want, as long as you tell WP what they are. Even better, you can define many different codes for the same image.

So now you can get crazy, hack and slash the thing and put anything you want in there. That’s it.

4. Some words of warning

4.1. Choose your codes carefully

First, think carefully about what codes you choose. Those codes will be used both by you, in the posts, and by other people, in the comments. Once people use some codes, they are put in the body of either the posts or the comments and that’s it.

If someone enters :haha: and it transforms into :lol:, that’s very nice. But if you later change the smiley array and :haha: is no longer a valid code, you’ll be left with just the code showing in the text. So pick your codes early, and choose them well, and later you can change just the images without headaches.

Secondly, you should also leave in some of the most common codes, those that people have come to expect, such as smile, sad, cool, grin, wink, blank, cry, tongue; you know them. Many people will use them by reflex, because that’s what they use all the time in email and chats.

Thirdly, mind those extra spaces in front of the “classical” codes. You may notice that they have an extra space in my example. That’s a good idea, because it’s very easy to have, for instance, an 8 (eight) next to a round bracket “)” and make a “cool” face when you actually just wanted to put a number between brackets.

4.2. Using Smiley JS Buttons

If you use this plugin, there’s an extra precaution you must take. The plugin can only use one of the codes, if there are more than one for the same image. It will always use the last one, as they appear in the array above. So take care to arrange them properly and to test what comes out when you click the smiley buttons.

Note: the general order doesn’t matter. What matters is just the relative order of the codes that produce the same image. If you know PHP, the explanation is simple: the plugin uses array_flip(), which overrides the code each time it comes across an image again, thus leaving only the most recent one in the end.

5. I’ve messed up! I want the default back!

Oh, alright. Here’s what you have to do:

1. Edit wp-config.php. Locate the following two lines and delete everything you’ve added between them. Save it and put it back on the server.

   define('ABSPATH', dirname(__FILE__).'/');
   ...
   require_once(ABSPATH.'wp-settings.php');

2. Put the default images back in wp-images/smilies/ (for WP 1.5.x) or in wp-includes/images/smilies/ (for WP 2.x). You did make a backup, right? If you didn’t, no biggie (but make one next time): just download a fresh WordPress package and get them from it.

That’s it. Once you have the config file with the modifications undone and the original smilies back, WP will behave just like in the beginning. You can now start messing with it all over again! :)

6. Tips and tricks

6.1. Vertical alignment for smilies

This is actually useful for all small images that you have throughout the site, such as RSS icons, not just smilies. You may have noticed that sometimes they appear misaligned vertically, usually too high compared to the writing around them.

The fix is a simple CSS statement, which should go into your style.css:

img {
  vertical-align: middle;
}

However, you may need to tweak it a bit. It may affect other images that you don’t want it to if you add the statement as is. Depending on the situation, you may wish to limit its scope to only certain zones on the page. One example would be just the sidebar, or just the content, or just the comments. How exactly to accomplish this depends on what identifiers those page parts are using. An example:

div#sidebar img {
  vertical-align: middle;
}

…which states that only images inside the <div> with id="sidebar" should be affected.

You can also try adding !important after middle (separate them with a space) to prevent other CSS rules from overiding this one. YMMV.