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.