Drupal theming: theme_node vs. node.tpl.php

Posted: July 30th, 2008 | Author: admin | Tags: | No Comments »

So I’ve been incredibly frustrated trying to theme Drupal 5.x over the past few months.  Now, I’ll admit that this was my own fault, but the problem I ran into isn’t very clearly documented anywhere, so I figured I’d post the explanation here so that anyone else Googling it might be assisted by my hard-won wisdom:

theme_node OVERRIDES node.tpl.php files

There.  That’s it.  I had created a theme_node implementation in my template.php file in order to customize the node display, and forgotten about it.  Later on, when I tried to create node-nodetype.tpl.php files to customize the appearance of each type of node, nothing worked.  I tried everything.  I wound up just giving up.  Until finally, today, I absolutely needed to change something in the HTML in order to add some Javascript functionality, so I dug in, and managed to find the solution in a description of the way PHPTemplate works here.

Nowhere in the theming docs on Drupal.org is this mentioned.  It’s not mentioned in the API docs for the theme_node function either.  So now you have it in writing.

What this means, in practical terms, is that you should NEVER write an implementation of theme_node.  It’s less MVC than using a template file, it’s less flexible for displaying different node types differently, and it has the potential to trip you up down the line if you forget it’s there.  Just use the template files.  For sanity’s sake.