Gecko Compatibility Handbook

** Notes ** - The Solution Quick Reference needs more attention. - I'm also looking for a way to organize all that information. - Some inline examples were removed because of technical limitations. They are actually replaced by ''-(EXAMPLE REMOVED)-'' The goal of this handbook is to help you update websites to work with standards-based browsers and properly detect Gecko.

If you're new to standards, you may find Using Web Standards in Your Web Pages a helpful introduction.

Gecko is an embeddable browser, developed as part of the Mozilla open source project and based on W3 Standards rather than the proprietary approaches of the past. Adhering to web standards simplifies cross-browser web development and enables accessibility.

4.x vs. Gecko

Since 1997, much of the Web's content has been developed for Microsoft Internet Explorer 4 or Netscape Navigator 4. These browsers were developed before the relevant W3C recommendations for HTML, CSS, and the DOM existed.

These earlier, non-standards based browsers differed in several ways from Gecko:

  • These browsers use proprietary (non-standard) HTML, CSS, and JavaScript.
  • Internet Explorer 4 and Netscape Navigator 4 share support for a large part of the HTML 3.2 standard and basic JavaScript.
  • While they support the CSS 1 standard to some degree, the implementations are not complete and have non-standard features added.
  • Neither Internet Explorer 4 or Netscape Navigator 4 support the W3 DOM. Instead, each browser supports its own proprietary API for manipulating the content, style and position of HTML Elements in a web page.
  • In addition, Internet Explorer 4 and Netscape Navigator 4 use completely different methods of embedding third-party software into the browser.

Gecko is a cross-platform browser engine, compatible with a number of Windows versions including Windows XP, as well as Mac and Linux. Because of Gecko's cross-platform nature, functionality is generally very much the same on different platforms unlike Internet Explorer for Mac and IE for Windows, which are very different programs and so may behave quite differently from each other.

Quick Compatibility Test

If your site uses Netscape 4.x and Microsoft proprietary technologies, see Using Web Standards in Your Web Pages for a quick tutorial on standards. This compatibility test will be most beneficial to sites using simple code or that have updated to support standards.

Set Up Browsers For Testing

The various Gecko-based browsers do not always contain <tt>Netscape</tt> in the user-agent string. Thus it's critical to verify that you are properly detecting browsers such as AOL for Mac OS X.

You can either download the various browsers. Or, if you are using user-agent detection, you can install an extension in Firefox or Mozilla which allows you to "spoof" the user-agent strings of the various Gecko browsers. Here's how:

  1. Launch Mozilla or Firefox. The benefit of using these browsers is that if you're only detecting <tt>Netscape</tt> or <tt>Netscape6</tt> you'll see the issues right away.
  2. Install the User Agent Switcher extension.
  3. After restarting your browser, add the the user-agent strings that you want to test to the list (<tt>Tools | User Agent Switcher | Options | Options... | User Agents | Add...</tt>). Once you filled the dialog box (it should look like the screenshot below), click OK and close the Options dialog.

    Image:GeckoCompatibilityHandbook-Configure-UASwitcher.PNG
  4. You can now start using the user-agent string you've just created by clicking <tt>Tools | User Agent Switcher | The name you have chosen</tt>. You can verify the string got changed by looking under <tt>Help | About</tt>.

You can find the user agent strings of many Gecko-based browsers here. If possible, also download the actual clients (Netscape, AOL, CompuServe) for testing.

Review Your Results

The following scenarios all relate to browser detection. For more solutions to common problems please continue reading this handbook.

Problem: Site supports standards but does not look right

Try picking the Internet Explorer 6 user-agent string. If this works, set up your detection to serve IE 6 content to visitors with <tt>Gecko</tt> in their user-agent strings. IE 6.x is actually more similar to Gecko browsers than Netscape 4.x is to Gecko, due to increased support of W3C standards.

Problem: Site certified on Netscape 6.x looks incorrect in other browsers

If your site is already Gecko-compatible, try switching back to a Netscape 6 user-agent string. If it looks OK, you're probably detecting only <tt>Netscape</tt> or <tt>Netscape6</tt>. Detecting <tt>Gecko</tt> instead is the easy way to fix this as well as accomodate users of Mozilla, CompuServe 7, etc. (Related article)

Problem: Site has problems in all Gecko-based browsers

If you are still seeing problems, take a look at the troubleshooting section of this handbook. Also if you're using Netscape 4.x and Microsoft proprietary technologies, see Using Web Standards in Your Web Pages for a quick tutorial on what's different in Gecko.

AOL or CompuServe Problems

Even if your site works on Netscape 7.x, it is important to test your site in AOL for Mac OS X and CompuServe 7 to check for browser detection and network issues.

Testing AOL From Within a Firewall

If you need to connect to AOL via a corporate firewall, America Online has registered TCP/IP ports 5190 and 11523 so you can communicate with the AOL client software. This way you can test your site on the AOL client from behind your firewall, provided that your network administrators will open these ports.

You need to be connected to the Internet to test your site on AOL; it isn't possible to access your site on a local machine via your LAN, without an Internet connection. See Webmaster@AOL for further information.

Solution Quick Reference

As discussed in Mozilla's Using Web Standards in Your Web Pages, coding for cross-browser compatibility requires you write standard markup that Gecko-based browsers, Netscape 4, and IE browsers can render properly.

Symptom Possible Problem Solution
Site works correctly in Netscape 6.x but not Netscape 7.x or other browsers based upon Gecko. The browser detection JavaScript detects Netscape 6.x but does not detect other Gecko-based browsers.
  • Upgrade the browser detection JavaScript to detect "Gecko." (related article)
Content differs in Gecko browsers and Internet Explorer Use of proprietary or invalid markup (such as is generated by some Microsoft Office applications).
  • Use the W3 HTML and CSS Validator Tools to validate the web page. Correct any errors and replace proprietary code wherever possible.
  • Upgrade web authoring tool to versions that support the W3 standards and Gecko browsers
Content differs in Gecko browsers and Internet Explorer The JavaScript Console in Netscape 6.x and Netscape 7.x displays errors about document.all, document.layers, document.<property> not being defined because of an incorrect browser sniffing, or use of proprietary JavaScript.
  • Update browser sniffing to correctly detect Gecko browsers.
  • Upgrade APIs to use newer standards-conformant versions
  • Upgrade web authoring tool to versions that support the W3 standards and Gecko browsers
Content differs in Gecko browsers and Internet Explorer
  • Your CSS relies on bugs in Internet Explorer's implementation of CSS.
  • Internet Explorer incorrectly treats ID's and CLASS names as case insensitive while Gecko treats them correctly as case sensitive. Inconsistent case between the CSS defining the style for HTML ID's and CLASSes results in Gecko browsers not applying the styles to ID's or CLASS names that differ in case.
  • Internet Explorer incorrectly specifies height and width of inline elements such as SPAN.
  • Internet Explorer implements the box model (padding, margins, borders) incorrectly.
  • Do not use Internet Explorer's invalid implementation of CSS. Use only the cross-browser, standards conformant features of CSS. Use consistent case when writing HTML ID and CLASS name attributes and CSS Styles for those IDs and CLASSes. Do not specify heights or widths on inline elements such as SPANs. Use only cross-browser box specifications for margins, padding and borders. (more about CSS)
Content differs in Gecko browsers and Internet Explorer Incorrect Layout mode specified by DOCTYPE.
  • If pages should be displayed by legacy browsers such as Netscape Navigator 4 or Internet Explorer 4 and 5, be sure to specify Quirks mode layout via the DOCTYPE.
Images are laid out without intervening blank areas in Interent Explorer but display blank areas between the images in Gecko browsers. Incorrect Layout mode specified by DOCTYPE.
  • Standards Mode Layout has been specified by the DOCTYPE. Change the DOCTYPE to request Quirks mode layout instead. more info
Clicking a link results in a 404-Page not found but works in Internet Explorer The link may use an invalid form of a relative URL.
Clicking on a link displays a "download" or displays HTML code instead of rendering the page correctly, but works as expected in Internet Explorer The Web Server has incorrectly specified the MIME type for the content. Internet Explorer tries to guess the MIME type of documents while Gecko browsers relies upon the Web Server to specify the correct MIME type. Gecko does not try to 'sniff' the MIME type for a document in order to reduce the possibility of unsecure, dangerous content masquerading as as a safe MIME type.
  • Use Perl's HEAD utitility to determine the actual MIME type being used by the Web Server. Correct any incorrect Server MIME types. (related article)
Stylesheet is not being recognized The presence of the title attribute in a link element that references an external stylesheet can cause the stylesheet may be causing the external stylesheet to be ignored.
  • Make sure that any stylesheet which should always be applied is persistent instead of preferred. (related article)
Connecting to a secure site fails, but connects in Internet Explorer The Web Server does not properly implement the fall back negotiation for SSL.
  • The Web Server administrator needs to upgrade the SSL software. In order to use a site with a defective implementation of SSL, visitors need to disable TLS in their Netscape 6/7 or Mozilla browser until the site has upgraded to software that correctly implements SSL.
DHTML Menus implemented using HierMenu have problems The HierMenu version is obsolete. The earliest version of HierMenu only supported Netscape Navigator 4.x and Internet Explorer 4.x and above. Later versions did support Netscape 6; however, in Netscape 6.1 and higher, support for Internet Explorer's proprietary offsetXXX properties results in HierMenu placing popups in the wrong position. The most recent versions of HierMenu fully support all Gecko-based browsers.
  • Upgrade to the most recent version of HierMenu

Common Coding and Server Problems

This section details solutions to the most common problems affecting standards-based browsers as well as issues that may specifically affect Gecko browsers.

Proprietary HTML

Problem: Using Browser-Specific Proprietary HTML Markup (such as <tt><LAYER></tt>).

Since a browser is supposed to ignore HTML tags it does not recognize and render the content inside the tags, web page authors have used the technique of combining proprietary HTML that will work as expected in each browser.

Gecko browsers will ignore both Internet Explorer and Netscape Navigator 4 proprietary HTML tags. So, a page may not display in Gecko browsers as it does in Internet Explorer 4 or in Netscape Navigator 4.

The prime example of this is the use of Netscape Navigator 4 proprietary <tt><LAYER></tt>, commonly used in site navigation. For standards-based alternatives, see Updating DHTML Web Pages for Next Generation Browsers.

An HTML page can be quickly checked for the use of proprietary HTML Markup by submitting the page to the W3's HTML Validator using the HTML 4.01 DOCTYPE. We will have more to say about DOCTYPEs later in this article, but essentially the DOCTYPE is supposed to indicate to a browser what version of HTML is used in the page.

The HTML Element Cross Reference provides a list of all HTML Elements supported in Netscape 4, Gecko browsers, Internet Explorer 4 and up and can be used to determine which HTML Elements are supported by all browsers.

Browser Detection

Problem: Faulty Browser Detection or Sniffing

While browser detection is useful in enabling authors to code pages that work only in specific browsers, improper browser detection can lead to major user experience breakages.

Many problems can occur when a web page uses browser detection to determine which proprietary features to use for a particular browser.

Please see the Browser Detection and Cross Browser Support article for a better approach to detecting browsers.

Browser-specific Workarounds

Problem: Code includes workarounds for bugs and browser-specific quirks.

Since a Web page is judged not by how well it is written but by how well it displays in a browser, authors have developed many techniques which take advantage of idiosyncracies in particular browsers to achieve the desired effect. This is of particular importance since the early implementations of CSS found in Internet Explorer 4 and Netscape Navigator 4 had many bugs. In order to achieve the desired effects on a page, authors wrote HTML and JavaScript which depended upon these bugs in order to work properly.

This can cause problems in Gecko browsers since it implements the standards strictly. The old "code to the bugs" approach will not work for Netscape 6.x, Netscape 7.x and other Mozilla based browsers.

Example - Putting forms in Tables

Invalid HTML to eliminate line break in <tt><FORM></tt>.

In older browsers, this results in the TD cell tightly wrapping around the input element.

<table border="1">
 <tr>
  <form name="form2">
   <td>
    <input type="text">
   </td>
  </form>
 </tr>
<table>

This approach is commonly used to get around the fact that <tt><FORM></tt> is a block level element in HTML and will naturally begin on a new line in the page. Unfortunately, this is invalid HTML and can cause problems both when parsing the page and when applying the CSS styles.

Incorrect Use of XML Empty Tag notation

Many authors have taken to using XML Empty tag notation (<tt><tag /></tt>) in their HTML files. In XML, an Empty tag never has any content. The XHTML backward compatibility guidelines state that Empty Elements can be coded by following the tag name with a space followed with as slash as in <tt><tag /></tt>. To be backwardly compatible you must have a space before the trailing <tt>/></tt>. In addition, you must only use the XML Empty tag notation for HTML Elements that are always Empty - and not for HTML Elements that have optional ending tags.

For example, it is ok to code <tt><br></tt> as <tt><br /></tt> although there is no benefit to do so in HTML documents. But it is not OK to code <tt><option></tt> as <tt><option /></tt>. To understand why, consider the following:

HTML without optional ending tagsEquivalent HTML with optional ending tags
<select>
<option>OptionValue
</select>
<select>
<option>OptionValue</option>
</select>

Now consider if we used the XML Empty tag notation: the <tt><option /></tt>.

HTML with XML Empty Tag notation Equivalent HTML with ending tags
<select>
<option />OptionValue
</select>
<select>
<option></option>OptionValue
</select>

This is simply not correct. If you must use the XML Empty tag notation, then only do so for HTML Elements that never have any content - not for HTML Elements that have optional ending tags.

CSS ID's should be case-sensitive

Gecko implements the case sensitivity of Class ID's correctly and will display this example correctly. However Internet Explorer treats all CSS ID's as case-insensitive and will not display this example correctly.

<style type="text/css">
  #id1 { text-decoration: line-through; }
  #ID1 { text-decoration: underline; }
</style>
<div id="id1">
  should be line-through
</div>
<div id="ID1">
  should be underline
</div>

-(EXAMPLE REMOVED)-

Note that the W3C's HTML Validator will flag HTML ID attributes as duplicates if they only differ due to case. There appears to be some inconsistency between the actual HTML 4.01 Recommendation and the SGML declaration for HTML on whether ID attributes are case sensitive or not. This is unfortunate since the HTML Validator is one of the primary vehicles web developers have for learning about the standards.

Due to the common nature of this error, Netscape 6.2 began treating CSS ID attributes as case-insensitive in Quirks mode only. If you are invoking Standards mode, you should still code your CSS to be consistent with respect to case.

CSS Class names should be case-sensitive
<style type="text/css">
  .class1 { font-size: 1em; }
  .CLASS1 { font-size: 2em; }
</style>
<div>
<div class="class1">
  should be font-size: 1em;
</div>
<div class="CLASS1">
  should be font-size: 2em;
</div>

-(EXAMPLE REMOVED)-

Gecko implements the case sensitivity of Class names correctly and will display this example correctly while Internet Explorer treats all CSS Classnames's as case-insensitive and will not display this example correctly.

Due to the common nature of this error by web authors, Netscape 6.2 began treating CSS Class attributes as case-insensitive in Quirks mode only. If you are invoking Standards mode, you should still code your CSS to be consistent with respect to case.

Incorrect Relative URLs

A Relative URL is one which refers to the same web server where a web page is hosted. A Relative URL that refers to a path relative to the directory where a Web page is located looks like <tt>path/file.html</tt>. Relative URLs that refer to a path relative to the web server's root directory look like <tt>/path/file.html</tt>.

Older browsers supported the invalid use of <tt>http://path/</tt> for URLs relative to a web server's root directory but Gecko browsers do not. To correctly specify a web page relative to a web server's root directory, use URLs of the form <tt>/path/file.html</tt>.

Invalid use of spaces in name Attributes (such as image maps)

Many authors seem to be infected by a penchant to use spaces in names. A name or id attribute in HTML 4.01 may not legally contain spaces. This can cause problems with Gecko-based browsers, especially in image maps. You should make sure that your name attributes are coded using valid characters only.

Bad Code Due to Old APIS and Tools

Problem: Obsolete APIs or web authoring tools generate non-standard code.

Many older versions of cross-browser APIs in common use around the web such as DYNAPI do not support Gecko for one or more of the reasons listed above. This is also the case for older versions of web authoring tools such as Macromedia's Dreamweaver 2 and 3.

Newer versions of these APIs and tools do support Gecko however. For example, DYNAPI is now maintained at SourceForge and offers a Gecko-compatible version. Newer versions of web authoring tools support Gecko.

Wrong DOCTYPE

Problem: An incorrect DOCTYPE can completely alter a page's presentation.

Gecko, Internet Explorer for Mac OS and Internet Explorer 6 all use a technique called DOCTYPE sniffing to determine if a page is to be laid out in a fashion compatible with the older browsers or if it is to be laid out in a fashion compatible with the W3 standards.

Using the appropriate DOCTYPE in an HTML document allows a web page author to continue to support the older, less compliant browsers while also supporting the newer, more compliant browsers by specifiying special Quirks mode layout via the DOCTYPE. As time progresses and the older browsers drop in market share, web page authors can transition to standards-based layout by using the appropriate DOCTYPE. (related article)

While DOCTYPE sniffing is a useful means of continuing to support the older browsers, it can be a problem for newer browsers such as Netscape 6.x and Netscape 7.x if an inappropriate layout mode is specified.

Gecko has two layout modes: Quirks and Standard. Quirks mode mimics the behavior of Netscape Navigator 4 while Standards mode follows the W3C Recommendations for HTML and CSS. In particular, Standards Layout Mode uses the CSS Box Model as defined in Chapter 10 of the CSS 2 Recommendation. The mode is picked based on the DOCTYPE declaration (or the lack thereof) at the beginning of an HTML document.

Invalid Comments

Gecko also has three parsing modes: Quirks, Almost Standards, and Standards. Quirks mode allows the use of invalid comments containing two dashes -- while Standards and Almost Standards modes do not.

<!---- This is an invalid HTML Comment accepted in Quirks Comment Parsing ---->
<!-- This is a valid HTML Comment accepted in Stricts Comment Parsing -->

For the exact rules on which DOCTYPEs invoke Quirks vs. Standards mode see Mozilla's DOCTYPE sniffing article.

Plugins Coding

You'll find for that some plugins behave differently in Gecko than in Netscape Navigator 4. Visit the Plugins page to learn about scripting Gecko browsers, proper use of tags, changes in the plugin architecture vs. the Netscape 4 generation, and suggested plugin strategies.

Web Server Configuration Problems

Incorrectly specified MIME types

Many Web servers have incorrectly specified MIME types for files. Gecko browsers require that the server specifies the correct MIME type to match the content type:

  • HTML - text/html
  • CSS - text/css (related article)
  • XML - text/xml
  • SVG - image/svg+xml

Faulty implementations of HTTP

Several Web Servers incorrectly implement the HTTP protocol which can result in problems for Netscape 6.

Faulty implementations of SSL

Older browser such as Internet Explorer 4 and Netscape Navigator 4 implemented older versions of the Secure Sockets Layer (SSL) protocol. The most common version of SSL on the web today is SSL 3.0, however the newest version TLS (SSL 3.1), which is supported by Gecko browsers is not supported by many Web Servers today. Unfortunately, several implementations of SSL 3.0 incorrectly implement the negotiation of which version of SSL to use and fail to connect to Gecko browsers.

For more detail on this issue, please read Notes on TLS - SSL 3.0 Intolerant Servers.

Useful Resources

References

Original Document Information

  • Last Updated Date: August 16th, 2002
  • Copyright © 2001-2003 Netscape. All rights reserved.

Document Tags and Contributors

 Last updated by: Mgjbot,