Discovering and Working with Template Suggestions in Drupal
August 09, 2019


Custom website theme development in Drupal 7 is, basically, where you define how each element and part of the website will look to the end user. This is done via manipulating theme files and writing our own custom web theming code in HTML, CSS, and JavaScript.

Luckily for us, Drupal is a well organized framework and provides template files on the level of fields, nodes, pages, as well as modules and others. This way you can override only the parts you need and benefit from all the default standards compliant output Drupal provides.

To delve deeper into tailoring website themes in Drupal 7 please check the elaborate Theming Drupal 7 Guide on their official website.

In this post, we cover a simple tip for Drupal theme developers to help them discover which theme files they can create in their custom theme template.

What are Template Suggestions

Template suggestions are alternate templates based on existing .tpl.php files. These suggestions can be used when a specified condition is met and the suggested template exists.

For example, if you create a file named page.tpl.php and place it into your theme's templates folder, Drupal will use that file instead of its default one for all pages. If you create a file named page--front.tpl.php now Drupal will use that page template for the home page specifically and the previous one for all the other pages.

You can see how powerful and well organized the system is. The only thing that remains is discovering how you can tell which template file names (suggestions) are available. Read on.

Enabling Theme Debug Mode

As of Drupal 7.33 we have a theme debug mode available in core. This mode can be used to see possible template suggestions and the locations of template files right in your HTML code as HTML comments.

To enable debug mode, open your settings file in "/sites/default/settings.php" and append the below line to it. Keep in mind that you might need to make this file writable beforehand. Do also make sure to remove or comment out this flag once you're done debugging.

$conf['theme_debug'] = TRUE;

Sample Debug Output

Below is a sample debug output you can see after the website renders. It basically lists all the template suggestions from the most specific to the least specific and marks with an "x" the one that was chosen to render this specific field for example. We recommend using the "inspect element" functionality in your browser's developer tools on the element you need to theme. You'll find the debug output section written on top of your element.

<!-- THEME DEBUG -->
<!-- CALL: theme('field') -->
   * field--field-image--slide.tpl.php
   * field--slide.tpl.php
   x field--field-image.tpl.php
   * field--image.tpl.php
   * field.tpl.php

Drupal Development Open Source

Share this post

Written by
Mario Awad

Founder of SOFTKUBE, lead developer, and getting things done addict. Passionate about open source, user interface design, business development, and the tech world.

More about Mario Awad


A small team of experts developing simple, usable, and high-quality web solutions. We blog about business, entrepreneurship, web development, and technology.

More about us

Recent Posts

Custom Theme Migration from Drupal 9 to Drupal 10

How to Change the Most Recent Git Commit Message

How to Make Google Chrome Forget a Permanent HTTP 301 Redirect

Finding and Fixing Unintended Body Overflow to Remove Horizontal Scrollbars

View all posts

All Posts Categories

Business Cheat Sheets CLI Design Development Downloads Drupal Email Google Apps HID Keyboards Multilingualism Open Source Philosophy PHP Pointing Devices Productivity Quotes Science Security SEO Technology Thoughts Windows Zend Framework