A Beginners Guide to Drupal Overrides


The problem with many software applications is you can’t make them your own. With Drupal, however, you have the option to override how Drupal does things. From altering a form to customizing the way your pages are displayed, Drupal provides options.

The concept of overriding something in Drupal can be made reality in several ways: Drupal’s APIs, theme overrides, as well as overriding default configurations in modules. Whatever it is you need to do, the number one rule you should endeavor to follow is: don’t hack the core (or a contributed module). Don’t open the code files in Drupal and change them to meet your needs. There are better ways.

In this tutorial, we will focus on overriding themes.

What are Drupal themes?


When someone talks about a Drupal theme, they are likely referring to the files of code bundled together and installed in the themes directory on your site. The theme ‘code,’ however, is not always located in the specific theme directory.

Consider the screenshots above. On the left are the files contained in the Stark theme (a theme that ships with Drupal 7). Observe that the Stark theme does not have any files that end with tpl.php. Why does this matter? Because it’s the files that end with tpl.php that contain the HTML markup and PHP that make your webpages. There are several tpl.php files: html.tpl.php, page.tpl.php, node.tpl.php, block.tpl.php, etc. (When you have finished reading this tutorial, visit https://drupal.org/node/171194 for a visual depiction of the common tpl.php files and their purpose.)

In the right screenshot are the directories and files contained in the Bartik theme. Observe that the Bartik theme has a directory called templates. In that directory are files ending with tpl.php. (The next screenshot below shows the contents of the template directory.)

Question: How is it possible that Stark works without tpl.php files and Bartik has a directory with several?
Answer: Because “theme” in Drupal is not only pertain to the files within the theme directory.

Where are Drupal themes?


The screen shot on the left lists the files and directory located in the node module, a core module located in the root modules directory. Notice that it contains a file called node.tpl.php. The node.tpl.php file contains the HTML markup that renders the node within the page that is displayed in your browser.

On the right is the template directory for the Bartik theme. Notice it contains five tpl.php files, including the node.tpl.php. You might be wondering why the Bartik theme has the node.tpl.php when the Stark theme does not. The answer is simple, the Bartik theme is overriding Drupal’s default node.tpl.php file and the Stark theme is not.

How is this possible? That’s the cool part. When a visitor to your site requests a page, let’s say http://example.com/about-us, Drupal goes to work trying to find out what that page needs to look like. Amongst all the decisions it needs to make, based on your configurations, Drupal needs to know the HTML, PHP, CSS, etc. needed to present About Us as you planned.

  • First it looks to the theme files. The theme files might be located in the root themes directory because you are using Bartik, Stark, or Garland. Or the theme files could be located in a directory at sites/all/themes/zeropoint, assuming you are using the Zero Point theme.
  • If Drupal is trying to render a block for your About Us page and the theme you are using does not have the tpl.php that tells Drupal the markup, Drupal will go to the core block module and use the default block.tpl.php file located there.
  • If Drupal is trying to display something (a page, a block) created by a contributed module, it will look to see if the module is providing the tpl.php. For example, if you have Views installed, take a look at the templates included in the module.

Overriding core or contributed displays


As we mentioned earlier, the Bartik theme is overriding Drupal’s default node.tpl.php file (as well as four others). Let’s see what this might look like. First, the developer of the Bartik theme copied the default node.tpl.php file into the Bartik theme template directory. Then she/he made the changes.

The screenshots compare the default node.tpl.php with Bartik’s node.tpl.php. As you can see, Bartik has made some changes to the existing markup and added new markup.


Please note that Bartik is not overriding Drupal’s configuration options, such as those found with a content type’s manage display. That type of override is another discussion and … in my humble opinion … should be avoided. Let layout modules such as Display Suite and your theme CSS manipulate the display of your node elements.

If you are interested in overriding, or enhancing, a feature managed by one of Drupal’s core modules (or a contributed module), visit https://drupal.org/documentation/develop.


0 0 votes
Article Rating
Notify of
1 Comment
Inline Feedbacks
View all comments
9 years ago

Fantastic Thx 🙂

Would love your thoughts, please comment.x