For the sake of simplicity, I’ve made the process of debugging and validation a separate chapter. However, as you continue working and develop your own Joomla! templates, you will discover that life is much smoother if you debug and validate at each step of your template-development process. The full process will pretty much go like this: add some code; check to see if the page looks good in Firefox; check it in IE; make sure the page validates with W3C; if so, add next bit of code and repeat as necessary.
We’re going to cover the basic techniques of debugging and validation that you should be employing throughout your development process. We’ll dive into the W3C’s XHTML and CSS validation services, look at using Firefox’s JavaScript/Error console for robust debugging, and introduce you to the Firebug extension. I’ll also give you a little troubleshooting insight as to some of the most common reasons due to which “good code goes bad”, especially in IE and the various ways to remedy the problems.
Remember our initial work-flow chart in Chapter 3?
Figure 4.1 Basic Work Flow
I was insistent that your work flow be pretty much like this: edit -> check it -> then go back and edit some more. The main purpose of checking your template after adding each piece of code is of course to see if it looks OK and, if not, immediately debug that piece of code.
So your work flow really ends up looking something similar to the following:
Figure 4.2 Expanded Workflow
You want to work with nice, small pieces or chunks of code. As soon as you see that something in your browser isn’t looking right, you can check for validation and then fix it. The advantage of this workflow is that you know exactly what needs to be fixed and what code is to be blamed. You can ignore all the code that was looking fine and validating before. The recently added 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 code before checking it in your browser and then discover something has gone awry, you’ll have twice as much sleuthing to do in order to discover which bits of code are to be blamed. Again, your fail-safe is your backups.
You should be regularly saving backups of your template 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.
As mentioned in Chapter 3, you’ll primarily design for Firefox and then apply any required fixes, hacks, and workarounds to IE. You’ll do that for each piece of code you add to your template. As shown in Figure 4.1, first check your template 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, works the way you intended it to work, check that the code validates and move on. When one of these 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 template. The most common reasons for things being wrong are:
Images are misnamed, mistargeted, or sized inappropriately.
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.
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 boxes marked with the x symbol in IE if they’re called directly from the CMS. 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 template. 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 sized inappropriately, you can go back to your image editor and fix them by re-exporting 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.
Note
Don’t forget about casing! Chances are you’re developing your template with an installation of Joomla! on a local Windows machine with a server installed or a test server like RJS. But the actual Joomla! installation that your template is going to be installed into is more likely to be on a 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 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 template when you upload it into your client’s installation of Joomla! 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 Figure 4.2, we advocate you to not only visually check your design as it progresses in Firefox and IE, but also test for validation.
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. Hey, “time is money” and you’ll just save that validation part until the very end. After all, that’s just “icing on the cake”, right?
The problem with debugging purely based on the visual output is, all browsers (some more grievously than others) will try their best to help you 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 play 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 is 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 template “wonky” when you know, without a doubt, it’s perfectly fine code!
The worst case scenario seen in this type of visual-only debugging is that template developers get desperate, and randomly start making all sorts of odd hacks and tweaks to their markup and CSS to make it look right.
Miraculously, they often manage to make it 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, one browser started consistently interpreting the bad syntax! The template designer is then convinced that the other browser isn’t good, and designing these non-WYSIWYG, dynamic templates is quite problematic.
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 trouble shoot.
Last, your CSS file might get fairly big, fairly quickly. It’s easy to forget that you have already created a rule and accidentally create another rule of the same name. It’s all about cascading, so whatever comes later overwrites what came first.
Note
Double rules: You’ll remember that we ran into this issue with the original rhuk template in Chapter 3. The author had two body rules, and we had to troubleshoot this before we could get the background color changed. 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.
Perhaps you found a site that has a nice CSS style or effect that you like and so you copied those rules into your template’s CSS. It’s easy to introduce errors by wrongly copying in bits of code. A small syntax error in a property towards the bottom of a rule may seem OK at first, but might 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 style sheet 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” element inside an “in-line” only element such as putting a header tag inside an anchor tag (<a href, <a name, and so on) 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 DOCTYPE is valid and correct. If IE doesn’t recognize the DOCTYPE or if you have huge conflicts like an XHTML DOCTYPE, and you use all-cap HTML 4.0 tags in your markup, IE defaults into quirks mode and from there on who knows what you’ll get in IE.
Note
My template 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 validation errors in your page. Another obvious item is to note 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 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. The only item that should be placed above that item in your template is the <?php defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' ); ?> code we discussed in Chapter 3.
Firefox will read your page until it hits a valid DOCTYPE and then proceed from there, but IE will break and go into quirks mode.
If you’ve been following our debug->validate method described earlier, then for all intents and purposes, your layout should look pretty spot-on between both browsers.
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 IE 6 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 we’ve had people “swear” to us that their page validated yet quirks mode was being activated), you might “live with it” rather than trying to sleuth what’s causing quirks mode to activate.
Basically, IE 5.x and IE 6 quirks mode, don’t properly interpret the box-model standard, and thus “smush” 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 10px 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 of 70 pixels of space.
In quirks mode IE, your box is kept at 50px wide (so that it’s probably taller than your Firefox div because the text inside is wrapping 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!
Figure 4.3 Firefox box model (left) and quirks mode IE box model (right)
Almost everyone is now using IE 6 (and probably 7), and we find that as long as we stay in strict mode and not fall into quirks mode, we don’t have too many issues with box-model rendering. Occasionally, we still notice that relative (% or .em) values render a little differently for our properties, but that’s not box model, so much as
what the two browsers consider, say, 20% to be in pixels. Even so, as long as your layout doesn’t look weird, it’s generally OK if you’re template’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.
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 IE 5.x for Windows), then it’s time for some hacks.
The cleanest hack is the !important, hack, which we briefly reviewed in Chapter 3 when the original rhuk designer used it in his CSS. We like it because it lets our CSS still render as valid. However, you should note that the !important value is valid syntax and meant to be used as an accessibility feature of CSS. It’s not a value that was ever meant to affect design. The fact is that IE does not recognize it is a bug and though it’s very simple and easy to implement, it is not recommended to be used liberally as a design fix. The understanding is that 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). The thing is, all 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 the following:
.classRule{
height: 100px !important;
height: 98px;
}Firefox and all other browsers will read the value with the !important value after it as though 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 here: http://www.info.com.ph/~etan/w3pantheon/style/starhtmlbug.html.
Be aware that these 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. At this time, we’re still using IE6 and you must chose to use these three hacks at your discretion.
Your best bet is again, not to use hacks and create alternatives to using a box-model hack. This can be achieved in a couple of ways. A good one is to break your XHTML markup down a little more so that it’s in more controllable chucks. For instance, instead of one div layer:
<div id="leftSide">...</div>
This div layer has the following assigned rule:
#leftSide{
width: 200px;
border: 2px;
padding: 10px;
}This is clearly going to give you problems in quirks mode IE, because the div will stay at 200 pixels wide and “smush” your border and padding inside it, it would be better to tuck an extra div or other XHTML element inside the leftSide id as follows:
<div id="leftSide"><div>...</div></div>
Then, you can control the width and borders much more accurately using CSS that looks like the following:
#leftSide{
width: 200px;
}
#leftSide div{
border: 2px;
padding: 10px;
}By using a fix like this, your div will always be 200 pixels wide, despite the border and padding, in all browsers, regardless of quirks mode. Plus, your XHTML markup and CSS stays valid.
Note
Container divs: We find working with CSS and XHTML markup in this way 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 our design or maybe just decide to add them later. In browsers like Firefox, a miscalculation or late addition like that will throw our columns off, especially if their containing div is set to an exact width. This results in ugly, stacked columns. We like to use clean containing divs to only control our placement, width, and margins. Then, we 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.
You can set your own main container divs in your template and then load in your Joomla! modules using the -2 property in your mosLoadModules PHP Code. This will let you control exact placement with your own divs and then style the internal Joomla! output divs. You can have even more divs to work with in your Joomla output if you use the -3 property as specified in Chapter 3.
Your final alternative is to just create two uh-hacked style sheets for your template 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 can then call this specific IE style sheet code below which will load additionally only if the browser is IE.
In the IE style sheet, you’ll duplicate the rules and correct the properties that were not looking correct in Firefox. Because this style sheet will load underneath your main style sheet, any duplicated rules will overwrite the original rules in your first style sheet. 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 of the double rules.
In your index.php template, add this code after your full style sheet call:
<!--[if IE]>
<link rel="stylesheet" type="text/css" href="ie-fix.css"
media="screen, projection" />
<![endif]-->Note
Is that a conditional comment?
Yes it is. In the past, your best bet to load in the proper style sheet would have been using a server-side script to detect the browser with something like PHP. You could use a JavaScript as well, but if someone had JavaScript disabled in their browser, it wouldn’t work. Not everyone can be a PHP whiz, hence, we advocate the method above for loading in your two style sheets with minimal hassle. The above method is also the best for keeping your two style sheets as simple as possible (having a main one, then one with IE fixes). However, you can apply all sorts of control to the conditional comment above, giving you quite a bit of power in how you dole out your CSS. For instance, you can specify what version of IE to check for IE 5, IE 6, or IE 7, you can also inverse the condition and only load in the CSS if the browser is not IE, by placing another ! exclamation point in front of the IE, for example: <! [if !IE]> ...<![endif]>. Learn all about this conditional CSS tag at http://www.quirksmode.org/css/condcom.html.
You have to add that code in the template index.php file. We would prefer something like this could be implemented in 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 template’s index.php file.
Also, please note that we advocate using the @import method for bringing in style sheets but that method will not work within the <![if IE]> CSS check. Use the standard link import tags used above.
Note
CSS trouble-shooting 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. You’ll notice we did this to our initial layout in Chapter 3. 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 we 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 back in line. Using Firebug? Firebug will outline your CSS-defined elements for you. Read on to find out more about this great Firefox extension.
You’ll want to always validate your XHTML first. This is just as well since 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. If you’re working locally from your browser, you’ll need to Save Page As, and save an HTML file of your template with Joomla! output and upload that full output to the validator using the upload field provided.
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!
Figure 4.4 Validated XHTML
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.
Figure 4.5 Validated CSS
Here you’ll want to see another screen with a green bar that says Congratulations! No Error Found.
Figure 4.6 Errors found in XHTML
If you entered or uploaded your XHTML and you didn’t get a screen with a green bar, you’ll have to scroll down below the red bar and take a look at what errors were reported.
In our example, 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 these 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 grave that it will block other errors from being picked up until it’s fixed. Always validate -> fix -> validate, until you get that green bar telling you that you’re good to move on.
Note
Where’s My Error? The validator tells us which line the offensding 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 template is pulling in content from the CMS, the offending line of code is not necessarily the same code line in your template anymore. So where’s the error? We work around this by copying some unique text from the error, in our 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.
Once your XHTML validates, you can move on to checking your CSS.
Figure 4.7 Errors found in CSS
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 offending code line. This is handy as your style sheet is not affected by the Joomla! CMS output so you can go right to the line mentioned and make the suggested fix.
Perhaps you’ve discovered (because you are talented indeed and would find something like this) that your XHTML and CSS validate, yet somehow something is still wrong with your layout. Or maybe, you’re using some special JavaScripts to handle certain aspects or features of your template. W3C’s XHTML and CSS tools won’t validate JavaScript. If you find yourself in this situation you will have to dig a little deeper to get to the root of the problem or make sure all aspects (like JavaScripts) of your template are valid.
You can use Firefox’s JavaScript/Error Console (called the JavaScript Console in 1.x and Error Console in 2.x) to debug and validate any JavaScripts your template is using. Go to Tools | Error Console in your browser to activate it. You can also activate it by typing javascript: into your address bar and hitting Enter on your keyboard.
Figure 4.8 Errors found in Console
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 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 that you can go right to it and make the suggested fix.
A more robust tool is Joe Hewitt’s Firebug extension for Firefox at http://www.getfirebug.com/.
This extension will find them all: XHTML, CSS, JavaScript, and even little weird tid-bit things happening to your DOM (Document Object Model) on the fly. There are a variety of fun inspectors, and just about all of them are invaluable.
Once you have Firebug installed into your browser, you can turn it off and on by hitting F12 or going to View | Firebug.
Our favorite is the options available for CSS. Firebug will show you your box models with different colored shading and let you see the measurements of each edge. Moreover, 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.
Figure 4.9 Errors found in FireBug
Note
DOM: We’ve mentioned the DOM a few times in this book, learning about the Document Object Model can really enhance your understanding of your XHTML templates (or any web page you design) as well as help you in having a better understanding of how to effectively structure your CSS rules and write cleaner, accurate JavaScripts. Find out more from the W3Schools at http://w3schools.com/htmldom/default.asp.
If you want a better understanding of how all-text browsers or users on mobile devices are viewing your site, you can use Google’s mobile viewing tool to give you an idea. This may help you visualize how to better arrange your site semantically for users in these categories.
You’ll now be able to see how your complete site looks without CSS styling, and you can even turn off images. Use this if you think that your Joomla! content is loading in logically and in the order of importance you prefer for your viewers (that is semantically). Also keep in mind this is very similar to how a search engine bot will crawl your page from top to bottom, and thus the order in which the content will be indexed.
In this chapter we reviewed the basic wash -> rinse -> repeat process to debugging and validating your template’s code. You learned how to use the W3C’s XHTML and CSS validation tools and we further explored the value of using Firefox as a valuable development tool using its JavaScript Console and Firebug extension.
Next, it’s time to package up your design and send it to your client. Get ready to look at some XML.