mozilla

Revision 54548 of Writing forward-compatible websites

  • Revision slug: Web_development/Writing_forward-compatible_websites
  • Revision title: Writing forward-compatible websites
  • Revision id: 54548
  • Created:
  • Creator: Bzbarsky
  • Is current revision? No
  • Comment 58 words added

Revision Content

This is a list of best practices for creating websites that do not break when browsers are updated.  It's not always possible to follow all of these, but following as many of them as possible as

Prefix all global variable access in event handler content attributes with window.

When an event handler content attribute (onclick, onmouseover, and so forth) is used on HTML element, all name lookup in the attribute first happens on the element itself, then on the element's form if the element is a form control, then on the document, and then on the window. For example, if you have this markup:

<div onclick="alert(ownerDocument)">Click me</div>

then clicking on the text will alert the ownerDocument of the div. This will happen even if there is a var ownerDocument declared in global scope.

What this means is that any time you access a global variable in an event handler content attribute, including calling any function declared globally, you can end up with a name collision if a specification adds a new DOM property to elements or documents. If that happens, then suddenly your function will stop being called. This has happened multiple times to various sites already during the evolution of HTML5.

To avoid this, fully qualify global variable access, like so:

<script>
  function localName() {
    alert('Function localName has been called');
  }
</script>
<div onclick="window.localName()">Clicking me should show an alert<div>

Note that removing "window." in the example above completely changes the behavior in this case.

Don't assume that sniffing a particular object or capability implies anything about the presence or absence of other objects, capabilities, or bugs

If you plan to use some feature, use object-detection to sniff for that exact feature, if possible.  As a simple example, don't assume that any browser in which "filter" in body.style tests true must be Microsoft Internet Explorer and have a window.event available in event handlers. Don't assume that browsers with support for a given DOM feature must also have some other, especially nonstandard, DOM feature. Or that they don't have support for some other feature (e.g. don't assume that a browser that supports onload on script elements will never support onreadystatechange on them). As browsers converge behavior, they will both add features and remove them. They will also fix bugs.  All three of these have happened in the past and will happen again.

Don't UA-sniff

This is really a particularly common instance of assuming that one feature (the presence of a particular substring in the UA string) implies something about the presence or absence of other features.

If you have to UA-sniff, assume unknown and future UAs have the desired capability

If you have to resort to UA sniffing, assume that the browsers you haven't tested with are at least as standards-compliant as the ones you did test with.  Don't lock out unknown browsers or future versions of existing browsers by default.

Don't target hacks at future versions of browsers

This is also a common instance of assuming that present correlation between bugs implies future correlation between bugs.  Targeting hacks at old versions of browsers that no longer have the bug you're relying on for your hack is OK: once a browser has fixed bug X, you can know for certain that all releases that had bug X also had bug Y and use the presence of bug X to target workarounds for bug Y.

Avoid depending on cutting-edge nonstandard features

Even if the feature is prefixed, using it could be dangerous: as the specification evolves the browser's prefixed implementation can likewise change to track the specification. And once the feature is standardized, the prefixed version will likely be removed.

When using cutting-edge features (even standard ones) that are not universally implemented, make sure to test fallback paths

Make sure to test what happens in a browser that doesn't implement the feature you're using, especially if you don't use such a browser day-to-day while working on the site.

Don't use vendor-prefixed features except to target old buggy versions

Vendor-prefixed features can change behavior in future releases.  Once a browser has shipped a feature unprefixed, however, you can use the prefixed version to target old releases by making sure to always use the unprefixed version of the feature when available.  A good example, for a browser vendor using the -vnd CSS prefix that has shipped an unprefixed implementation of the make-it-pretty property, with a behavior for the value "sometimes" that differs from the prefixed version:

<style>
  .pretty-element {
    -vnd-make-it-pretty: sometimes;
    make-it-pretty: sometimes;
  }
</style>

The order of the declarations in the rule above is important: the unprefixed one needs to come last.

Don't use unprefixed versions of CSS properties or APIs until at least one browser supports them

Until there's decently widespread support of the unprefixed version of something, its behavior can still change in unexpected ways.  Most especially, don't use the unprefixed version if no browser actually supports it.

Don't unnecessarily create separate codepaths for different browsers

Don't go out of your way to run different code based on either object detection or UA sniffing if one of the codepaths involved actually works in all browsers.  There is a good chance of browsers changing behavior to converge with each other and hence breaking one of the codepaths that didn't use to work in all browsers to start with.

Avoid missing >

Passing a validator is one way to ensure this, but even if your website doesn't validate entirely you should make sure all your > characters are present. Missing those can lead to unexpected situations due to a following tag name being treated as an attribute on a previous tag. This can work for a bit, then break if a specification attaches a meaning to that attribute. Here's an example that works in browsers without HTML5 support but breaks in a browser supporting HTML5:

<form action="http://www.example.com">
  <input type="submit" value="Submit the form"
</form>

due to the missing > on the input tag.

Don't leave experiments that didn't work in your code

If you try using a CSS property to do something you want, but it has no effect, remove it.  It might start doing something you don't expect in the future.

Don't concatenate scripts you don't control

The "use strict;" directive in ECMAScript, when used on the file level, applies to everything in the file. So appending a script that depends on non-strict-mode behavior to a strict-mode script will cause things to break.

Ask the authors of any JavaScript libraries you use to also follow these guidelines

Unfortunately, libraries have a strong tendency to violate many of them.

Revision Source

<p>This is a list of best practices for creating websites that do not break when browsers are updated.  It's not always possible to follow all of these, but following as many of them as possible as</p>
<h2>Prefix all global variable access in event handler content attributes with <code>window.</code></h2>
<p>When an event handler content attribute (<code>onclick</code>, <code>onmouseover</code>, and so forth) is used on HTML element, all name lookup in the attribute first happens on the element itself, then on the element's form if the element is a form control, then on the document, and then on the window. For example, if you have this markup:</p>
<pre>&lt;div onclick="alert(ownerDocument)"&gt;Click me&lt;/div&gt;</pre>
<p>then clicking on the text will alert the <code>ownerDocument</code> of the <code>div</code>. This will happen even if there is a <code>var ownerDocument</code> declared in global scope.</p>
<p>What this means is that any time you access a global variable in an event handler content attribute, including calling any function declared globally, you can end up with a name collision if a specification adds a new DOM property to elements or documents. If that happens, then suddenly your function will stop being called. This has happened multiple times to various sites already during the evolution of HTML5.</p>
<p>To avoid this, fully qualify global variable access, like so:</p>
<pre>&lt;script&gt;
  function localName() {
    alert('Function localName has been called');
  }
&lt;/script&gt;
&lt;div onclick="window.localName()"&gt;Clicking me should show an alert&lt;div&gt;</pre>
<p>Note that removing "<code>window.</code>" in the example above completely changes the behavior in this case.</p>
<h2>Don't assume that sniffing a particular object or capability implies anything about the presence or absence of other objects, capabilities, or bugs</h2>
<p>If you plan to use some feature, use object-detection to sniff for that exact feature, if possible.  As a simple example, don't assume that any browser in which <code>"filter" in body.style</code> tests true must be Microsoft Internet Explorer and have a <code>window.event</code> available in event handlers. Don't assume that browsers with support for a given DOM feature must also have some other, especially nonstandard, DOM feature. Or that they don't have support for some other feature (e.g. don't assume that a browser that supports <code>onload</code> on script elements will never support <code>onreadystatechange</code> on them). As browsers converge behavior, they will both add features and remove them. They will also fix bugs.  All three of these have happened in the past and will happen again.</p>
<h2>Don't UA-sniff</h2>
<p>This is really a particularly common instance of assuming that one feature (the presence of a particular substring in the UA string) implies something about the presence or absence of other features.</p>
<h2>If you have to UA-sniff, assume unknown and future UAs have the desired capability</h2>
<p>If you have to resort to UA sniffing, assume that the browsers you haven't tested with are at least as standards-compliant as the ones you did test with.  Don't lock out unknown browsers or future versions of existing browsers by default.</p>
<h2>Don't target hacks at future versions of browsers</h2>
<p>This is also a common instance of assuming that present correlation between bugs implies future correlation between bugs.  Targeting hacks at <em>old</em> versions of browsers that no longer have the bug you're relying on for your hack is OK: once a browser has fixed bug X, you can know for certain that all releases that had bug X also had bug Y and use the presence of bug X to target workarounds for bug Y.</p>
<h2>Avoid depending on cutting-edge nonstandard features</h2>
<p>Even if the feature is prefixed, using it could be dangerous: as the specification evolves the browser's prefixed implementation can likewise change to track the specification. And once the feature is standardized, the prefixed version will likely be removed.</p>
<h2>When using cutting-edge features (even standard ones) that are not universally implemented, make sure to test fallback paths</h2>
<p>Make sure to test what happens in a browser that doesn't implement the feature you're using, especially if you don't use such a browser day-to-day while working on the site.</p>
<h2>Don't use vendor-prefixed features except to target old buggy versions</h2>
<p>Vendor-prefixed features can change behavior in future releases.  Once a browser has shipped a feature unprefixed, however, you can use the prefixed version to target old releases by making sure to always use the unprefixed version of the feature when available.  A good example, for a browser vendor using the <code>-vnd</code> CSS prefix that has shipped an unprefixed implementation of the <code>make-it-pretty</code> property, with a behavior for the value <code>"sometimes"</code> that differs from the prefixed version:</p>
<pre>&lt;style&gt;
  .pretty-element {
    -vnd-make-it-pretty: sometimes;
    make-it-pretty: sometimes;
  }
&lt;/style&gt;</pre>
<p>The order of the declarations in the rule above is important: the unprefixed one needs to come last.</p>
<h2>Don't use unprefixed versions of CSS properties or APIs until at least one browser supports them</h2>
<p>Until there's decently widespread support of the unprefixed version of something, its behavior can still change in unexpected ways.  Most especially, don't use the unprefixed version if no browser actually supports it.</p>
<h2>Don't unnecessarily create separate codepaths for different browsers</h2>
<p>Don't go out of your way to run different code based on either object detection or UA sniffing if one of the codepaths involved actually works in all browsers.  There is a good chance of browsers changing behavior to converge with each other and hence breaking one of the codepaths that didn't use to work in all browsers to start with.</p>
<h2>Avoid missing <code>&gt;</code></h2>
<p>Passing a validator is one way to ensure this, but even if your website doesn't validate entirely you should make sure all your <code>&gt;</code> characters are present. Missing those can lead to unexpected situations due to a following tag name being treated as an attribute on a previous tag. This can work for a bit, then break if a specification attaches a meaning to that attribute. Here's an example that works in browsers without HTML5 support but breaks in a browser supporting HTML5:</p>
<pre>&lt;form action="http://www.example.com"&gt;
  &lt;input type="submit" value="Submit the form"
&lt;/form&gt;
</pre>
<p>due to the missing <code>&gt;</code> on the <code>input</code> tag.</p>
<h2>Don't leave experiments that didn't work in your code</h2>
<p>If you try using a CSS property to do something you want, but it has no effect, remove it.  It might start doing something you don't expect in the future.</p>
<h2>Don't concatenate scripts you don't control</h2>
<p>The <code>"use strict;"</code> directive in ECMAScript, when used on the file level, applies to everything in the file. So appending a script that depends on non-strict-mode behavior to a strict-mode script will cause things to break.</p>
<h2>Ask the authors of any JavaScript libraries you use to also follow these guidelines</h2>
<p>Unfortunately, libraries have a strong tendency to violate many of them.</p>
Revert to this revision