Anatomy of a Drupal Theme - Basic Structure
It can be a bit confusing to create a custom theme for Drupal. Users new to this process typically hack a core theme like Garland, or grab a starting theme from the repository, but then it's easy to get frustrated with all the different template files, functions, and styles. After all, what are these extra functions? Why aren't they included in Drupal's core if they're so necessary? Why do I see page.tpl.php and a bunch of node-*.tpl.php files and a dozen other .php and misc files? I'll try to cover some of the basic concepts of Drupal theming and get into the more advanced stuff in later posts. My goal here is to really break things down on a simple, linear level.
Describe Your Theme to Drupal
Every theme will need a theme-name.info file to describe the theme -- the name, the version, and the version of Drupal on which it can run, the locations of the JavaScript and CSS files, and to define the names of regions that blocks can be placed into.
Add Functions and Theme Settings
You can define functions within the template.php file to be used throughout your theme. Perhaps you want to list taxonomy terms or re-build the user login form based upon your own needs -- these custom functions can be setup within template.php.
You can also define settings that pertain to your theme within theme-settings.php. These configuration options will appear at ~/admin/build/themes/settings/your-theme-name. Theme settings might include tab styles, enabling or disabling certain block regions, or specifying where regions should go within your layout. I've found that theme-settings.php typically only pertains to community themes as a custom theme has all of its layout predefined in the template and CSS files.
Page.tpl.php
Your primary page template defines the overall structure of the page -- for example, the doctype declaration, html, head, and body tags, perhaps some general formatting like your div elements, and the closing body and html tags. You can also set block regions within this file. Think of page.tpl.php as your main "index.html" file that allows you to suggest and stylize the main structure of your site.
Check out the page.tpl.php API page for a list of available variables.
Node.tpl.php
The node.tpl.php template file handles the structure and styles of the node content only. Do I have to have a node.tpl.php? No, but you'd be missing out on all the flexibility and power that Drupal brings in the first place. If you simply print out $content in your page.tpl.php template, Drupal will spit out the page in a pre-formatted way. The beauty of the node.tpl.php template is that it allows you to specify the exact layout of the body of any Drupal node.
Check out the node.tpl.php API page for a list of available variables.
A Simple Theme
The most basic Drupal theme really could consist of this:
customtheme/
customtheme.info
page.tpl.php
customtheme.info source:
name = CustomThemedescription = A really simple custom Drupal theme.core = 6.xengine = phptemplateregions[sidebar] = Sidebar
page.tpl.php source:
<html><head><title><?php print $head_title; ?></title><?php print $head; ?><?php print $styles; ?></head><body><?php print $logo; ?><?php print $primary_link; ?><?php print $title; ?><?php print $tabs; ?><?php print $content; ?><div id="sidebar"><?php print $sidebar; ?></div><?php print $closure; ?></body></html>
This would give you a theme called "CustomTheme" on the ~/admin/build/theme page which outputs your dynamic primary navigation, any node content, your sidebar region and any blocks within it, and includes the proper META tags, etc., for your pages.
While overly simple, the structure of a theme should now be apparent to the new Drupal themer. Once you're comfortable with this setup, you'll certainly want to add the design and usability that your website requires; throughout that process you'll inherently need to add the additional theme files that will make it possible.
This brings us to the next stage of a custom theme - the node object.
Add new comment