Chrome Frame: Developer Guide

Home
Chromium
Chromium OS

Quick links

Report bugs
Discuss
Sitemap

Other sites

Chromium Blog
Google Chrome Extensions
Google Chrome Frame

Except as otherwise noted, the content of this page is licensed under a Creative Commons Attribution 2.5 license, and examples are licensed under the BSD License.

The Chromium OS designs and code are preliminary. Expect them to evolve.

For Developers‎ > ‎How-Tos‎ > ‎

Contents
1 About This Document
2 Making Your Pages Work With Google Chrome Frame
2.1 Conditional Google Chrome Frame Activation
3 The differences between Chrome and Chrome Frame
4 Detecting Google Chrome Frame and Prompting to Install
4.1 CFInstall.check() Options
4.2 CFInstall Examples
4.3 Screenshot of prompt
5 Debugging Tools
6 Testing Your Sites
6.1 Chrome Frame as a default renderer
6.2 Chrome Frame as a closed container
6.3 Troubleshooting installation issues
6.4 Further Troubleshooting
6.5 Asking for help
7 Chrome Frame for Administrators

About This Document

This document is for web developers who want their pages to work with Google Chrome Frame (aka, GCF). In most cases, making your pages work with GCF is trivial: you just add a single tag to the page. This simple process is described in the next section. The rest of the document is devoted to advanced issues and options.

In short, if your page works in the Google Chrome browser, it'll work in GCF. For more information check out FAQ.

Making Your Pages Work With Google Chrome Frame

Making your pages work with GCF is easy. Just add this tag to the top of the page:

<meta http-equiv="X-UA-Compatible" content="chrome=1">

That's it! Users running Internet Explorer with GCF installed will automatically have pages that include this tag rendered by GCF.

For many sites, adding a tag to every page may be cumbersome, so GCF also supports detection through an HTTP header with the same name and value:

X-UA-Compatible: chrome=1

You may recognize the X-UA-Compatible flag as the same mechanism introduced with IE 8 for controlling the rendering engine that IE uses for a particular page. In cases where GCF is not installed, the values can be combined to control IE's rendering behavior:

<meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1">

Note that the value for the "IE" parameter must be provided first. Also, please note that no matter where in the order you list the value "chrome=1", GCF will render the page if it is installed. That is to say, the switch to render the page in GCF always takes the highest priority.

To deploy this header site-wide for a site served with Apache, ensure that mod_headers and mod_setenvif are enabled and add the following to your httpd.conf (or appropriate configuration file):

<IfModule mod_setenvif.c>
  <IfModule mod_headers.c>
    BrowserMatch chromeframe gcf
    Header append X-UA-Compatible "chrome=1" env=gcf
  </IfModule>
</IfModule>

For IIS 7.0 and greater, you can set the header in a web.config file with similar syntax:

<configuration>
  <system.webServer>
     <httpProtocol>
        <customHeaders>
           <add name="X-UA-Compatible" value="chrome=1" />
        </customHeaders>
     </httpProtocol>
  </system.webServer>
</configuration>

GCF supports both the meta tag and HTTP header methods of triggering rendering interchangeably, allowing you to choose whichever approach is best for your site. Note also that GCF is best effort, meaning that if you specify the meta tag or header and GCF isn't installed, the page will be rendered in MSIE as normal.

Conditional Google Chrome Frame Activation

Depending on your site's needs, you might only want to use Google Chrome Frame for users with certain versions of IE. The following X-UA-Compatible header values (whether in a meta tag, or in the HTTP headers) provide you with this control:

chrome=1   - Always active
chrome=IE7 - Active for IE major version 7 or lower
chrome=IE8 - Active for IE major version 8 or lower

The following complete example indicates usage of Google Chrome Frame for IE6 users, and otherwise passes the "Edge" parameter to later versions of IE:

<meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=IE6">

The differences between Chrome and Chrome Frame

There are a few subtle differences between the two. Read up on the details at Differences between Chrome and Chrome Frame.

Detecting Google Chrome Frame and Prompting to Install

GCF reports that it is available by extending the host's User-Agent header with the string chromeframe. For more information see Chrome Frame User Agent.

You can use server-side detection to look for this token and determine whether GCF can be used for a page. If GCF is present, you can insert the required meta tag; if not, you can redirect users to a page that explains how to install GCF.As an alternative to server-side sniffing, you can use the CFInstall.js script to detect GCF and prompt users to install the plug-in without restarting their browsers. Using the script is straightforward:

<html>
<body>
  <script type="text/javascript" 
   src="/img/spacer.gif"> 
  <style>
   /* 
    CSS rules to use for styling the overlay:
      .chromeFrameOverlayContent
      .chromeFrameOverlayContent br
      .chromeFrameOverlayCloseBar
      .chromeFrameOverlayUnderlay
   */
  </style> 

  <script>
   // You may want to place these lines inside an onload handler
   CFInstall.check({
     mode: "overlay",
     destination: "www.waikiki.com"
   });
  </script>
</body>
</html>

The document containing the script must include a body tag. In browsers other than Internet Explorer, the call to check() is a no-op. Note that you can't make a local copy of the JavaScript library and use it with a file:// URL - that won't work.In Internet Explorer, check() determines if Chrome Frame is installed. If not, the user is prompted to install it.

You can choose how you want the user to be prompted. By default, check() injects an br at the top of the page. This br will navigate to a "Please install Google Chrome Frame" page hosted by Google. The overlay mode specified in the example ensures that this UI is displayed over other page content in a modal way and gives the user controls to disable the prompt for the site (noted for the future in a cookie).

Once the user prompt is displayed, CFInstall examines the environment periodically to determine if the plug-in has finished installing. If it has, the browser is redirected to the destination URL. If no destination is provided, the current page is simply refreshed when GCF is detected. If the page was served with either the meta tag or HTTP header, the refreshed page will then render in GCF and the subsequent call to check() will not trigger the prompt.

CFInstall.check() Options

The CFInstall.check method has many more options. You can specify:

mode: optional
How the user should be prompted when GCF is missing. Defaults to a value of inline that puts an br in the document that points to the value of url. If a value for node is specified this will control where the br is placed, else it will appear as the first child of the doucment's body element. If mode is set to overlay (recommended), an in-page dialog is displayed that floats over page content. If mode is popup, then url is opened in a new (popup) window. It's recommended that you only use a value of popup when calling check() from a user action, for instance the onclick handler of a button element else popup blocking software may defeat the check.
url: optional
Defaults to "google.com/chromeframe". Set this to change the URL that the prompt (either inline or in a popup) will navigate to. You might use this if you're using GCF on an intranet or closed environment and you want to prompt users to install from an alternate location.
destination: optional
The URL to navigate to once CFInstall detects that GCF has been installed.
node: optional
The ID or reference to an element that will contain the br prompt. If no node is provided, the prompt br will be inserted at the top of the document.
onmissing: optional
Function to be called when GCF is missing.
preventPrompt: optional
Boolean, defaults to false, which allows you to disable the default prompting mechanism. Use in conjunction with onmissing to implement your own prompt.
oninstall: optional
Function that will be called when GCF is first detected after an install prompt is displayed.
preventInstallDetection: optional
Boolean, defaults to false. Set this to true to prevent CFInstall from checking whether GCF has been installed. Use this to prevent redirection.
cssText: optional
Style properties to apply to the prompt br when mode is inline.
className: optional
CSS classes to apply to the prompt br when mode is inline.

CFInstall Examples

Using the node parameter with an inline prompt to place the prompt br in the page and using CSS to style the br, reloads the current page when install finishes:

<html>
<body>
  <!--[if IE]>
    <script type="text/javascript" 
     src="ajax.googleapis.com/ajax/libs/chrome-frame/1/CFInstall.min.js"></script>

    <style>
     .chromeFrameInstallDefaultStyle {
       %; /* default is 800px */
       border: 5px solid blue;
     }
    </style>

    <div id="prompt">
     <!-- if IE without GCF, prompt goes here -->
    </div>
 
    <script>
     // The conditional ensures that this code will only execute in IE,
     // Therefore we can use the IE-specific attachEvent without worry
     window.attachEvent("onload", function() {
       CFInstall.check({
         mode: "inline", // the default
         node: "prompt"
       });
     });
    </script>
  <![endif]-->
</body>
</html>

Note the use of the IE-specific conditional comment syntax. This syntax prevents the code inside it from being visible to non-IE browsers. This avoids fetching the CFInstall script and running the checks on browsers that don't need them, speeding up your pages. Notably, if this page is served with the GCF meta tag or header and the page renders using GCF, the conditional comments will also be ignored, meaning that it's safe to wrap CFInstall-specific code in conditional comments.

Easier method to enable Chrome Frame for specific versions of Internet Explorer is explained in the FAQ:

www.chromium.org/developers/how-tos/chrome-frame-getting-started/chrome-frame-faq#TOC-How-can-I-enable-Google-Chrome-Fram1

Screenshot of prompt

Here is how the prompt looks in mode:"overlay":

Debugging Tools

You can use the Web Inspector in GCF just as you would in the Google Chrome browser. To use it, right-click and choose "Inspect Element". Logging is available via the console.log method, and you can set breakpoints and inspect network activity.

Testing Your Sites

To make your pages work with GCF, you should use the method of inserting a meta tag, as described earlier. There are other ways of invoking GCF. These techniques are useful for testing but are turned off by default. GCF provides a fast testing and prototyping shortcut that's especially useful when you can't modify the page you want to test. To use this method, just navigate to the URL prepended with "gcf:". Note that this prefix is in addition to any other URL scheme. For example, to see Gmail in GCF, go to Internet Explorer and navigate to:

gcf:



		
		
		
		    
		        
		            
		                
		                    
		                        
		                            
		                        
				    
					
				    
                                        
					    
            
            
                                                    
		                    
		                
		            
		            
		                
				    
                                        SEARCH:
		                    
		                    
		                        
					
		                    
		                
		            
		        
		    
		

		
	        
	        Related searches: 


chrome
 

prompt
 

google
 

cfinstall
 

script
 
        
		
		    
		        
		            gipoco.com
		            is neither affiliated with the authors of this page or responsible 

		            for its contents. This is a safe-cache copy of the original web site.
		        
		        
		            gipoco.com
		            is neither affiliated with the authors of this page nor responsible
		            for its contents. This is a safe-cache copy of the original web site.