Warning message

Documentation is currently being migrated into the new system. Some pages might be temporarily missing, and some guides might appear empty. Thank you for your patience while we are improving Drupal.org documentation.

Overriding themable output

Last updated on
September 19, 2016 - 08:16

Depending on how your site is configured, the HTML code that makes up each page in your site is compiled from the output of various Drupal modules.

About modifying HTML markup

If the default HTML markup supplied by any module does not suit the requirements of your theme, you can override some or all of it, so that the resulting page is exactly what you need for your design.

For example, you might decide that for your site, the default search box should have an image of a magnifying glass and that the label on the search button should read "Discover great stuff!" rather than the default label of "Search". You can completely override the default markup, so that the markup calls for your image file and that the button is labeled the way you want.

Don't hack core

It's very important to understand the concept of "overriding". While it is technically possible to just find the module responsible for the search field and edit the code directly, this is definitely NOT recommended. In the short term, it will seem to solve your problem, but it will soon make it difficult to keep your site up to date. Whenever you update the module, perhaps for a general security release, you would need to remember to redo any of your customizations.

How to change HTML the Drupal way

The "Drupal Way" is to do an override. This involves four basic steps:

  1. Locate the module responsible for the markup
  2. Do one of the following:
    • If the module provides a template (tpl.php file), copy the template to your theme directory. See Core Templates and Suggestions for a list of core templates. OR...
    • In the module code, identify the theme or preprocess function that is generating the markup you want to change and copy the function to your theme's template.php file. You will need to change the "theme_" or "template_" prefix to match the name of your theme. For example, "theme_breadcrumb" would become "mythemename_breadcrumb"; "template_preprocess_page" would become "mythemename_preprocess_page".
  3. Within the copied function or template, change the HTML code to suit your needs.
  4. Refresh the theme cache.

The About overriding themeable output page provides a more in-depth look at overriding Drupal's default markup and the underlying system that makes it possible.

These steps are explained in greater detail in the following pages.

Using PHP for theming

If you are not already familiar with PHP, the process might seem somewhat intimidating, but it generally does not require that you understand anything about actually writing PHP. As long as you know what HTML you want to be displayed, it's simply a matter of modifying that part of the code. As with any theming work, you should not make changes to a live or production site until you have thoroughly tested the changes on a development site.

Overriding CSS

Many modules also provide style sheets (.css files) which specify the default look and feel of the markup. These style sheets can also be overridden. For more information, see Overriding style sheets from modules and base themes.

Popular Contributed Modules that override the default HTML output

Some contributed modules have their own theming guides. Also see overriding style sheets from modules and base themes.

Modules for which theming-specific documentation exists are listed below by Drupal version.

Drupal 7–compatible modules