Adam Gregory

In this series I am going to explore the Drupal Theme System: how it works, how to override core functions, common hacks and code snippets, and how to build your Drupal site exactly how you want it.

The Drupal theme system can seem very daunting when you fist start using Drupal. Most new drupalers think that the theme system starts and ends with Themes, i.e. Garland, Pushbutton, etc., when in fact the theme system extends far beyond that. Themes are just the tip of the iceberg and the core theme system is much more powerful then you see in the core Themes.

To get an idea of what the core theme system is you need to start with the theme() functions. You may have seen this function called through Drupal modules and themes and wondered how it works, so I'll explain. The theme() function is what commonly called a magic function, meaning it magically calls another function. Basically when you see:

What is really happening is:

Now why would we use the theme() function to do this if we could just call theme_username() on our own? Here is where the beauty of the Drupal Theme system lies. I'll explain why in a moment, but for now let's stop and think about designing a Theme first.

Imagine you are a highly skilled Web Designer(I know hard to imagine right). You have toiled away in Photoshop for weeks, really it was only days, but you charged the client for weeks ;). You've created a masterpiece that is worthy of it's own place in the Louvre, but you hand it over to the Web Developer only to see it get hacked up into his CMS of choice and all the little touches you put on it get mangled up when he tells you, "Sorry, that's the way the system outputs the HTML/CSS. There's nothing I can do about that." You grumble under you breath and walk away convinced that CMS's are the devil and destroy beautiful designs with their bulky and ugly code. You one day vow to find a CMS that will let you control the output of ALL (or at least most) of the code. You don't have to imagine anymore. Drupal is built to allow you to override the core output of anything that is ran through the theme() function.

Here is how it works. (See, I told you I'd explain didn't I?) If in the example above Drupal simply made a call to theme_username() then when it outputs the code it will simply output whatever code was coded into theme_username(). But Drupal doesn't call theme_username() it calls theme() passing it the name of the function it wants to call, in this case username. What happens now is that whole magic thing I mentioned earlier. The theme() function looks for modules or themes that override theme_username with their own implementation.

For example lets say theme_username() looks like the following (It doesn't in case you are wondering):

And you being the CSS guru that you are take one look at that and want to vomit. (I know tables are gross) Well here how you fix it. You have your theme called mytheme so in your theme, we'll talk about specifics of how to do this in a later post, you create the following:

Now when theme('username',$user) is called it first looks for your override. Upon finding it it calls your implementation of theme_username() rather then the core function which allows you to control your code and make beautiful websites.

I hope that this is a good start to help you understand the Drupal Theme system. In the next post well discuss the specifics of how and where to override core theme functions and what you can override.