The Theme System
As discussed briefly in Chapter 1, modules generate the contents of a given page, and the theme system provides the opportunity to cut in and customize the page before it’s displayed. A theme is a collection of images, CSS, and (usually) HTML/PHP files that change the look of Drupal’s default output. With a simple flick of a radio button, you can completely change the design of your website by choosing a different theme, and you can customize settings on a theme to make adjustments, such as to the site logo or colors, as we saw in Chapter 2.
Figure 11-1 provides a general overview of how the theme system works. Each path in Drupal corresponds to a particular module that is responsible for handling the page request. For example, “node/1” is handled by the Node module, “admin/build/ themes” is handled by the System module, and a path like “albums” might be handled by the Views module. After the module has built up the contents of the page, it calls up the theme system with a special function called theme(), which we’ll be discussing in more depth later in the chapter.
The theme system consists primarily of a theme engine, which defines the dynamic parts of the page, as well as the rules for how Drupal’s output is defined and can be over- ridden, and the currently enabled theme, such as Garland. The theme engine is capable of setting up the basic structure and markup of the content and rendering the entire page template with the current page’s content inside of it. But where the visual magic happens—and where you start to gain control over exactly how each element on the page looks—is in the theme itself.
Every single element on the page, from the title in the browser window, to the site logo, to the regions where blocks are placed, to the links in the menu bar, is run through the theme system. The difference between an obviously “Drupal”-looking site and a stylish site is creative use of the tools provided by the theme layer. Let’s look at the pieces of a theme we have to work with, as well as how Drupal expects us to use them.
Figure 11-1. An overview of how Drupal goes from URL to HTML
.info Files
Beginning with Drupal 6, themes are defined by a theme_name.info file that resides in the theme’s directory, often simply referred to as the “.info file.” This file defines a variety of metadata for the theme, including the name of the theme, a description, its Drupal core version compatibility, and which theme engine it uses. Beyond those ba- sics, the .info file can also define the block regions available to the theme, and the CSS stylesheets and JavaScript files used. You can also define the theme features available to administrators under the theme configuration screens (see Chapter 2.
Here is a simple example showing basic theme information, taken from the core Blue- marine theme. A full description of all attributes available in .info files for themes is available at http://drupal.org/node/171205.
Regions
Regions are the areas on your site where you can place blocks, as we did in Chapter 2 and in other places throughout this book. Drupal provides five regions by default:
• Header (header)
• Footer (footer)
• Left sidebar (left)
• Right sidebar (right)
• Content (content)
You can change this list of regions for your theme in its .info file. Here is an example that creates a new region, Ads, and also excludes some of the defaults, such as Header, by not defining them:
regions[ads] = Ads regions[right] = Right sidebar regions[content] = Content regions[footer] = Footer
By defining just these regions in the theme, site administrators are limited in where they may place blocks on the block administration page for this theme. There will be no Header or Left sidebar for them to use. This can be very powerful when you have a very specific layout and you don’t want administrators putting things in the
“wrong” place.
Features
Features refer to the various elements of a theme that can be toggled on and off through the theme
administration interface at Administer→Site building→Themes (admin/ build/themes), under the Configure tab.
The following is the default list of features provided by Drupal core:
• Logo (logo)
• Site name (name)
• Site slogan (slogan)
• Mission statement (mission)
• User pictures in posts (node_user_picture)
• User pictures in comments (comment_user_picture)
• Search box (search)
• Shortcut icon (favicon)
• Primary links (primary_links)
• Secondary links (secondary_links)
If you wish to exclude a feature from the toggle list, you need to create your own feature list in the .info file and make sure to comment out or remove the items you don’t want. The Skyliner theme has the following feature list:
features[] = name features[] = slogan features[] = mission features[] = search features[] = favicon
CSS
You can define the name and location of all of the CSS and JavaScript files for your theme in the .info file. If no stylesheets are added in the .info, Drupal will automatically find and include the style.css file within your theme directory. You can easily use other stylesheets in addition to style.css if you want. You can also override the CSS that is provided by modules in your site. By giving a theme’s CSS file the same name as a module’s CSS file, we tell Drupal, “Use this file, not that file,” and Drupal will swap this file out for the original. An example of this would be to define system-menus.css in your theme, which would then override the core system-menus.css file in the System module’s directory (modules/system). Here is an example of defining CSS stylesheets from the Skyliner theme’s .info file (note that they have all been placed in a styles di- rectory inside the theme’s main directory):
stylesheets[all][] = styles/reset.css stylesheets[all][] = styles/typography.css stylesheets[all][] = styles/forms.css stylesheets[all][] = styles/style.css
JavaScript
There is also an automatically recognized default JavaScript filename, script.js, that you can use for your themes.
Again, you can add additional filenames to your .info file as well, as you can see in another example from the Skyliner theme:
scripts[] = skyliner.js
Template Files
Creating a Drupal theme with just images and CSS will work fine if Drupal’s outputting the HTML markup that you need. But what happens when you want to place an extra <div> around the title of a node, or you want to move the user picture from the top of posts to the bottom? This is where template files come in, providing the bulk of Drupal’s output markup.
Comments, nodes, blocks, and the overall page itself are all output through template files. Template files end with the special filename extension of .tpl.php. A template file is named by the item that it is controlling; for example, comments are controlled by the comment.tpl.php file, and the entire page is controlled by the page.tpl.php file.
The template.php File
We’ve now had a look at the basic building blocks for themes and some of the files that make up a theme. The last, crucial piece of Drupal theming is the ability to completely override the output that Drupal gives you by default and use your own custom markup instead. This is where the fun really starts.
You may find that while the template files give you a lot of control, you can’t really do much about the HTML that you are given inside those variables. You can do all the HTML editing around them that you want, but how do you crack into the variables themselves and get them to behave? The real customization of the nitty-gritty details comes in the form of the template.php file. This file is where master themers can really show their stuff by adding extra variables and logic to their themes.
How to Edit Theme