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.
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.
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.
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.
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!
Everything Is Relative
Most Windows users are still predominately using IE 6 (and IE7 is gaining). When it comes to validating and debugging for IE, I find that as long as I stay in strict mode and not fall into quirks mode, I don't have too many issues with box model rendering. Occasionally, I still notice that relative CSS values such as % or .ems render a little differently, but that's not box model, so much as what the two browsers interpret, say, 20% to be in pixels. Even so, as long as your layout doesn't look weird, it's generally OK if your theme's container divs are a hair wider in one browser over the other. If you're using relative values to measure everything out, your placement will stay intact.
What are the major browsers? According to W3schools, at the time of this writing, IE6 and IE7 together make up a little over half of the total users. Firefox comes in second. Use this link to keep up on browsing trends: http://www.w3schools.com/browsers/browsers_stats.asp.As I mentioned at the beginning of this article, you still need to look and make sure your site is rendering properly in as many browsers as you have access to. As a bonus, if you have access to multiple platforms (like Linux or Mac, if you're on a PC), it's good to check and see how popular browsers who have distributions for those OSs look on them too. If you're using valid markup, you'll be pleasantly surprised to find out that your site looks great in all sorts of browsers and platforms. Occasionally, if you run into a situation where something doesn't look right, you can then decide if that browser is critical to your users and if you'd like to fix it.
To Hack or Not to Hack
If for some reason, you feel you know what you're getting into and have intentionally used markup syntax that's triggering quirks mode in IE (or you just can't figure out why, or maybe your client insists on designing for IE5.x for Windows), then it's time for some hacks.
The cleanest hack is the !important hack. I like it because it lets CSS still render as valid. However, you should note that the !important value is the valid syntax and meant to be used as an accessibility feature of CSS. It's not a value that was ever meant to affect the design.
The fact that IE does not recognize it is a bug and though it's very simple and easy to implement, it's not recommended to be used liberally as a design fix. The understanding is, eventually IE will fix this bug so that it adheres to accessibility standards and then your hack will no longer work (especially if IE doesn't change anything about how it runs in quirks mode).
Remember: All CSS hacks rely on exploiting various bugs in IE to some extent and may or may not continue to work with future service patches and upgrades to IE.
To implement the !important hack, take the width, height, margin, or padding property that has the discrepancy in it and double it. Place the value that looks best in Firefox first and add the !important value after it. Then, place the value in the duplicate property that looks best in IE below the first property. You should have something that looks like this:
height: 100px !important;
Firefox and all other browsers will read the value with the !important value after it, as if it were the last value in the rule. IE ignores the !important value and thus regular-old cascading kicks in, so it reads the actual last property value in the rule.
Other IE hacks include using the star selector bug hack (*) and the _ underscore hack (_). Both hacks work on the same general principle as the !important hack, that IE does or doesn't recognize something that all the other browsers do or don't recognize themselves. You can find out more about the underscore hack from WellStyled.com ( http://wellstyled.com/css-underscore-hack.html). A good overview of the star selector bug can be found at Info.com.
Be aware, those last two hacks will show up as validation errors in your CSS. Plus, the star and underscore hacks are rumored to no longer be viable in IE7 (ah! fixing those bugs!). You must choose to use these three hacks at your discretion.
Your best bet is again to not use hacks. This is achieved in a couple of ways. First, you can break your XHTML markup down a little more. That means, for example, instead of one div layer:
...with the assigned rule:
... which is clearly going to give you problems in quirks mode IE, because the div will stay at 200 pixels wide and 'squish' your border and padding inside it, it would be better to tuck an extra div or other XHTML element inside the leftSide id like so:
Then, you can control the width and borders much more accurately using CSS that looks like this:
Using a fix like above, your div will always be 200 pixels wide (despite the border and padding) in all the browsers, regardless of quirks mode. Plus, your XHTML markup and CSS stays valid.
Container divs: I find working with CSS and XHTML markup like this also keeps you from getting into other trouble; let's say we 'do the math' to figure our column widths and margins out, but then, either forget to account for borders and padding in the design or maybe just decide to add them later. In browsers like FireFox, a miscalculation or late addition like that will throw columns off, especially if their containing div is set to an exact width. This results in ugly, stacked columns.When we built the theme mockup, I like to use clean containing divs to only control placement, width, and margins. Then, I let inner divs (which will by default, expand to the width of the containing div) take on borders, padding, and other visual stylings. This is a good way to get your math right and keep it right, no matter what design additions may come later.
Your final alternative is to just create two stylesheets for your theme, one for general browser use and one for IE browsers, and let each browser call them in.
This isn't as bad as it seems. The bulk of your CSS can stay in your main CSS file, you'll then call in this specific IE stylesheet code below which will load additionally, only if the browser is IE.
In the IE stylesheet, you'll duplicate the rules and correct the properties that were not looking correct in Firefox. Because this stylesheet will load in underneath your main stylesheet, any duplicated rules will overwrite the original rules in your first stylesheet. The result is CSS styling that's perfect in Firefox and IE. However, if you run the CSS validator in IE it will alert you to the double rules.
In your header.php, home.php, or index.php template file (whichever file has your <head> tags in it), add the following code after your full stylesheet call:
<link rel="stylesheet" type="text/css" href="ie-fix.css"
media="screen, projection" />
You have to add that code in the theme's template file or files that contain the <head> tags. I usually put it in under my main stylesheet call. Yes, it would be nice if something like this could be implemented into the actual CSS file and then only parts of our CSS would need to be specific, and we'd only need to keep track of one file, but alas, you have to add it to your theme's header.php or files that contain the header tags.
Also, please note that while I advocate using the @import method for bringing in stylesheets, that method will not work within the <![if IE]> CSS check. Use the standard link import tags that are used in this include method above.
CSS troubleshooting technique: The best way to quickly get a handle on a rule that's gone awry is to set a border and general background color to it. Make the color something obvious and not part of your color scheme. Often times, using this technique will reveal quite unexpected results, like showing that a div was inadvertently set somehow to just '500' wide instead of '500px' wide, or perhaps that another div is pushing against it in a way you didn't realize. It will quickly bring to your attention all the actual issues affecting your object's box model that need to be fixed to get your layout backin line.
The Road to Validation
You'll always want to validate your XHTML first. This is just as well because W3C's CSS validator won't even look at your CSS if your XHTML isn't valid.
Go to http://validator.w3.org/ and if your file is on a server, you can just enter in the URL address to it. If you're working locally, from your browser, you'll need to choose Save Page As and save an HTML file of your theme's WordPress output and upload that full HTML file output to the validator using the upload field provided.
In our example above, you can see that we have a typo in one of our divs (looks like an odd s got in there somehow), and we have an image tag that doesn't have the proper closing (/) in it. Wherever possible, you'll note that the validator tries to tell us how to fix the error. Whenever a recommendation is made, go ahead and implement it.
We'll need to fix those two errors and run the validation again to make sure we're now validating. Don't just think you can fix the errors listed and move on without validating again. Occasionally, an error will be so grievous that it will block other errors from being picked up until it's fixed. Always validate -> fix -> validate, until you get that happy green bar telling you that you're good to move on.
Where's My Error? The validator tells us which line the offensive code appears in, which is why we love HTML editors that display the line number to the left in our Code view. However, once your theme is pulling in the content from WordPress, the line the offense appears in is not necessarily the same code line in your specific theme template anymore. So where's the error? Well, you have to know your template files enough to recognize where the error might be, for instance, I know that <div id="footer" > is in my footer.php template file. Once I know the general file, I work around this by copying some unique text from the error, (in my case, s>). You can also use text from an alt or id tag within the reported object. Then, use the Find option in your editor to directly locate the error.
Ideally, when you run your XHTML through the validator, you'll get a screen with a green bar that says This Page Is Valid XHTML 1.0 Transitional!.
You can then move on to checking your CSS.
Open up another tab in your browser and go to http://jigsaw.w3.org/css-validator/. Again, same deal! If you're working off a server, then just enter the address of your CSS file on the development site and check the results. Otherwise, you'll have to use the by File Upload tab and upload a copy of your CSS file.
Here you'll want to see another screen with a green bar that says Congratulations! No Error Found.
If you don't get the green bar, the validator will display the offending error and again offer suggestions on how to fix it. The CSS validator will also show you the line of code the offense takes place on. This is handy as your stylesheet is not affected by WordPress' output, so, you can go right to the line mentioned and make the suggested fix.
You will be pleasantly surprised to find out that the console will also spit out several warnings and errors for CSS rules that the W3C's validators probably didn't tell you about. The Error Console does hold a log of all errors it encounters for all pages you've looked at. Therefore, the best way to proceed with the Error Console is to first hit Clear and then reload your page to be sure that you're only looking at current bugs and issues for that specific page.
Again, the Error Console will let you know what file and line the offending code is in, so you can go right to it and make the suggested fix. In my previous screenshot, it looks like the console is taking issue with the thickbox.css file (Thickbox is a web user interface feature).
The Web Developer's Toolbar
This is a great extension which adds a toolbar to your Firefox browser. The extension is also available for the Seamonkey suite and the new Flock browser, both of which are like Firefox, powered by the open-source code of Mozilla.
Get it from http://chrispederick.com/work/web-developer/.
The toolbar lets you link directly to the DOM browsers and Error Consoles, W3C XHTML and CSS validation tools, toggle and view your CSS output in various ways, as well as just lets you view and manipulate a myriad of information your site page is outputting on-the-fly. The uses of this toolbar are endless. Every time I'm developing a design I find some feature, I'd never previously used, useful.
A more robust tool is Joe Hewitt's FireBug extension for Firefox (there's a 'Firebug Lite' version for Internet Explorer, Safari, and Opera) (http://www.getfirebug.com/)
Linux and Firebug: "Firebug does work on Linux, but some distributions don't compile Mozilla correctly, and it is missing the components that Firebug depends on. Even more common is the case of individual Linux users compiling their own Firefox binaries incorrectly."--Firebug FAQ (http://www.getfirebug.com/faq.html)
Once you have Firebug installed into your browser, you can turn it off and on by hitting F12 or going to View | Firebug.
My favorite Firebug features are the options for reviewing HTML, CSS, and the DOM. Firebug will show you your box models and let you see the measurements of each ledge. Plus, the latest version of Firebug lets you make edits on-the-fly to easily experiment with different fixes before committing them to your actual document. (There are features that let you do this using the Web Developer Toolbar as well, but I find the Firebug interface more in-depth—see the following screenshot.)
In this article, we reviewed the basic process to debugging and validating your theme's XHTML markup, PHP code, and CSS. You learned how to use W3C's XHTML and CSS validation tools. We further explored using Firefox as a valuable development tool by using its Error Console and available extensions like the Web Developer Toolbar and Firebug.