Plain PHP themes
PHP themes are the most direct way of themeing Drupal. A PHP theme consists of overrides for Drupal's built-in theme functions. You will most likely only override the basic theme hooks (pages, nodes, blocks, ...), but you can theme anything from lists to links if you desire.
To create a PHP theme, create a directory in your themes directory (we will assume themes/mytheme in this document), and inside that directory create a mytheme.theme file. This file is a regular PHP file, so make sure it contains <?php ?> tags.
The default theme functions in Drupal are all named theme_something() or theme_module_something(), thus allowing any module to add themeable parts to the default set provided by Drupal. Some of the basic theme functions include: theme_error() and theme_table() which as their name suggests, return HTML code for an error message and a table respectively. Theme functions defined by modules include theme_forum_display() and theme_node_list().
In your .theme file, you can override any of these functions. To override the function theme_something(), define the function mytheme_something() in your .theme file. This function should have the same definition as the original. It is easiest to start with Drupal's function, and apply your changes there: many theme functions contain code logic within them. To avoid problems when upgrading Drupal in the future, it is best to mark the changes between the original Drupal function and your customized version. That way, you can reapply to your customizations if the original was changed.
Required functions.
Aside from theme functions, there are two functions that you need to include.
The first is mytheme_features(). This function should return an array of strings, marking the features your theme supports (e.g. search box, logo, mission statement, ...). The theme system will provide toggles and settings for these features in the administration section. In your code, you can retrieve the value of these settings though theme_get_setting(). If you are planning on releasing your theme to the public, it is advised to implement all Drupal features, so others can customize your theme.
Available features are:
| logo | A logo can be used. The theme should check the settings default_logo (boolean) and logo_path (string). |
| toggle_logo | The logo can be turned on/off |
| toggle_name | The site name can be turned on/off |
| toggle_search | The search box can be turned on/off |
| toggle_slogan | The site slogan can be turned on/off |
| toggle_mission | The mission statement can be turned on/off |
| toggle_node_user_picture | The theme can optionally display user pictures next to nodes |
| toggle_comment_user_picture | The theme can optionally display user pictures next to comments |
Here's the _features() function from the standard chameleon.theme:
<?php
function chameleon_features() {
return array(
'logo',
'toggle_name',
'toggle_slogan');
}
?>The second required function is mytheme_regions(), which defines the available regions in the theme.
Here's the chameleon.theme _regions() function:
<?php
function chameleon_regions() {
return array(
'left' => t('left sidebar'),
'right' => t('right sidebar')
);
}
?>For each region you define, you'll want to include a code block including the region's content in the page output. Typically, this might look something like:
<?php
if ($blocks = theme_blocks('regionname')) {
$output .= '[wrapping content]' . $blocks . '[/wrapping content]';
}
?>Note that 'regionname' here is the array key, not its text description (that is, 'left' and not 'left sidebar'). By 'wrapping content' we just mean any div, td, text, or other elements you might want to enclose your region's content in.
So, to introduce additional regions beyond just the standard 'left' and 'right' ones, you simply (a) add your region to the list defined in your _regions() function and (b) render the resulting content to the output as shown. So the coding part's quick and easy, don't hesitate to be creative!
Directory names
Note that unlike templates and styles, themes are tied to their directory name. If you want to clone a PHP theme, you need to rename its directory, its .theme file and its functions inside the .theme file.