Compatibility Mode: What Any XPages (or Web Developer) Needs To Know

  |   Blog   |   4 Comments

This rant is not the result of any individual project,I’ve been meaning to write it for a while. It’s also as much out of disillusionment of believing web developers who say you can switch off compatibility mode, because it’s not what happens necessarily.

When developing for a corporate environment, the default browser is usually Internet Explorer. Internet Explorer has always required a lot of hacks, so much so that in the past traditional Domino web applications for internal use were sometimes designed only for IE. But in the XPages world (or most web development that uses some kind of framework), mostly we don’t have to worry about those hacks any more.


But we still have to deal with one abomination (sorry, but it’s so horrendous I cannot bring myself to use anything more polite).

Often there are policies in place to force intranet sites into Compatibility Mode. So as a web developer, you developer and test against a proper browser – one that has proper developer tools to help you diagnose problems, not something that’s just called Developer Tools. Then you come to look at it on Internet Explorer…and weep!

Because you realise that in the post-IE6 world, modern web development uses techniques such as float to position content. But there are other aspects as well, as you’ll see. You realise the cause of your woes is that IE9 is running compatibility mode. So you’ve been developing a web application that should look like this, and does look this in any other browser.

IE9 NonCompat

But certain bits of functionality and look and feel don’t work quite how they should. That’s because it’s forced into Compatibility Mode. So the Browser Mode shows as IE9 Compat View, the Document Mode as IE7 standards (“standards”!), and the user cannot change it out of Compatibility Mode, as you see below:

IE9 Compat

But thankfully a quick search of the internet gives a host of experts who tell you how to switch compatibility mode off.

Or so you think.

You’ve probably seen the code. So on an XPage, the beforeRenderResponse would set a header:

<xp:this.beforeRenderResponse><![CDATA[#{javascript:if (context.getUserAgent().isIE(7,11)) {
var exCon = facesContext.getExternalContext();
var response = exCon.getResponse();
response.setHeader("X-UA-Compatible", "IE=edge");

The isIE parameters may vary and IE=edge is not recommended (that forces it into the most recent for the relevant IE version, which you may not have tested). But whatever the parameters that are chosen and regardless of what people tell you, it doesn’t switch off Compatibility Mode.

It changes the Document Mode, but leaves Compatibility Mode switched on.

And that’s not the same. If you want proof, compare the screenshot below to the first screenshot. This app had the code above. I defy anyone to claim it looks the same.

IE9 standards

The ideal solution would be that, if companies still need a Internet Explorer in Compatibility Mode for legacy intranet applications, deploy that but also deploy a modern browser for modern Domino XPages applications within the intranet. Or better still, ensure those legacy applications are displayed in Compatibility Mode either by adding code to force Compatibility Mode or getting users to change it.

Otherwise, the cost and the pain of supporting legacy intranet applications burdens modern developers.

AUTHOR - Paul Withers

Paul Withers is an IBM Lifetime Champion, has been an OpenNTF Board Member since 2013, has worked with Domino since R4.5, XPages since 2009, co-authored XPages Extension Library and was technical editor for Mastering XPages 2nd Edition. He is one of the developers on OpenNTF Domino API as well as contributor to a variety of other OpenNTF projects. For full bio, see

  • Tatu Lappeteläinen | Feb 19, 2014 at 3:20 pm

    We use response.setHeader(“X-UA-Compatible”, “IE=8”); and set the !DOCTYPE to HTML5 to deal with IE’s Compatibility Mode.

    • paulwithers | Feb 19, 2014 at 7:25 pm

      Thanks, I wasn’t aware of that. Unfortunately, although the DOCTPE in the source HTML changes, it doesn’t seem to stop compatibility mode or alter the different display I see.

  • Per Henrik Lausten (@perlausten) | Feb 19, 2014 at 3:27 pm

    Paul, great explanation.

    I have created a simple custom control that displays a warning message if compatibility mode is turned on:

  • Joe Brender | Sep 16, 2014 at 1:07 pm

    Thanks for the rant. I am dealing with the same issue today and I’m right there with you!

    Of course, I build apps in a real browser, so by the time I get around to testing in IE, I’ve got a lot of code written and time invested. I do use doctype of html5 by default, since Bootstrap somewhat requires it, and it doesn’t address the compatibility mode issue.

Post A Comment