As you work on and develop your own WordPress themes, you will no doubt discover that life will go much smoother if you debug and validate at each step of your theme development process. The full process will pretty much go like this: Add some code, check to see the page looks good in Firefox, validate, then check it in IE and any other browsers you and your site’s audience use, validate again if necessary, add the next bit of code… repeat as necessary until your theme is complete.
Don’t Forget About Those Other Browsers and Platforms
I’ll mostly be talking about working in Firefox and then ‘fixing’ for IE. This is perhaps, unfairly, assuming you’re working on Windows or a Mac and that the source of all your design woes will (of course) be Microsoft IE’s fault. You must check your theme in all browsers and if possible, other platforms, especially the ones you know your audience uses the most.
I surf with Opera a lot and find that sometimes JavaScripts can ‘hang’ or slow that browser down, so I debug and double-check scripts for that browser. I’m a freelance designer and find a lot of people who are also in the design field use a Mac (like me), and visit my sites using Safari, so I occasionally take advantage of this and write CSS that caters to the Safari browser. (Safari will interpret some neat CSS 3 properties that other browsers don’t yet.)
Generally, if you write valid markup and code that looks good in Firefox, it will look good in all the other browsers (including IE). Markup and code that goes awry in IE is usually easy to fix with a work-around.
Firefox is a tool, nothing more! Firefox contains features and plug-ins that we’ll be taking advantage of to help us streamline the theme development process and aid in the validation and debugging of our theme. Use it just like you use your HTML/code editor or your image editor. When you’re not developing, you can use whatever browser you prefer.
Introduction to Debugging
Have a look at our initial work-flow chart.
I was insistent that your work-flow pretty much be as edit -> check it -> then go back and edit some more. The main purpose of visually checking your theme in Firefox after adding each piece of code is so that you can see if it looks OK, and if not, immediately debug that piece of code. Running a validation check as you work just doubly ensures you’re on the right track.
So, your work-flow really ends up looking something more like this:
You want to work with nice, small pieces or ‘chunks’ of code. I tend to define a chunk in XHTML markup as no more than one div section, the internal markup, and any WordPress template tags it contains. When working with CSS, I try to only work with one id or class rule at a time. Sometimes, while working with CSS, I’ll break this down even further and test after every property I add to a rule, until the rule looks as I intend and validates.
As soon as you see something that doesn’t look right in your browser, you can check for validation and then fix it. The advantage of this work-flow is you know exactly what needs to be fixed and what XHTML markup or PHP code is to blame. All the code that was looking fine and validating before, you can ignore. The recently added markup and code is also the freshest in your mind, so you’re more likely to realize the solution needed to fix the problem.
If you add too many chunks of XHTML markup or several CSS rules before checking it in your browser, then discover something has gone awry, you’ll have twice as much sleuthing to do in order to discover which (bit or bits) of markup and code are to blame. Again, your fail-safe is your backup.
You should be regularly saving backups of your theme at good stable stopping points. If you do discover that you just can’t figure out where the issue is, rolling back to your last stable stopping point and starting over might be your best bet to getting back on track.
Here, you’ll primarily design for Firefox and then apply any required fixes, hacks, and workarounds to IE. You can do that for each piece of code you add to your theme. As you can see in the preceding figure, first check your theme in Firefox and if there’s a problem, fix it for Firefox first. Then, check it in IE and make any adjustments for that browser.
At this point, you guessed it, more than half of the debugging process will depend directly on your own eyeballs and aesthetics. If it looks the way you intended it to look and works the way you intended it to work, check that the code validates and move on. When one of those three things doesn’t happen (it doesn’t look right, work right, or validate), you have to stop and figure out why.
Troubleshooting Basics
Suffice to say, it will usually be obvious when something is wrong with your WordPress theme. The most common reasons for things being ‘off’ are:
- Mis-named, mis-targeted, or inappropriately-sized images.
- Markup text or PHP code that affects or breaks the Document Object Model (DOM) due to being inappropriately placed or having syntax errors in it.
- WordPress PHP code copied over incorrectly, producing PHP error displays in your template, rather than content.
- CSS rules that use incorrect syntax or conflict with later CSS rules.
The first point is pretty obvious when it happens. You see no images, or worse, you might get those little ugly ‘x’d’ boxes in IE if they’re called directly from the WordPress posts or pages. Fortunately, the solution is also obvious: you have to go in and make sure your images are named correctly if you’re overwriting standard icons or images from another theme. You also might need to go through your CSS file and make sure the relative paths to the images are correct.
For images that are not appearing correctly because they were mis-sized, you can go back to your image editor, fix them, and then re-export them, or you might be able to make adjustments in your CSS file to display a height and/or width that is more appropriate to the image you designed.
Don’t forget about casing! If by some chance you happen to be developing your theme with an installation of WordPress on a local Windows machine, do be careful with the upper and lower casing in your links and image paths. Chances are, the WordPress installation that your theme is going to be installed into is more likely to be on a Unix or Linux web server. For some darn reason, Windows (even if you’re running Apache, not IIS) will let you reference and call files with only the correct spelling required. Linux, in addition to spelling, requires the upper and lower casing to be correct. You must be careful to duplicate exact casing when naming images that are going to be replaced and/or when referencing your own image names via CSS. Otherwise, it will look fine in your local testing environment, but you’ll end up with a pretty ugly theme when you upload it into your client’s installation of WordPress for the first time (which is just plain embarrassing).
For the latter two points, one of the best ways to debug syntax errors that cause visual ‘wonks’ is not to have syntax errors in the first place (don’t roll your eyes just yet).
This is why, in the last figure of our expanded work-flow chart, we advocate you to not only visually check your design as it progresses in Firefox and IE, but also test for validation.
Why Validate?
Hey, I understand it’s easy to add some code, run a visual check in Firefox and IE, see everything looks OK, and then flip right back to your HTML editor to add more code. After-all, time is money and you’ll just save that validation part until the very end. Besides, validation is just icing on the cake. Right?
The problem with debugging purely based on visual output is, all browsers (some more grievously than others) will try their best to help you out and properly interpret less than ideal markup. One piece of invalid markup might very well look OK initially, until you add more markups and then the browser can’t interpret your intentions between the two types of markup anymore. The browser will pick its own best option and display something guaranteed to be ugly.
You’ll then go back and futz around with the last bit of code you added (because everything was fine until you added that last bit, so that must be the offending code) which may or may not fix the problem. The next bits of code might create other problems and what’s worse that you’ll recognize a code chunk that you know should be valid! You’re then frustrated, scratching your head as to why the last bit of code you added is making your theme ‘wonky’ when you know, without a doubt, it’s perfectly fine code!
The worst case scenario I tend to see of this type of visual-only debugging is that the theme developers get desperate and start randomly making all sorts of odd hacks and tweaks to their markup and CSS to get it to look right.
Miraculously, they often do get it to look right, but in only one browser. Most likely, they’ve inadvertently discovered what the first invalid syntax was and unwittingly applied it across all the rest of their markup and CSS. Thus, that one browser started consistently interpreting the bad syntax! The theme designer then becomes convinced that the other browser is awful and designing these non-WYSIWYG, dynamic themes is a pain.
Avoid all that frustration! Even if it looks great in both browsers, run the code through the W3C’s XHTML and CSS validators. If something turns up invalid, no matter how small or pedantic the validator’s suggestion might be (and they do seem pedantic at times), incorporate the suggested fix into your markup now, before you continue working. This will keep any small syntax errors from compounding future bits of markup and code into big visual ‘uglies’ that are hard to track down and troubleshoot.
PHP Template Tags
The next issue you’ll most commonly run into is mistakes and typos that are created by ‘copying and pasting’ your WordPress template tags and other PHP code incorrectly. The most common result you’ll get from invalid PHP syntax is a ‘Fatal Error.’ Fortunately, PHP does a decent job of trying to let you know what file name and line of code in the file the offending syntax lives (yet another reason why I highly recommend an HTML editor that lets you view the line number in the Code view).
If you get a ‘Fatal Error‘ in your template, your best bet is to open the file name that is listed and go to the line in your editor. Once there, search for missing < ?php ? > tags. Your template tags should also be followed with parenthesis followed by a semicolon like ( ) ; . If the template tag has parameters passed in it, make sure each parameter is surrounded by single quote marks, that is,
template_tag_name('parameter name', 'next_parameter');.
CSS Quick Fixes
Last, your CSS file might get fairly big, fairly quickly. It’s easy to forget you already made a rule and/or just accidentally create another rule of the same name. It’s all about cascading, so whatever comes last, overwrites what came first.
Double rules: It’s an easy mistake to make, but validating using W3C’s CSS validator will point this out right away. However, this is not the case for double properties within rules! W3C’s CSS validator will not point out double properties if both properties use correct syntax. This is one of the reasons why the !important hack returns valid. (We’ll discuss this hack just a little further down in this article under To Hack or Not to Hack.)
Perhaps you found a site that has a nice CSS style or effect you like, and so you copied those CSS rules into your theme’s style.css sheet. Just like with XHTML markup or PHP code, it’s easy to introduce errors by miscopying the bits of CSS syntax in. A small syntax error in a property towards the bottom of a rule may seem OK at first, but cause problems with properties added to the rule later. This can also affect the entire rule or even the rule after it.
Also, if you’re copying CSS, be aware that older sites might be using depreciated CSS properties, which might be technically OK if they’re using an older HTML DOCTYPE, but won’t be OK for the XHTML DOCTYPE you’re using.
Again, validating your markup and CSS as you’re developing will alert you to syntax errors, depreciated properties, and duplicate rules which could compound and cause issues in your stylesheet down the line.
Advanced Troubleshooting
Take some time to understand the XHTML hierarchy. You’ll start running into validation errors and CSS styling issues if you wrap a ‘normal’ (also known as a ‘block’) element inside an ‘in-line’ only element, such as putting a header tag inside an anchor tag (<a href, <a name, etc.) or wrapping a div tag inside a span tag.
Avoid triggering quirks mode in IE! This, if nothing else, is one of the most important reasons for using the W3C HTML validator. There’s no real way to tell if IE is running in quirks mode. It doesn’t seem to output that information anywhere (that I’ve found). However, if any part of your page or CSS isn’t validating, it’s a good way to trigger quirks mode in IE.
The first way to avoid quirks mode is to make sure your DOCTTYPE is valid and correct. If IE doesn’t recognize the DOCTYPE (or if you have huge conflicts, like an XHTML DOCTYPE, but then you use all-cap, HTML 4.0 tags in your markup), IE will default into quirks mode and from there on out, who knows what you’ll get in IE.
My theme stopped centering in IE! The most obvious thing that happens when IE goes into quirks mode is that IE will stop centering your layout in the window properly if your CSS is using the margin: 0 auto; technique. If this happens, immediately fix all the validation errors in your page. Another big obvious item to note is if your div layers with borders and padding are sized differently between browsers. If IE is running in quirks mode it will incorrectly render the box model, which is quite noticeable between Firefox and IE if you’re using borders and padding in your divs.
Another item to keep track of is to make sure you don’t have anything that will generate any text or code above your DOCTYPE.
Firefox will read your page until it hits a valid DOCTYPE and then proceed from there, but IE will just break and go into quirks mode.
Fixing CSS Across Browsers
If you’ve been following our debug -> validate method described in the article, then for all intents and purposes, your layout should look pretty spot-on between both the browsers.
Box Model Issues
In the event that there is a visual discrepancy between Firefox and IE, in most cases it’s a box model issue arising because you’re running in quirks mode in IE. Generally, box model hacks apply to pre IE 6 browsers (IE 5.x) and apply to IE6 if it’s running in quirks mode. Again, running in quirks mode is to be preferably avoided, thus eliminating most of these issues. If your markup and CSS are validating (which means you shouldn’t be triggering quirks mode in IE, but I’ve had people ‘swear’ to me their page validated yet quirks mode was being activated), you might rather ‘live with it’ than try to sleuth what’s causing quirks mode to activate.
Basically, IE 5.x and IE6 quirks mode don’t properly interpret the box model standard and thus, ‘squish’ your borders and padding inside your box’s width, instead of adding to the width as the W3C standard recommends.
However, IE does properly add margins! This means that if you’ve got a div set to 50 pixels wide, with a 5 pixel border, 5 pixels of padding, and 10 pixels of margin in Firefox, your div is actually going to be 60 pixels wide with 10 pixels of margin around it, taking up a total space of 70 pixels..
In IE quirks mode, your box is kept at 50 pixels wide (meaning it’s probably taller than your Firefox div because the text inside is having to wrap at 40 pixels), yet it does have 10 pixels of margin around it. You can quickly see how even a one pixel border, some padding, and a margin can start to make a big difference in layout between IE and Firefox!
