Introduction to theming

Drupal is known for its power and flexibility and it can be a daunting experience trying to understand how it all comes together. There are countless ways to solve theming problems but not all are recommended. Knowing the "Drupal way" can lead to minimized code bloat and easier maintenance. If you choose to break the rules and go your own path, knowing them first may lead to a greater chance of success.

This does not mean you must understand Drupal top to bottom in order to create your theme. You can dive in as deep as you need to get the job done, but the more complex your site's design, the better it is to understand more of what Drupal's theming system provides.

The aim of this handbook is to expose all parts of Drupal's theming layer. Some areas will be geared towards more technical users while others will be more basic. The information presented in the following pages will progress from a general overview all theme developers should be familiar with to the more specific, and at times, more technical explanations.

A few things you should be aware of before proceeding:

• An understanding of xHTML and CSS.
• JavaScript and jQuery if your theme needs scripting support.
• The terminology used in Drupal.

Knowing PHP will be a requirement in some situations but it is possible to avoid it entirely with pure CSS based themes.

Depending on your goals for the theme, it can be a very simple or complex process. Drupal is very open-ended so carefully consider what you are trying to achieve. You should think about the requirements of the site first. It is a lot easier to design with specific requirements in mind than creating a general purpose theme.

If you ever get stuck on a problem, read the troubleshooting page, ask in the theming forum or on IRC @ #drupal-themes. See How to effectively use IRC for instructions.

Theming overview

A common software practice is to compartmentalize the programming layer from the presentation layer. There are numerous reasons for this, the most obvious being that the skill set required for programming the back-end business logic is very different from creating a visually appealing and effective user interface. As a theme developer, you can control certain aspects of the available data but it is limited to the output and presentation. Only Drupal core and modules should work with input. For example, a module can implement a form with a default look and feel and handle user input saving it to the database. The theme's role is to only override the look and feel.

This abstraction in Drupal is achieved through the theme function. It is a conduit to the theming subsystem. It allows theme engines to provide an optional middle layer for tagging languages such as PHPTAL or Smarty. It also allows themes to control all presentation markup. Theme engines are optional as are tagging languages. PHPTemplate is the default engine. As the name suggests, PHP is the language used when outputting variables mixed in with the xHTML markup.

Starting with Drupal 6, the requirements for creating theme engines has been lowered substantially.

All layers can implement a themed representation of the output, but only within the theming layers can overrides occur; with a few exceptions. Theme engines can override themed output from core and modules, while themes can override everything else.

Note that PHPTemplate engine does not override any output but other theme engines can. There is a special case where a module can influence the output or override absolutely everything but it is for very special cases and should not interfere in most situations. For example, the devel themer module does this to aid theme development. More details will be revealed in a later section.

You can ignore most of this if your theme will be styled entirely through CSS but when the markup needs to be altered, it is important to know how to get to the source of the output so it can be altered.

• Note that the core of Drupal and countless modules always use themable functions and template files to output the presentation markup. Never hack on files outside your theme folder as that would lead to complications when there is a need to update. This is known as "forking". The power of open source is to have the community manage bug fixes and add new features. Once you start a fork, a closed system is created and you lose the leverage of the community. Drupal provides all the functionality to override the presentation layer. If you ever have to hack on files outside the theme, either you are doing something wrong or it is a bug. In the latter case, please file a bug report. Or even better, provide a patch file to fix the problem.
• For those familiar with PHPTemplate engine in previous incarnations, almost all the functionality has been moved deeper into core. The job now of PHPTemplate is to only discover theme functions and templates on behalf of the theme. It is less of an engine and more of a theme helper. PHPTemplate was originally written by Adrian Rossouw for 4.7. The changes in 6 was the work of Earl Miles. An extended forum discussion provides some of the reasoning behind the initial creation of the engine and the issue queue for the new direction in 6.

Anatomy of a Drupal theme

phptemplate theme:

.info (required)

All that is required for Drupal to see your theme is a ".info" file. Meta data, style sheets, JavaScripts, block regions and more can be defined here. Everything else is optional.

The internal name of the theme is also derived from this file. For example, if it is named "drop.info", then Drupal will see the name of the theme as "drop". Drupal 5 and below used the name of the enclosing folder of the theme.

Info files for themes are new in Drupal 6. In version 5, .info files were used solely for modules.

template files (.tpl.php)

These templates are used for the xHTML markup and PHP variables. In some situations they may output other types of data -xml rss for example. Each .tpl.php file handles the output of a specific themable chunk of data and in some situations it can handle multiple .tpl.php files through suggestions. They are optional and if none exists in your theme, it will fall back to their default output. Refrain from having complex logic in these files. In most cases, it should be straight xHTML tags and PHP variables. A handful of these templates exist in directories where core and contributed modules exist. Copying them to your theme folder will force Drupal to read your version.

Note: The theme registry caches information about the available theming data. It must be reset when adding or removing template files or theme functions from your theme.

template.php

For all the conditional logic and data processing of the output, there is the template.php file. It is not required but to keep the .tpl.php files tidy it can be used to hold preprocessors for generating variables before they are merged with the markup inside .tpl.php files. Custom functions, overriding theme functions or any other customization of the raw output should also be done here. This file must start with a PHP opening tag "<?php" but the close tag is not needed and it is recommended that you omit it.

Sub-themes

On the surface, sub-themes behave just like any other theme. The only differences is that they inherit the resources from their parent themes. To create one, a "base theme" entry inside the .info file is needed. From there it will inherit the resources from its parent theme. There can be multiple levels of inheritance, i.e., a sub-theme can declare another sub-theme as its base. There are no hard set limits to this.

Drupal 5 and below required sub-themes to be in sub-directories of the parent theme. This is no longer the case.

Others

• The logo and screen shot is not absolutely necessary for the theme to function but it is recommended especially if you are contributing it to the Drupal repository. Screenshots will show inside the theme administration page and the user account settings for selecting themes when the appropriate permissions are set. See the screenshot guidelines for more information.
• To supply administrative UI settings or "features" beyond logo, search, mission, etc., a "theme-settings.php" file can be used. This is an advanced feature. More information can be found in the Advanced settings handbook page.
• For color module support, a "color" directory with a "color.inc" file is needed along with various support files.

• If you want to base your work off a core theme, use sub-theming or make a copy and rename the theme. Directly modifying Garland or Minnelli is strongly discouraged since they are used for the install and upgrade process.
• All themes should be installed in the "sites/all/themes" directory to separate them from core files. Read about multi-site installations to see all the possible installation directories.

.info files for themes

New to Drupal 6, .info configuration files are now required for each theme. This file should reside in your theme's directory. Without this file, your theme will not be visible by Drupal. The .info file must end with the ".info" extension.

The internal "machine" readable name of the theme is derived from this file. For example, if it is named "drop.info", then Drupal will see the name of the theme as "drop". Be sure that no odd characters are used since it informs Drupal on how to form various functions in PHP and therefore it will have the same limitations. The name should start with an alphabetic character, no spaces or punctuation. Underscores are allowed but no hyphens. Numbers are allowed as long as it is not the first character.

Notes:

• Warning! Modules bearing the same internal name as your theme can prevent your site from functioning. This may happen from duplicate function names which is illegal in PHP. All installed components must have unique names.
• The contents of the .info file is cached in the database so altering it will not be noticed by Drupal. (Do not confuse this with the theme registry.) To clear it, do one of the following:
  1. Clear button located at "Administer > Site configuration > Performance".
  2. With devel block enabled (comes with devel module), click the "Empty cache" link.
  3. Simply visit the theme select page at "Administer > Site building > Themes".

The syntax is similar to INI files. It is basically a static text file for configuring the theme. Each line in the text file is a key-value pair with the key on the left and the value on the right, with an "equals sign" between them. (example: key = value) Semicolons are used to comment out a line. Some keys use a special syntax with square brackets for building a list of associated values, referred to as an "array". If you are unfamiliar with arrays, using them should be apparent enough by following the example of the default .info files that come with Drupal and reading the explanations of the examples that follow.

Drupal understands the keys listed below. Drupal will use default values for the optional keys not present in the .info file. See the examples set for core themes.

• name !
• description *
• screenshot
• version *
• core !
• engine *
• base theme
• regions
• features
• stylesheets
• scripts
• php

name (required)

The human readable name can now be set independently from the internal "machine" readable name. This imposes less restrictions on the allowed characters.

name = Un tema nombre de fantasía
   

description (recommended)

A short description of the theme. This description is displayed on the theme select page at "Administer > Site building > themes".

description = Tableless multi-column theme designed for blogs.
   

screenshot

The optional screenshot key tells Drupal where to find the theme's thumbnail image used on the theme selection page (admin/build/themes). If this key is omitted from the .info file, Drupal uses the "screenshot.png" file in the theme's directory.

Use this key only if your thumbnail file is not called "screenshot.png" or if you want to place it in a directory outside of your theme's base directory (e.g. screenshot = images/screenshot.png).

screenshot = screenshot.png
   

version (recommended)

The version string will automatically be added by drupal.org when a release is created and a tarball packaged. So, you may omit this value for contributed themes. However, if your theme is not being hosted on the drupal.org infrastructure, you can give your theme whatever version string makes sense.

version = 1.0
   

core (required)

From 6.x onward, all .info files for modules and themes must indicate what major version of Drupal core they are compatible with. The value set here is compared with the DRUPAL_CORE_COMPATIBILITY constant. If it does not match, the theme will be disabled.

core = 6.x
   

Note that the drupal.org packaging script automatically sets this value based on the Drupal core compatibility setting on each release node. So, people downloading packaged themes from drupal.org will always get the right thing. However, for sites that deploy Drupal directly from CVS, it helps if you commit this change to the .info file for your theme. This is also a good way to indicate to users of each theme what version of core the HEAD of CVS is compatibile with at any given time.

engine (recommended)

The theme engine, which is used by the theme. If none is provided then it is assumed the theme is stand alone, i.e., implemented with a ".theme" file. Most themes should use "phptemplate" as the default engine.

PHPTemplates job is to discover theme functions and templates on behave of the theme. Omit this entry only if you know what you are doing.

engine = phptemplate
   

base theme

Sub-themes can declare a base theme. This allows for theme inheritance, meaning the resources from the "base theme" will cascade and be reused inside the sub-theme. Sub-themes can declare other sub-themes as its base allowing multiple levels of inheritance. Use the internal "machine" readable name of the base theme. The following is used in Minnelli, the sub-theme of Garland.

base theme = garland
   

More details are available in the page, Sub-themes, their structure and inheritance.

regions

The block regions available to the theme are defined by specifying the key of 'regions' followed by the internal "machine" readable name in square brackets and the human readable name as the value, e.g., regions[theRegion] = The region name.

If no regions are defined, the following values are assumed. You can override the values for your specific needs.

regions[left] = Left sidebar
regions[right] = Right sidebar
regions[content] = Content
regions[header] = Header
regions[footer] = Footer
   

More details are available in the page, Blocks, content and their regions.

features

Various page elements output by the theme can be toggled on and off on the theme's configuration page. The "features" keys control which of these check boxes display on the theme's configuration page. This is useful for suppressing check boxes for elements not defined or used by a theme. To suppress a check box, omit the entry for it. However, if none are defined, all the check boxes will display due to the assumed defaults.

The example below lists all the available elements controlled by the features key. By commenting out the primary_links and secondary_links elements, their check boxes are suppressed and are not seen by site administrators.

features[] = logo
features[] = name
features[] = slogan
features[] = mission
features[] = node_user_picture
features[] = comment_user_picture
features[] = search
features[] = favicon
; These last two disabled by redefining the
; above defaults with only the needed features.
; features[] = primary_links
; features[] = secondary_links
   

More details are available in the page, Custom theme settings.

stylesheets

Traditionally, themes default to using style.css automatically and could add additional stylesheets by calling drupal_add_css() in their template.php file. Starting in 6, themes can also add style sheets through their .info file.

stylesheets[all][] = theStyle.css
   

More details are available in the style sheets section.

Example .info files from core themes

Garland:

Minnelli sub-theme of Garland.:

Note that everything from the line "; Information added by drupal.org packaging script on 2008-02-13" and down is added by the drupal.org packaging script. You should never manually add the project and datestamp keys. The version key added manually (in the first section) allows sites to use your theme when taken directly from CVS.

Overriding themable output

The following only applies when the default markup needs changes. This section can be skipped if the presentation is handled only through style sheets.

There are three aspects to overriding the themed output. The first is knowing where the source originates, the second is providing the override and third is understanding its type.

Note that Drupal maintains cached theming data through the theme registry. It must be cleared when setting up overrides.

1. Finding the source:

Finding the source can be difficult to track down due to the hierarchy of theming calls whose source can be spread throughout the whole system.

Links to 520KB PDF. Provided for illustration only.

Most of the page elements are typically pulled with theme('page') and placed inside the page.tpl.php template after rendering navigation bits, the bits within the navigation bits, block regions, the blocks within the block regions, etc. Each chunk of themed data is often referred to as a theming "hook".

Note: Theming functions and templates will now be referred to as theming hooks. There are many hooks unrelated to theming throughout the system. Any mention of it here only relates to theming.

Getting to the source of any specific chunk of markup can now be tracked with the devel module. It includes a theming tool to easily visualize the source of any output, its type and tons of other theming data. See the screencast for a demonstration. This is not available for Drupal versions less than 6 due to technical limitations.

2. System of overrides:

The system of overrides has a specific cascading order with few exceptions. Drupal core and modules provide a reasonable default for its markup handled by the theming hook. If it does not suit the requirements of the theme, then an alternate can be provided preventing the defaults from being used. This way, the defaults are left alone and all the theme specific changes are localized to the theme. Never hack on files outside your theme.

If you need more control beyond this convention of overrides, the theme registry can be manipulated for more control.

Note: Although it is still possible, PHPTemplate.engine in Drupal 6 no longer overrides theme functions. In 5, that is what allowed templates to be used for a handful of the theming hooks. It is no longer necessary.

3. Functions vs. templates:

There are two ways or "types" as it was mentioned above in implementing any given hook. Normal "functions" or "templates". Depending on the nature of the themed element, one may be better suited than the other. Core and modules can construct the output in either type. The upper theming layers can carry over the same type or change it.

Links to PDF. Flow map for 5 also available for comparison.

Theming hooks implemented as functions provide speed. It is about five times faster than templates but they are difficult for designers who may be more familiar with working directly in xHTML. Generally, this should not be a concern as it depends on the nature of the hook and the number of times it is called on a page.

Note: In versions before 6, core and modules could only work as functions for the theming hooks. Implementing through templates was done by PHPTemplate by overriding the hooks and doing the conversion on the engine layer.

Here are two examples on overriding with the help of devel themer.

Overriding functions:

The theme function theme_menu_local_tasks is a simple function for outputting both primary and secondary tabs. The theming hook in this case is "menu_local_tasks". To override, the "theme" prefix in the function name can be changed to the name of your theme or the theme engine the theme is running under. Using the theme name is recommended due to potential name collisions with sub-themes.

The example shows Garland is using the name of the theme engine for the override. If you were to create a sub-theme based on Garland, then using the name of your theme is mandatory.

Placing the following inside the theme's template.php file will override the default after clearing the theme registry. Change "drop" to the name of your theme.

<?php
function drop_menu_local_tasks() {
  $output = '';

  if ($primary = menu_primary_local_tasks()) {
    $output .= "<ol class=\"tabs primary\">\n". $primary ."</ol>\n";
  }
  if ($secondary = menu_secondary_local_tasks()) {
    $output .= "<ol class=\"tabs secondary\">\n". $secondary ."</ol>\n";
  }

  return $output;
}
?>

The only change here is the markup from an unordered list to an ordered list.

A listing of all the theme functions can be found on api.drupal.org.

Overriding templates:

If the default implementation is done as a template then simply moving the source template file into the theme will automatically override it after clearing the theme registry. Here is an example for search-theme-form.tpl.php. Note that the theming hook in this case is "search_theme_form" with the template using hyphens instead of underscores.

That is all you need to do. Open the copied template in your editor to make your alterations. All the core .tpl.php files are documented. It should give a good indication on what can be done with the output.

Note: templates can be placed in any directory within the theme. This allows for better management and less clutter in the base level of the theme directory.

Related pages:

• To customize the variables inside templates, see the sub-page on Preprocess functions.
• A listing of all the theme templates can be found on the sub-page, Core templates and suggestions.

Converting from functions to templates

Converting a theme function into a template takes some initial work but once it is done, it's easier to work with. If you are collaborating with a designer, the conversion will enable them to focus on designing, not coding. There are many templates already available in core and many more will be converted in future versions. Contributed modules that follow best practices should also have templates available. These instructions are provided for the theming hooks not already made available as templates.

Getting Drupal to recognize the theming hook as a template is automated. These are the only requirements to trigger this change:

• Name of the template must match the theming hook.
• The underscores in the hook must be changed to hyphens.
• The template name must have an extension of ".tpl.php". (It can vary based on the theme engine.)

Consider the theming function theme_user_signature. The theme hook here is "user_signature". Creating a file named "user-signature.tpl.php" will tell Drupal that the hook is now a template after clearing the registry. Any content in this file will now take the place of the function. The part that takes more work is setting up the variables to be used in this file and that is done through preprocess functions.

A few notes:

• While it is possible to code directly inside the template, it is not considered good practice. All the complex logic should be separated from the .tpl.php file. This keeps it clean and easy to manage.
• There is also the issue of security. The separation can minimize the chance of cross-site scripting attacks by cleaning out potentially malicious user generated content. When handing over template files to your designer, all the output should be clean so they do not have to concern themselves with security issues.
• Compare the theming functions in 5 to the template conversions in 6 for forums. You can use that as an example on converting between the two types.
• More information on preprocess functions available.

The theme registry:

For most theme developers, the registry does not have to be dealt with directly. Just remember to clear it when adding or removing theme functions and templates. Editing existing functions and templates does not require a registry rebuild.

To clear the theme registry, do one of the following things:

1. Clear button located at "Administer > Site configuration > Performance".
2. With devel block enabled (comes with devel module), click the "Empty cache" link.
3. The API function drupal_rebuild_theme_registry.

The theme registry is cached data instructing Drupal on the available theming hooks and how to handle it by indicating its type. In previous versions all theming calls were handled on the fly. Since a lot more work is being done under the hood, the cached instructions speeds up the process especially for templates. The theme engine your theme is running under should automatically register all the theming hooks for you.

There are special cases where you may need to work with the registry directly. When your theme requires a new hook to be registered that was not already implemented on the layers below it (core, modules, engine). This includes some forms when they are not explicitly themed by core or modules but instead rely on the default form presentation.

• More details can be found in the sub-page, The theme registry for special cases.
• Do not confuse the theme registry with the theme's .info file which is also cached. Points 1 and 2 on clearing the registry will clear both.

Style sheets

The following will cover how Drupal handles style sheets through .info files. See the sub-page on adding through the API functions for more advanced functionality. Styling themes purely through CSS is possible with the information provided here.

There are a few points to be aware of. Each core component or module will provide a reasonable default for its presentation. This includes the markup and an associated style sheet. (see the explanation on the overriding behavior for the markup.) Due to the extensible nature of Drupal, it would be a great burden for themers to handle everything being pushed out to the browser. These defaults are there to be changed at the themers discretion. Just like the overriding behavior for themable functions and templates, the style sheets provided by core and modules can be overridden. Do not modify directly. All changes should be localized inside your theme.

Notes:

• When working with style sheets, make sure CSS Optimization is disabled. It is located in "Administer > Site configuration > Performance". When it is enabled, any alterations will not be reflected on your site until the aggregated styles are cleared. You can enable it again when you're done.
• The .info file is cached. Adding or removing any styles will not be noticed until it is cleared. (Do not confuse this with the theme registry.) To have it cleared, do one of the following:
  1. Clear button located at "Administer > Site configuration > Performance".
  2. With devel block enabled (comes with devel module), click the "Empty cache" link.
  3. Simply visit the theme select page at "Administer > Site building > Themes".

Adding style sheets:

By default, a "style.css" file will be used from your theme when no other styles are defined inside the .info file. Adding other styles is as simple as defining a new 'stylesheets' key with its media property and the name of the style sheet. Keep in mind that defining custom styles will prevent the default "style.css" from loading. Remember to explicitly define the default if your theme uses it.

; Add a stylesheet for all media
stylesheets[all][] = theStyle.css

; Add a stylesheets for screen and projector media
stylesheets[screen, projector][] = theScreenProjectorStyle.css

; Add a stylesheet for print media
stylesheets[print][] = thePrintStyle.css
   

A few notes:

• Note the empty square brackets between the [media] and = styleName.css.
• The order in which the styles are listed in the head of the page will reflect the order it is defined here.
• The style sheets can be placed in sub-directories, i.e., stylesheets[all][] = stylesheets/styleName.css. Useful for organizing style sheets.

Overriding core and module style sheets:

To override a core or module style sheet, it can be redefined from the themes .info file. Take "system-menus.css" as an example. It is located in "modules/system/system-menus.css". With this entry, the original CSS file will be ignored and your local copy will be loaded.

stylesheets[all][] = system-menus.css
   

A few notes:

• Overriding a core CSS files will prevent the default "style.css" file from loading. Remember to explicitly define any defaults when needed.
• The themes override must have a matching media type of the original style.
• Any linked elements within the style will have to be corrected. Double check the file for any 'url()' properties or '@import' rules to make sure they are pointing to the right resource.
• The order the style sheets listed in the head of the page will change. In effect, this may cause some cascading rules to change with it.
• Some core and module style sheets are loaded conditionally. Overriding through .info files will force the file to be always used.
• If the changes from the theme is not substantial, then consider using CSS selectors to override the styles instead of overriding the whole file.

Overriding the base theme's style sheets:

This only applies to sub-themes. To prevent a style sheet from a base theme from being carried over to a sub-theme, you can redefine the style sheet inside the .info file.

The base theme and the sub-theme must have the same entry:

stylesheets[all][] = masterStyle.css
   

If the file exists inside the sub-theme, then it will be used while omitting the file will prevent it from loading.

JavaScript & jQuery

jQuery basics

As of version 6 of Drupal, jQuery 1.2.3 is included in Drupal core,

Default JavaScript file

Similarly to style.css, there is a new automatically included file named script.js for adding JavaScript code to a theme. The file should be placed in the theme's home directory.

JavaScript theming

There is now a theming mechanism for JavaScript code. Together with the automatically included script.js, this allows theme developers more freedom in the domain of scripted events on Drupal sites. Often, people's JavaScript code produces markup that is inserted into the page. However, this may contain HTML that has been hard-coded into the script, which did not allow alteration of the inserted code.

Modules provide default theme functions in the Drupal.theme.prototype namespace. For example, if I wanted to make my theme function powered(to display a "powered by Drupal" icon), it would look like this

The way I would call this is

That puts a button like

in the footer.

If I wanted to override this in my theme, maybe to include files in my theme directory instead of /misc, I would do so like this:

This takes advantage of plain JavaScript. The above function would go in a theme's JavaScript file, avoiding the need for altering the related module's JavaScript files.

JavaScript theme functions are entirely free in their return value. They can vary from simple strings to complex data types like objects, arrays, and jQuery elements. Refer to the original (default) theme function to see what your custom theme function should return.

Still needed: jQuery intro, how to add aggregation (patch at http://drupal.org/node/119441) etc...

Blocks, content and their regions

The block regions available to the theme are defined within .info files. It must be specified with the key of 'regions' followed by the internal "machine" readable name in square brackets and the human readable name as the value, e.g., regions[theRegion] = The region label. If none are defined, the following values are assumed.

Keep in mind that the internal names are converted into region variables inside the "page.tpl.php" template automatically. In the above example, the [left] region will output all the blocks assigned to it through the $left variable. There are a few restrictions on naming variables in PHP so make sure the internal names conform to the same restrictions. It can only contain alphanumeric characters and underscores but it cannot start with a number.

The human readable name outside the square brackets are used for labeling the region in the block administration page located at "Administer > Site building > Blocks".

Here is the block administration table for Garland:

A few notes:

• There are template (.tpl.php) files available for rendering individual blocks.
• Adding a custom region prevents the defaults from being used. If you want to keep the defaults in addition to custom regions, manually add in the defaults.
• The order in which the regions are defined will be reflected in the block configuration table. Garland for example uses the default regions. Notice the order of the regions listed in the image.
• The contents of the .info file is cached in the database so altering it will not be noticed by Drupal. (Do not confuse this with the theme registry.) To clear it, do one of the following:
  1. Clear button located at "Administer > Site configuration > Performance".
  2. With devel block enabled (comes with devel module), click the "Empty cache" link.
  3. Simply visit the theme select page at "Administer > Site building > Themes".

Upgrade notes:

• In Drupal 5 and below, regions were declared with ThemeName_regions() or EngineName_regions(). It has been deprecated in Drupal 6.
• If you are upgrading your theme from versions before Drupal 6 and the region variables of $sidebar_left and $sidebar_right were used, rename them to $left and $right.
• The $footer_message region variable in versions before 6 mixed the footer region with the footer message (set from "Administer > Site configuration > Site information"). Make sure a separate $footer variable is created if your theme uses it since Drupal 6 and above no longer combines the two elements.

Manually assigning content to regions:

Content can be manually set inside regions with drupal_set_content. For example, drupal_set_content('header', 'Welcome!') would assign the text 'Welcome!' to the header region.

Here is a more useful example for building a summary of all the comments into the "right" region. Rename the "drop" prefix with the name of your theme. More information on preprocessors is available.

Note that setting content through this function should happen before the block regions are retrieved and that is done with a call from template_preprocess_page > theme_blocks > drupal_get_content.

Custom theme settings

Various page elements output by the theme can be toggled on and off on the theme's configuration page. Located at "Administer > Site building > Themes > themeName". For example, the site's slogan can be suppressed by unchecking the "Site slogan" check box on that page.

These checkboxes show themselves depending on the the features enabled inside the .info file. It must be specified with the key of 'features' followed by empty brackets then the feature itself, e.g., features[] = the_feature. If none are defined, the following values are assumed.

To disable any features, only add the ones you want into the .info file. Defining only the features needed for the theme will omit the rest. Some of the features will also enable related form fields. For example, 'logo' will enable an upload field for the image along with the checkbox.

A few notes:

• The contents of the .info file is cached in the database so altering it will not be noticed by Drupal. (Do not confuse this with the theme registry.) To clear it, do one of the following:
  • Clear button located at "Administer > Site configuration > Performance".
  • With devel block enabled (comes with devel module), click the "Empty cache" link.
  • Simply visit the theme select page at "Administer > Site building > Themes".
• hook_features() is no longer supported.

Theming the maintenance page

The maintenance page is used when the site is set into off-line mode. You can enable this mode from "Administer > Site configuration > Site maintenance". This mode will also trigger with a database failure. By default, the core theme Minnelli is used in this mode even if another theme is selected. To use your theme for the maintenance page, it has to be set from your "settings.php" file located in either "sites/default" or "sites/your.domain.com".

From that file, enable it through the $conf variable with the internal name of your theme:

Next, copy your main "page.tpl.php" and rename it to "maintenance-page.tpl.php" or copy the template located in "modules/system/maintenance-page.tpl.php" to your theme and edit so it matches the rest of your site. Verify the changes by setting the site into off-line mode then log out.

To account for database failures, try turning off your database. Any function call that depends on the database should be checked first with db_is_active. The variable $db_is_active can also be used from the template.

To prevent warnings about the database connection from appearing, you can also place a template file named "maintenance-page-offline.tpl.php" and change the $content variable with your custom message. This template file is a template suggestion based on maintenance-page.tpl.php so they both need to exist.

A "maintenance.css" file is included in this mode. It is located in "modules/system/maintenance.css". You can override this file with the instructions provided in the style sheets section.

Notes:

• The initial install and updating of your site depends on the core themes, Minnelli and Garland. It cannot be changed for these modes.
• The theme registry is not cached when set to off-line mode.

Troubleshoot your theme

For all the effort you put into building your site the most important thing to your users is how your site looks. Managing the inconsistencies in your theme for each browser, for each module, and for user selectable themes can be very challenging.

First you should familiarize yourself with basic Cascading Style Sheets (CSS) concepts. Review CSS Discuss or HTML dog for CSS resources. A good overview of the power of CSS can be seen at the CSS Zen Garden.

Validate! Always. Validate XHTML 1.0 Strict.

There is no way you can know what certain browsers do in certain quirky situations. Which causes the inconsistencies. But adding your load to that uncertainty, makes things harder and impossible for others to help you. Only if you have validated XHTML and CSS and if it looks good in standard compliant browsers, you can start debugging. Too often one hears designers "butbutbut, if i make it validate, then it looks awfull again, I don`t want to start all over again" . In that case, the fact that designer had a good looking layout, was due to a bug! debugging on top of bugs is just not an option!

And really: A validating, clean layout will work 90% of the time. will have easy fixes 9% of the time and will only require hard measures 1% of the time. Really!

If you would like to validate your whole site you can use these tools.

Your page should not look the same everywhere

Another very important thing to notice is the nature of HTML and CSS. They are meant to look different in different places. My mobile phone is not able to show your fancy 6 column fixed with javascript based layout. And it should not be able to. Safari and Konqueror decided to not allow certain styles in forms (security and desktop consistency). Large screens will resize your font and that might break your fixed with layout. People using older screens will have larger font sizes set. People with bad internet connections often disable images. Or even CSS.

So keep in mind that your style is nothing more than an advice for browsers to display it in certain ways. It is by no means a law.

Tools for managing inconsistencies in your theme

1. We recommend you start with a standards compliant browser for your themes such as Firefox. Firefox allows you to highlight portions of your web page and right click view selected source to understand what your themes CSS classes are. Understanding how CSS classes for you theme are applied to the underlying xhtml is the key to understanding your theme.
2. Use standard CSS naming conventions. We recommend adopting these naming conventions for you CSS classes.
3. Select a valid DOCTYPE type for your theme and include a DocType Declaration(DTD).
4. To help in analyzing your HTML and CSS we recommend you install the Firebug plugin for Firefox. It is an invaluable tool that allows you to look at your css and html and change it in real time to evaluate the effects of your changes. Another very useful Firefox plugin is the Web Developer toolbar. This has tons of handy utilities.
5. The view formatted source extension for FireFox displays formatted and color-coded source and optional CSS information for each element.
6. Before you start modifying your CSS to fix your bugs it is important to ensure you are styling valid HTML or xHTML. There is a web validator built into the Firefox Web Developer toolbar. Opera has built in validation, just press Ctrl+Alt+V.
7. A more advanced tool for analyzing HTML pages for looking over code, spotting errors is the Watchfire WebXACT tool.
8. If you find a problem with invalid XHTML in a module file an issue and include screenshots showing how this causes problems in the theme.
9. To see how your site will look to search engines you can use Lynx viewer.
10. Positioning problems in your site with Internet Explorer can be resolved using these references: Position Everything Internet Explorer Primer
11. A library of examples of problems can be found at Quirks mode.

Cross browser compatibility (FireFox, Internet Explorer, Opera, Safari)

It's hard to check your theme in all browsers. There are a number of tools which are available to help look at your theme in multiple browsers.

1. Browser Shots is freely available but can take a while to get your screenshots.
2. BrowserCam is paid service with a 24 hour trial.

On Windows you can use Internet Explorer and download Firefox or Opera. On Linux you can use Konqueror, a KHTML based browser, which Safari uses on MacOS, Opera, Firefox for Linux, and Internet Explorer can be run under WINE. On Mac OSX you can use Safari and download Firefox or Opera.

Color and graphic issues

1. If you are trying to select colors you can use Color schemes.
2. If your theme is causing errors in your logs with favico not found you can create a favicon with these two tools favicon from pics and favicon generator.
3. To check for how color blindness effects users see Vischeck

Selecting a base theme

If you are looking for a theme to start with Zen or Foundation are good base themes for CSS-based theming. There is also BlueMarine, which uses tables for layout.

Module specific CSS

Some Drupal modules come with a default CSS file. You should use a tool like the developer's toolbar to see if a module's CSS is styling your elements and causing problems. When you install a new module you can also look in the module's folder to see if is including a CSS file.

Actually debugging problems in your theme

There is no easy solution to debug your theme. If you are having trouble you should try to use the simplest base theme possible or select a theme that is known to work that is as close to your end goal as possible. Learning the CSS classes in your theme is critical to understanding where your CSS changes will be applied. Try to find other themers by talking in IRC, providing documentation, and tutorials of what you have done. Make your existing theme available so that others can review and provide feedback on what you have done. Making friends with PHP programmers who can help you understand what the underlying PHP theme template is doing is also very important. Consider an exchange of skills to get support.

This page was written by Kieran Lal, and Trae McCombs from CivicSpace Labs with Theodore Serbinski. If you would like to contribute or help make Drupal theming easier join the themes mailing list, or contact Kieran.

Theme coding conventions

Theme authors should take care to write clean, well structured code just like a coder for any other project. Doing so makes the code easier to read, understand and maintain. While different organizations have different conventions, it's usually best to follow the Drupal standards as this helps when collaborating or asking for help.

• Add 2 spaces for indents; rather than a tabbed indent
• Match the indentation of long opening and closing block HTML tags
• Distinguish between PHP and HTML indentation.

  Not this:

    ...
    <?php if ($header): ?>
    <div id="header">
      <?php print $header; ?>
    </div>
    <?php endif; ?>
    ...
     

  but this:

    ...
  <?php if ($header): ?>
    <div id="header">
      <?php print $header; ?>
    </div>
  <?php endif; ?>
    ...
     

  This makes it much easier to find matching opening and closing tags defined with different indentation.

• Prefer PHP in HTML to HTML in PHP in templates. For example,

  not this:

  <?php
  if (!$page) {
    print "<h2><a href=\"$node_url\" title=\"$title\">$title</a></h2>";
  }

  if ($submitted) {
    print "<span class=\"submitted\">$submitted</span>";
  }
  ?>

  but this:

  <?php if (!$page): ?>
    <h2><a href="<?php print $node_url ?>" title="<?php print $title ?>"><?php print $title ?></a></h2>
  <?php endif; ?>

  <?php if ($submitted): ?>
    <span class="submitted"><?php print $submitted ?></span>
  <?php endif; ?>
     

  After all, PHP is a HTML embedded scripting language - and not the other way around.

Theme screenshot guidelines

Screenshots within a Drupal install

Every theme for 4.5+ needs a screenshot in the form of a screenshot.png placed in the theme directory. These are displayed in the theme listing within a Drupal installation (i.e. at Administer > Site building > Themes in Drupal 5.x or greater.) It is best that screenshots are consistent. The guidelines for core theme screenshots are (starting from a blank Drupal site):

1. Log in as the first user.
2. Enable the following modules, for some extra menu items: aggregator, blog, node, page, search, story and tracker.
3. Turn on the features that the theme supports (logo, site name, slogan, search box). Add some primary and secondary links if needed. We suggest "Link 1" "Link 2" "Link 3", you can link them to e.g. "user/1".
4. Set the site name to Drupal and slogan to Community Plumbing.
5. Create the following story node:
   

   Donec felis eros, blandit non

   Morbi id lacus. Etiam malesuada diam ut libero. Sed blandit, justo nec euismod laoreet, nunc nulla iaculis elit, vitae. Donec dolor. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos hymenaeos. Vivamus vestibulum felis <a href="#">nec libero. Duis lobortis</a>. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nunc venenatis pretium magna. Donec dictum ultrices massa. Donec vestibulum porttitor purus. Mauris nibh ligula, porta non, porttitor sed, fermentum id, dolor. Donec eu lectus et elit porttitor rutrum. Aenean justo. Phasellus augue tortor, mattis nonummy, aliquam euismod, cursus eget, ipsum. Sed ultricies bibendum ante. Maecenas rhoncus tincidunt eros.

6. Look at the node, and make sure the tabs are visible. Take a screenshot.
7. Cut out a piece about ~420x254 resized to exactly 150x90 (~35% of the original size). Try to show only useful page elements (menu, tabs, title, links). Don't include browser chrome (toolbar, status bar, scrollbar, etc).
8. Apply a standard 'sharpen' filter to the thumbnail for clarity.
9. Save as a PNG, in paletted colorspace to cut down on size.

Example:

Screenshots for Drupal.org display

For Drupal.org project thumbnails (displayed at http://drupal.org/project/Themes and on the individual theme project pages), use the guidelines above except that:

• You should fill up the site more. For example, add a comment to the story node or add some blocks.
• The screenshot should show the entire page, though still without browser chrome (toolbar, status bar, scrollbar, etc).
• Try to make your original screenshot have a width of about 1000 pixels, so that the thumbnail is about 30% of the original size.
• Try to keep the image small: save as paletted PNG or as a JPEG with 10-20% compression. This reduces the load time of the theme list on Drupal.org.
• To add the image to your project, click the Edit tab on the project node and expand the "Attached Images" section. Browse to find your screenshot locally and add it. A thumbnail will be created and added to the upper right corner of the project page once you submit your changes.

If you need to change the image you have uploaded, click the thumbnail on your project page (this takes you to the image node) and then click the Edit tab. You may then upload a new picture which will replace the existing one.

Note that this method of thumbnail placement is quite different from the method listed here previously. That old method (linking to the CVS version) will no longer work. This new method does not require site admin intervention to add and change pictures.

Adding your theme to Drupal.org

To add your theme to Drupal.org, it must be GPL'd. Do not include images or other copyrighted works that you do not want to see re-used or otherwise altered.

Themes are tracked the same way that code is, in the CVS repository. You will need to apply for a CVS account. Once you are approved, you will be able to check your theme into the Drupal CVS repository. Create a project and the download will be created for it automatically.

If you do add your theme, users will likely post suggestions, file bugs, and generally desire that you keep the theme up to date with current versions of Drupal.

Also read the screenshot guidelines.

You can find out more about the process of contributing code and themes and maintaining a project on Drupal.org here in the Developers handbook.