ActiveX Filtering for Developers

May 2nd, 2011

When we introduced ActiveX Filtering with the IE9 Release Candidate, we focused on delivering a great user experience that stays out of the way from regular browsing and makes it easy for users to turn off filtering when they want to. At the same time, we want users to have a great experience viewing Web sites while ActiveX Filtering is enabled. This includes minimizing site compatibility issues and clearly indicating when content on a Web page is blocked by ActiveX Filtering.

In this post, we describe some additions to ActiveX Filtering in the final IE9 release and share some best practices that we encourage Web site developers to follow. Updating Web sites based on these best practices helps maximize the browsing experience with ActiveX Filtering.

msActiveXFilteringEnabled API

Many Web sites display fallback content when they detect that users don’t have ActiveX controls installed. Typically, the sites display a message informing users that they need to install or upgrade an ActiveX control in order to view the content.

When ActiveX Filtering blocks a control from running on a Web site, the site displays the same message to users even though the control is already installed. The site is unable to determine whether the control is not installed or is simply blocked by ActiveX Filtering. Users proceed to re-install or upgrade the control but will eventually see the same message since the control is still blocked.

With the final IE9 release, we added the msActiveXFilteringEnabled API which determines whether ActiveX Filtering is enabled for the current site. The API returns false on a site if the user decided to turn off filtering for that site, or if ActiveX Filtering is turned off globally. The upcoming section on best practices includes further suggestions on how to use this API.

In-Page Filter Icon

Some Web sites don’t display fallback content when ActiveX controls are blocked by ActiveX Filtering. Instead of displaying a broken object icon in the placeholder area, IE now displays the same filtering icon as the one used in the address bar.

IE displays the same icon in the placeholders of content that is blocked by Tracking Protection. Displaying this icon makes it clear to users that IE has filtered that content from the page. It serves as a visual cue for users to click the icon on the address bar to turn off filtering for that Web site and view the content. Without this change, users may perceive that the Web page contains broken links and may not be driven to configure filtering options for that page.

Best Practices for Web site Developers

Here are some best practices that we encourage Web site developers to follow to ensure that their sites work well with ActiveX Filtering:

Use Native Objects Instead of ActiveX

During product testing, we found several examples of Web sites that unnecessarily rely on the Microsoft.XMLHTTP ActiveX control for AJAX operations. Since ActiveX Filtering blocks instantiation of that control via script, the sites won’t render properly when ActiveX Filtering is enabled even though the sites don’t appear to have any ActiveX content.

These sites use the following coding pattern to use the ActiveX version of the XMLHttpRequest object, which fails when ActiveX Filtering is enabled:

// BAD PATTERN: Don't do this!
var xhr = window.ActiveXObject ? new ActiveXObject("Microsoft.XMLHTTP") : new XMLHttpRequest();

Internet Explorer has supported the native XMLHttpRequest object since IE7. The native object will function correctly even when ActiveX Filtering is enabled. Web sites’ scripts should prefer the native object if it’s present. The following sample code shows how to reliably create the XMLHttpRequest object:

// Best Practice: Use Native XHR, if available
if (window.XMLHttpRequest) { // If IE7+, Gecko, WebKit: Use native object var xmlHttp = new XMLHttpRequest();
else if (window.ActiveXObject) { // ...if not, try the ActiveX control var xmlHttp = new ActiveXObject("Microsoft.XMLHTTP");
else { // No XMLHTTPRequest mechanism is available.

With this code sample, sites will only need to instantiate the ActiveX control as a last resort. Sites can ensure that their functionality does not get unnecessarily affected by ActiveX Filtering by using native objects when possible.

Many of the Web sites that exhibited this behavior were using an earlier version of JQuery which used the above bad pattern to instantiate the XMLHttpRequest object. The latest version, JQuery 1.5.1, has addressed this issue so we encourage Web site developers to update.

Properly Displaying Fallback Content

Earlier we described the potential user confusion around displaying the wrong type of fallback content when ActiveX Filtering blocks a control. Web sites should use the new API to determine whether ActiveX Filtering is enabled on the site to distinguish from the cases where the ActiveX control hasn’t been installed or the version is out of date.

If ActiveX Filtering is indeed enabled for the site, our first recommendation is for developers to not display any fallback content. This allows the filter icon to be displayed within the placeholder area and has the same user benefit as we described earlier.

If sites still desire to display some fallback content, they can show a custom message telling users that they have to turn off filtering to view the content. The following sample code shows how to use the new API to check for ActiveX Filtering and display a custom message if a control is blocked:

<object type="application/x-shockwave-flash" data="test.swf"> <script type="text/javascript"> // Best Practice: First detect if ActiveX Filtering is enabled if (typeof window.external.msActiveXFilteringEnabled != "undefined" && window.external.msActiveXFilteringEnabled() == true) { document.write("ActiveX Filtering has hidden this content."); } else { // Either the browser isn’t IE, or ActiveX Filtering is not enabled in IE document.write("Please install the Flash plug-in to view this content."); } </script>

Web sites can use some alternate methods to display the original content on the page. For example, the ActiveX Filtering Test Drive demo displays videos in the HTML5 video format when ActiveX Filtering is enabled for the site.

We ask developers not to navigate users to a different Web page when they detect that ActiveX Filtering is enabled. IE contains logic that will keep the filter icon displayed on the address bar even if the new Web page doesn’t contain any ActiveX controls, but users will need to navigate back to the previous page after they turn off filtering. If the new Web page is in a different domain, users will end up adding turning off ActiveX Filtering for the wrong domain.

Test Your Web site with ActiveX Filtering

Some of the site compatibility issues we observed with ActiveX Filtering can be easily identified and addressed through testing. An example is the following site whose layout is affected when ActiveX Filtering is enabled.

The filter icons appear properly in the placeholders for the blocked ActiveX controls. It turns out that the site declared one of the controls with default dimensions that were inconsistent with its actual dimensions. Since IE uses the default dimensions to display the placeholder object on the page, the incorrectly sized placeholder results in layout issues with the rest of the page.

Developers should test their Web sites for compatibility with ActiveX Filtering to identify issues like the one described in this post. This ensures that only ActiveX content on a Web page is blocked by ActiveX Filtering and users can continue to view the rest of the page properly.

Working Well with ActiveX Filtering

Since we released ActiveX Filtering in the IE9 Release Candidate, the feedback we received helped us make the proper additions to the feature in order to make it more usable for both end-users and developers. For example, adding the filter icon to the placeholder object for an ActiveX control helps indicate to users that ActiveX Filtering has blocked content on the page, and they can turn off filtering through the same icon on the address bar.

We encourage Web site developers to follow the best practices shared in this post to ensure that Web sites work well with ActiveX Filtering. Developers should prefer natively implemented objects to ActiveX controls when they’re available, and update their sites to JQuery 1.5.1 which uses the right method to instantiate the native XMLHttpRequest object. Use the new API to detect whether ActiveX Filtering is enabled on a site and display more targeted fallback content. Finally, thoroughly test Web site compatibility with ActiveX Filtering to identify subtle layout issues. In the meantime, we welcome developers to share their own best practices in comments for this post.

—Herman Ng, Program Manager, Internet Explorer