Organizing your theme files in Drupal

When working on a large Drupal site, your theme can become quite complicated with dozens of templates or template overrides, images, css files, javascript files and even a massively large template.php file. Sometimes all these files will get dumped into the root of the folder making specific files difficult to find.

Here are some best practices when organizing your theme folder to make things easier to find.

CSS, Javascript and Images

Keep these files in separate folders like so:

theme-name/js/
theme-name/css/
theme-name/images/

or you may want to organize them into an assets folder like this:

theme-name/assets/js/
theme-name/assets/css/
theme-name/assets/images/

Template Files

Put all your template files into a templates directory, then further separate them by the base template type (ie. page, node, block, view). Here is how that might look.

theme-name/templates/page/page.tpl.php
theme-name/templates/page/page-front.tpl.php
theme-name/templates/node/node.tpl.php
theme-name/templates/node/node-blog.tpl.php
theme-name/templates/views/views-view.tpl.php
theme-name/templates/views/views-view-fields--directory.tpl.php
theme-name/templates/views/views-view-field--user-list.tpl.php
theme-name/templates/block/block.tpl.php
theme-name/templates/block/block-footer.tpl.php
theme-name/templates/block/block-login.tpl.php

It is important to remember when do this that, in order for Drupal recognize the location of your templates, the core base file must first be present. For example, the node.tpl.php file, must be in your node/ folder before any other node type derivative templates will be recognized.

template.php

If your template.php file becomes a monstrosity, you may want to split it up into multiple files. You can do this by simply creating new files to move your code into and adding the necessary PHP require statement to the top of your template.php file.

Here is how you would change your template.php file

<?php
require "template-overrides.php";
require "template-preprocess.php";
// Whatever code you want to stay in template.php
?>

And here is what your filesystem would look like

theme-name/template.php
theme-name/template-overrides.php
theme-name/template-preprocess.php

Comments

U have to go in the admin and

U have to go in the admin and rescan the themes list.

Themeing the Contact Form

I am themeing the contact form and have created the file contact-mail-page.tpl and want to place it in my sub-folder theme-name/templates, Since the contact module is one of those exceptions to the rules where it doesn't register/implement hook_theme and doesn't have a core .tpl.php file, I don't know what other core base file to include with it in the sub-folder, if any. The only way the core can find the file is if I place it in my theme-name folder. It can't find it in the sub-folder. See below.

warning: include(./sites/all/themes/ori/contact-mail-page.tpl.php) [function.include]: failed to open stream: No such file or directory in /home/drupal/public_html/includes/theme.inc on line 1066.
warning: include() [function.include]: Failed opening './sites/all/themes/ori/contact-mail-page.tpl.php' for inclusion (include_path='.:/usr/lib/php:/usr/local/lib/php') in /home/drupal/public_html/includes/theme.inc on line 1066.

Is there a way to overcome this?

Thanks in advance.

Subtheme?

Is this a template you have registered yourself?

If you are using a subtheme, you might need to include the contact-mail-page.tpl in the templates folder of your parent theme. That's mostly a stab in the dark though.

Putting template files in folders - views exception

Thanks for the article - I thought you had to keep everything in the root folder.

However - 'core' template files of views don't have to be created and copied to a new subfolder eg (as per example above) : theme-name/templates/views/views-view.tpl.php -

see: http://drupal.org/node/457740

Organizing the templates

Nice article!! Thank you very much.

I have written a way to organice your node templates for full and teaser node views.

You can read it at: http://drewpull.drupalgardens.com/content/theming-node

My 2 cents.