Drupal PHPtemplate in a nutshell

Came across this wonderful post on the some drupal that explains it all :).

XTemplate is dead, long live PHPTemplate. :-) .theme files are there for legacy reasons. I don't know of anyone that actually uses them in production sites. Really, just use PHPTemplate.

In Drupal, there are theme_foo() functions. In your theme's template.php file, you can override them with a function named phptemplate_foo(). That, in turn, will get overridden by themename_foo(). Calling theme('foo') will call themename_foo(), phptemplate_foo(), or theme_foo(), whichever it finds first in that order. So if you wanted to override the "blocks" theme, you'd use phptemplate_blocks($region). Generally the easiest way is to just find theme_blocks(), copy and paste it to your template.php file, and rename it.

As a general rule, you should use phptemplate_foo() instead of themename_foo() in most cases. The exception is when the PHPTemplate engine itself already has a phptemplate_foo() function in the phptemplate.engine file.

OPTIONALLY, in the phptemplate_foo() function you can "stub out" the function to a template file. Any override function may do that, but in many cases you don't have to. The PHPTemplate engine itself already has override functions that "stub out" common theme functions (page, node, etc.), so you don't need to most of the time. Have a look in phptemplate.engine to see how it works for the standard overrides, and follow that pattern for your own when you need them.