New Drupal theming ebook

I’m currently working on a Drupal 6 theming ebook. The beta ebook attached to this posting is for Drupal 5.
Update, March 29th, 2008.

I am in the process of writing a 50-and-some pages ebook on Drupal theming. I have an outline and a spiral book full of notes, and lots of sections are already written. My current draft (call that a beta-book) is 15 pages long and if you log in you may download it. I work slowly when it comes to writing. I would absolutely love that ebook to be ready by next week the end of the month year next year. It’ll be available in a PDF format, and as per my current outline, it should be 50 pages long — but as per my experience, it should be twice as long in the end (my biggest challenge when documenting anything is to be concise). Say, it will be 60 pages long.

Fortunately, the book will be searchable and have a TOC. However, it won’t have an index : indexing in InDesign is quite a task, as one cannot possibly automate the creation of a good index. The ebook will be illustrated. Attached is the cover of the book with its Table of content.

I need your help. I need questions. Send them by e-mail, private messages, or add them as comments to this topic. I have tried to find as many good questions as I could in Drupal’s forums, but I need more. I need hard questions. There’s already decent documentation on theming. I am motivated to write my own because I believe I’ll have a very personal and interesting spin on the whole subject.


Current TOC

  1. Absolute minimal requirements for a theme, page 2
  2. Themeable or themable ? page 3
  3. What is a themeable function and The Trick, page 3
  4. Template files you don’t need to tell Drupal about, page 5
  5. Template files you need to tell Drupal about, page 7
  6. When not to use template files, page 8
  7. PHP code style in template files, page 9
  8. Anatomy of a page[-something].tpl.php file, page 10
  9. Anatomy of a node[-something].tpl.php file, page 15
  10. What does a page[-something].tpl.php file know, page 18
  11. What does a node[-something].tpl.php file know, page 20
  12. How does one make a *.tpl.php file more knowledgeable, page 22
  13. Theming a 'view', page 22
  14. CCK — what the hell is happening, page 25
  15. Theming precedence — the rules, page 26
  16. Adding regions — semantic or not, page 27
  17. Good design — proximity and strong alignment, page 29
  18. Browser-side theming : style.css, page 32
  19. Printer-friendly all the way, page 40
  20. Styling using jquery, page 42
  21. All about menus, page 46
  22. Theming the node form, page 49

April 12th update : Please do not post links to any web site on this page. I am giving a lot of my time — and some of my money (to buy all the fonts used on this web site and in the PDF documents, for instance) — to help people. I am helping people out my own free will, and it’s a pleasure for me. But I won’t offer free advertisement. Please, do not showcase your web site. In your own profile, you can put a link to your business or blog, so that people can look you up. Don’t treat me like a 10 dollar whore. I’m sorry that you had to read this, it’s extremely unlikely that this concerns you, at all.

AttachmentSizeHitsLast download
themingDrupal.pdf83.5 KB116910 years 41 weeks ago
themingDrupal_April18th.pdf436.53 KB176710 years 41 weeks ago
Last edited by Caroline Schnapp about 12 years ago.

Because you are not logged in, you cannot see the 2 files attached to this posting. Login or register to download these files.


Themeing ebook

Themeing, doesn't that word just look wrong?
Your Drupal ebook post led me here and I am looking forward to reading it having just started a Drupal based blog myself.
Congratulations on a great looking site, maybe I will be able to do something equally as pleasing when I've read your book!

Techjournal - The Random Blabberings of an IT Manager

It looks very wrong indeed

Themeing, doesn't that word just look wrong?

It was settled for me this morning while searching through a few books about blogging. Apress editors cannot go wrong, well they can. Theming it will be, will be. As in Drupal has a "theming engine". uses themeable as in a "themeable function" a lot; and many do use the same spelling elsewhere. However, Apress uses "themable". It’s confusing. But no big deal, assurément.

In Modern English

In Modern English any Noun can be used as verb, eg: 'penning'

I need your help. I need

I need your help. I need questions. Send them by e-mail, private messages, or add them as comments to this topic. I have tried to find as many good questions as I could in Drupal’s forums, but I need more. I need hard questions. There’s already decent documentation on theming. I am motivated to write my own because I believe I’ll have a very personal and interesting spin on the whole subject.


I think it stinks registration is required to download this book. It would make a lot more sense to require login to post. Oh-well... -Drue

Hello, I have browsed most

Hello, I have browsed most of your posts. This post is probably where I got the most useful information for my research. Thanks for posting, maybe we can see more on this. Are you aware of any other websites on this subject.
buy perfect tortilla reviews

Positive site, where did u

Positive site, where did u come up with the information on this posting?I have read a few of the articles on your website now, and I really like your style. Thanks a million and please keep up the effective work.


That is great that you're taking the time to do this. It is very much appreciated. Will there be any content about themeing with Views?

How can I forget Views?

Will there be any content about themeing with Views?

Views is the module. I will cover that too. I will cover how to theme a particular page view (with a list of nodes, or list of comments...).

Looking forward to it.

Looking forward to it.

"I would absolutely love that e-book to be ready by next week."

Ooooh! Me too! Me too! Really looking forward to this.

The TOC looks very thorough. I'm particularly interested in finding out the minimum requirements for a template, as I'm concerned that by hacking existing templates I'm keeping a lot of stuff in that I don't need.

All the best with it :)



I'm particularly interested in finding out the minimum requirements for a template, as I'm concerned that by hacking existing templates I'm keeping a lot of stuff in that I don't need.

My mouse is defective now and it makes it so hard to get work done in InDesign. I have to make 5 different attempts at selecting text on screen before it gets selected, and oftimes I create text areas just with a click (the mouse captures a drag). And then I have to delete these text areas that I never intended to create... by selecting the frikin shit, which is hard. It is driving me crazy. I have to buy a new mouse. Shit.

Back to theming. I have attached my current draft that explains the basic requirements for a theme to "exist". There are 2 aspects to what's minimal I guess : the minimal requirements as far as the PHPTemplate engine goes (that's covered in my current draft), and the minimal requirements that you will have to determine by yourself for your theme as far as WHAT you want to show.

To determine what's minimal for yourself you need pen and paper, and probably a long hard look at the Garland theme, which shows it all. For example, do you want a breadcrumb ? Do you really need 4 regions for blocks ? (top, left, right, bottom). Do you want to display a slogan ? Things like that.

Then you have to decide where all this content will go. Again, you need pen and paper. With a grid. Then you need to build a skeleton in XHTML (table or tabless design), then you plug your stuff in. Plugging in your content is VERY easy. The hard part is XHTML, it's layout, i.e. CSS. Which I will cover.

What's your favorite theme-to-tweak that doesn't use a table? I still can't believe that the only theme shipped with Drupal that does not use a table is Garland/Minnelli. It's surreal.

It's the second mouse that gets the cheese...

[responding to "Minimum" (Caroline Schnapp)]

...or so I heard, anyway. Not that that's at all relevant. (webpage on ancient mice on the way, now the kids are back at school, and Dad's back at work ;P )

My definition of minimal would be something like "implements everything that the core drupal install can offer, in a very simple way, with the fewest files and least/cleanest code." It will also rock from the point of accessibility, usability, tidiness and SEO.

So far, I've not found a Drupal theme that really does this for me. But I'm starting to roll out Drupal sites for my living, so I really need there to be one. Hence, a project I'm gonna get on with this week is to create the first draft of a really simple Drupal theme that scratches my itch.

But I mustn't forget about your mouse, either ;)

Theming Question

Hi Caroline,

I'm also looking forward to your ebook, thank you.

I have decided this morning to learn about theming from scratch, so, I made a folder called 'scratch' in sites>all>themes and into this I put an empty text file called page.tpl.php.

As a programmer/designer, the first thing I want to do is make page.tpl.php a "Reference File" that prints a list of all available variables and their values, i.e., $language = 'en'.

Without peeking at other themes' page.tpl.php files, I'd be interested to know what object or array might contain all available variables/arrays/objects? (I'm also just beginning to learn PHP.) So far, I know how to print_r($node), and I'm thinking there's probably some other object to print like this to see all page variables/arrays/objects.

Anyways, that's the question in my mind as a theming beginner and I'm off to the drupal handbook to see what I can hunt down.

Take Care,

Hi Ray

The variables that are made available to page.tpl.php in Drupal 5 are all passed through this function defined in phptemplate.engine :
phptemplate_page($content, $show_blocks = TRUE)

If you take a look at that long function you'll see what I mean.
The $variables are sent to the template through this call :
return _phptemplate_callback('page', $variables, $suggestions);

The $suggestions (and these are new to Drupal 5) allow for the creation and recognition of different page templates. For example, we can create a page-node-44.tpl.php to theme just the page that shows the node 44 in full view (where the page IS the node 44).

Plus you have these variables available to all templates :
$directory which is the value returned by path_to_theme();
$is_front which is the value returned by drupal_is_front_page();

$directory will give you theme/scratch

So you get these variables in page[-something].tpl.php:

[How to invoke from the template] : [where the variable comes from, FYI]

$sidebar_left : theme('blocks', 'left');
$sidebar_right : theme('blocks', 'right');

$base_path : base_path()
$breadcrumb : theme('breadcrumb', drupal_get_breadcrumb())
$closure : theme('closure')
$content : $content
$feed_icons : drupal_get_feeds()
$footer_message : filter_xss_admin(variable_get('site_footer', FALSE)) . "\n" . theme('blocks', 'footer')
$head : drupal_get_html_head()
$head_title : implode(' | ', $head_title)
$help : theme('help')
$language : $GLOBALS['locale']
$logo : theme_get_setting('logo')
$messages : theme('status_messages')
$mission : isset($mission) ? $mission : ''
$primary_links : menu_primary_links()
$search_box : (theme_get_setting('toggle_search') ? drupal_get_form$search_theme_form') : '')
$secondary_links : menu_secondary_links(),
$site_name : (theme_get_setting('toggle_name') ? variable_get('site_name', 'Drupal') : '')
$site_slogan : (theme_get_setting('toggle_slogan') ? variable_get('site_slogan', '') : '')
$css : drupal_add_css()
$styles : drupal_get_css()
$scripts : drupal_get_js()
$tabs : theme('menu_local_tasks')
$title : drupal_get_title()

You get of course the $node if the drupal internal path is node/x. You get this extra bit thanks to these lines of code in the phptemplate.engine phptemplate_page() function :

if ((arg(0) == 'node') && is_numeric(arg(1))) {
$variables['node'] = node_load(arg(1));

For starters

I would check my theme's name :)
Then get some basic information, then some content.

<?php print $directory ?>

<?php if ($is_front) : ?>

This is my front page.

<?php endif; ?>

<?php print $content ?>

I forgot something important :

$layout will be equal to : left, right, both or none... if there are blocks to print in the left sidebar, the right sidebar, both left and right, or in none of them. You can change your layout accordingly, with this information.

You can have something like this :

<?php if ($layout == 'left' || $layout == 'both') : ?>

<?php print $sidebar_left ?>

<?php endif; ?>

Found It!

I found the print_r(get_defined_vars()) suggestion here: Your TOC looks great. I'll probably be using this to learn a lot & will give you good feedback.

Please let me know

I found the print_r(get_defined_vars()) suggestion...

If some other variable is showing up that might be particularly interesting to the page (the template page that is), let me know :)

Searching a best online

Searching a best online casino network is not a difficult task in these due to top class social networking websites and SEO, but finding a premium website to enjoy a bit then you have to do some work hierher for that , like you have to read good content related to casinos and also visits sites where you can get your desired games. That's the best thing which i believe on. Hope this will also work for you.

So cool

Caroline you rock! Since I'm just learning PHP it's a blast to actually 'get' most of what you've written. Reminds me of the time I was in Italy and a dinner table conversation slowly morphed from sound into language. I'm very thorough and methodical when it comes to learning stuff so I'll certainly check back in later... Take Care, Ray

I just uploaded an updated draft

Thank you so much for the encouragement, Ray. :)

It will be a long book

I still have to add 2 pages to Exercise 3 before I get to the trivial and humoristic "themeable or themable" and then dive into "What is a themeable function".

Theming e-book

Hi Caroline,
I'm very much looking forward to the completion of this e-book (in your own time of course).
There is definitely much need for such material.
From what I saw in the pdf previews, it'll look really great. And it's probably going to be long, too, as I read in one of the comments.
Congratulations on this great initiative !

Great stuff

This is looking very good, Caroline. Maybe something that we could do some short run printing of as well? I'd love to help promote this more widely. Well, I did add you to Planet Drupal, so that should send some more folks wandering over... :P

Thank you Boris Mann

For adding me to the Planet Drupal list.

A short run printing may not be such a swell idea. I have an uncle that has liberal access to equipment to print magazines. Even if it wouldn’t cost so much to print this book, that is, even if I was allowed to print almost at cost price, it would still be expansive to ship the book. I am not sure that people are willing to pay for that.

I do have a fetish for the printed book. But that’s me. I love to hold books in my hands, and love their chemical scent lol... And I love to read from them, of course.

I make sure that the document prints well with laser printers. I don’t use CMYK black just for that reason, I use RGB black. And these days, it is easy to convert RGB to CMYK at the print “shop”, unlike a couple of years ago. So the document is regular-laser-printer-friendly, while not print-shop-unfriendly.

I am scrapbooking design ideas for a theme tonight, so I have not done much work on the book itself. Tomorrow is still a holiday, I intend on updating the book tomorrow with at least 4-5 other pages.

Thank you for your kind encouragement. Long live bryght DOT com.

Grander ideas

OK, OK, I admit it. I had some grander ideas than you just selling the printed book directly. I think this is something that would go great with theming tutorials, and might be a nice hand-out at the Drupalcon Barcelona this September. With compensation to you, of course.

We can talk more once you've finished :P 

Use POD...

... (Print On Demand) and you will not have to put a penny in advance. If people wish to have it in a paper book they will gladly pay for it.

Check it at:

About it
A few considerations
A blog on Self Publishing

A supplier
Another one

Best and thanks.

Oh I see

[In response to Boris Mann]
Seems like a very good idea for the book to be handed out in that context, indeed.

thank you

Appreciate your effort. I have no problems tweaking CSS but theming-functions are still a head scratcher. I hope you will make me see The Light…

Great work

I'm having a glance at the pdf and it looks great. I've just started working with drupal, and I think this book is perfect for starters: nice structure, easy reading and good content.
I can't wait for the whole book get finished :-D

Thank you for helping the community.

Greetings from Spain


Gracias infinitamente, sus palabras son muy alentadoras.

Good work!

Thanks a lot for the pdf!

Hope to meet you here in Barcelona for the drupalcon.

Thank you!

O this is really nice article! It will help my to create my ULTIMATE theme ;)

My God

I was just freaking out at Drupal for having terrible documentation and was about to start out on a project to learn the damn thing inside out and write a decent tutorial that isn't a> abstract as hell with lots of theory and code out of nowhere or b> code snippets. More along the lines of "How to think in Drupal".

Oh how I do wish your book was available now now now! I'm actually really needing it right now. It still astounds me that the community is so big, yet the gap between Drupal Ninja (usually a developer of some sort) and absolute Newbie is SO WIDE and the inbetween almost doesn't exist?!

Anyways, looking forward to it! Good luck!

Is it really all that bad?

Hey Hapworth :)

I've been really impressed by the Drupal documentation so far. But then my previous CMS hacking experience was with Mambo, so perhaps therein lies the secret ;)

After a day's study...

I've just managed to digest the existing draft preview. It's looking really good, and has already been a great help.

Take it easy :)

A side effect of "The Trick"

I thought it would be worth posting this small warning about "The Trick" you talk about in the book - where you hack includes/ so that HTML comments are inserted in your pages to highlight the various themeable functions.

This hack will cause an HTML comment to be inserted before the DocType statement - something that will kick Internet Explorer 6 out of "Standards Compliant Mode" (know your oxymorons!) into "Quirks Mode".

You really don't want to debug CSS in Internet Explorer while it's in Quirks Mode! I lost a lot of time yesterday figuring out why IE was even more buggy than normal :D

So it might be worth putting a note in the book to warn people to return includes/ to its original state before they do any CSS development with Internet Explorer.


Thank you!! :-)

(There is comment added with BEGIN_phptemplate_page... something like that...)

I think I will just modify the code as not to insert the 'phptemplate_page' comment... with the note!

Cheers :)

Internet Explorer, huh?! Ya gotta love it :S

Hello, looks like a great

Hello, looks like a great initiative, but how to get access to the draft? I registered, but can not login afterwards. Is there a secret handshake I don't know about? :-)

I have been neglecting

Is there a secret handshake I don't know about? :-)

I'll take care of this in a moment... sorry! :-)


Looks like a wonderful start that will fill a large gap. I bought Pro Drupal Develpment and found it all over my head. I was afraid of buying Drupal: Creating Blogs, Forums, Portals, And Community Websites as reviewers posted it was simply a rehash of material available online.

The preview of Theming Drupal is luring me in a little deeper. Difficult enough to keep me motivated and written in relatively plain English considering the topic.


Good stuff!

Hey Caroline...this is excellent! When can we expect the final documentation?

can't log in

Tried to register to download the guide, but after registering, my user account hasn't been activated. (It's now about a week later). Can you help please?

Thank you!

This is exactly what I was looking for. I am looking forward to reading it this weekend.

All eyes are on you Carol

Hello Carol,
All eyes are on you concerning the new Theming E-Book.
I waonder how you are able to sleep with the this whirl-wind of anxiety from the
small world of Drupallers.
It is ain't a holiday yet: We all love you and your posts especially your sleepless dedication of an evangelist.
Can't wait to see the book.

unable to login

please enable the accounts

Will do

Sorry about neglecting that.

Cannot log in

Hi, i registered, but i cannot log in. Can YOu help me?
Best Regards - chris

Account activation

I can't seem to log in. Can somebody please activate my account? Thanks!

Account is not activated yet

Would you please activate my account.


Your accounts have been activated

Sorry for the delay in making it happen.

I registered a few minutes

I registered a few minutes ago but I can't login. Would you please activate the account? thanks,


Your account has been approved

... have fun

Thank you for this!

I've used Drupal for several years, but have resisted the urge to build a theme from scratch - until now. Thank you for the effort, and for sharing this!

Activate my account

I got the password just few min.before.but i couldn't able to activate the account.would you please activate my account...............

activate the account

I registered a few minutes ago but I can't login. Would you please activate the account? thanks,



Looking forward to reading your ebook on theming!

Thanks a lot


great work

thank! your work is great for me!
i waiting for full your ebook

Account log-in

I registered a few minutes ago but I can't login. Would you please activate the account? thanks, xxx

unblock account

When you get a chance could you unblock my account

blocked here too..

just registered but cannot login...thanks!

complete TOC , i wish i read it

Would you please activate my account.


I would love to download and

I would love to download and the PDFs and make donations but I've tried over the months to get an account that's enabled and never do. Why that setup for accounts? Looks like great info here but.. blocked by this registration process.

Me too...

Yet another who would like to download the pdf but can't login. I am in the process of making a theming diagram for myself - since i am a visual thinker - and would like to use your guide as a guide. My username is Hunabku.


Yet another needs to login

please help - registered but can't login.
Username: Hunabku
Are you requesting donations?

Thank you for your hard work

This sounds like an excellent e-book, could you please activate my account so that I cant download it.

Thank you,


Great Job & a Couple of Questions

Hi Caroline!

First of all, let me tell you that you did a great job so far with the Theming e-Book and I simply can't wait to read on. It's got lots of great info - thanks a lot! There really should be more people like you - people who believe in helping others.

I've only recently started learning Drupal and PHP, and using various articles I found on the net, I managed to make a template for my website. I have some knowledge of CSS that gets me from A to B, so after I placed all of the PHP snippets correctly into my XML design, the pages started looking like I wanted fairly quickly.

Today, I decided to tweak my custom theme to look good on the administrative pages. Since my website will be more like a Blog/Gallery, it is not very important how they look, but still, working with nice-looking pages is much more pleasant. So, after some time, I got to editing the styles for the 'Submit Page' section. Here's the trouble I ran into while doing it.

This might be a really silly thing to ask, but I am a little stuck. I would like to have the 'Title' and 'Body' text in normal font-weight, not bold. No matter what I do to my .css file, unless I comment out the bold font in system.css like this, the text is remains bold:

(system.css, line 90)

.form-item label {
display: block;
/* font-weight: bold; */

It's not a deal of great importance, I just would like to know the reason. I have checked and I have no conflicting attributes in the style.css file. Any help will be appreciated. Whew, this was a long post.


How can login and download thanks

How can login and download thanks

Finish the book, please

Part of the book you actually wrote is truly best text on Drupal theming I've read.

It is focused and up to the point. Great book design too.

Why don't you upgrade it to Drupal 6, finish it and publish the book? If it matters at all, I bet you could make decent money out of it.

Drupal themes -