Get Client Resolution Data

Authored November 2000

Using these templates developers may retrieve client screen resolution and color depth data from JavaScript 1.1+ compatible browsers. This system may be used alone or in conjunction with an existing browser detection scheme (browser vendor, version, etc).

Resolution information can be used to create customized page layouts or content decisions. For example you may safely assume that a user with a 4bit (16 color), 640x480 system would appreciate a "graphics light" version of a site while a user with 32bit color at 1600x1200 resolution can accept whatever you throw at them (although of course this says nothing about connection speed). Tracking resolution information for statistical analysis can be very useful while planning a site redesign.

Explanation

This system capitalizes on the ability of JavaScript to access certain client information that is not available to the server via the CGI variable set. JavaScript is used to send the data to the server via the manipulation of a hidden graphic object on the page. This technique of using a graphic as a data conduit is more fully explored in our article "Using a GIF as a Data Pipe".

The system consists of three files:

• The first file, GetRes.cfm, is basically a JavaScript snippet that sets a CF Session variable. The template checks for the existence of the "Session.ResData" structure; if it does not exist does the template initializes it outputs the JavaScript to the browser in an attempt to populate it with better data. This template can be cfincluded into any file in the application.
• The second file, FauxGif.cfm, is called by the JavaScript as the SRC attribute of an IMG object. This template accepts the URL parameters (if any) and populates a session structure named "ResData" with the data retrieved (or defaults) then uses <cfcontent> to return a gif to the browser.
• The last file, Tiny.gif, is simply the single pixel, transparent GIF the FauxGif.cfm eventually sends to the client via the <cfcontent> tag.

The simplest way to use the system is to either cfinclude or copy the contents from GetRes.cfm into a template in your web application. You, for example, just use the first page of the application or the log in page of an secure application. You could also place the file on every template of the site, perhaps via a header or footer include/custom tag. In that case you may want to create a check that would prevent multiple resolution checks. For example you might only send the JavaScript if the Session.ResData structure exists and does not contain all zeros. You might also set a cookie in FauxGif.cfm and only send the script to the browser if the cookie doesn't exist.

Since, as is, the templates attempt to create and populate session variables you'll have to use these templates within an existing application. We make the assumption that most developer's interested in this snippet will want to modify the user experience on the fly so we also assume session variables are in use. It's a fairly simple modification to have the data retrieved written to some other store (a log file, a database, or client variables).

It should be obvious that clients that either do support JavaScript 1.1+ or have disabled client-side scripting will return no usable data (in this case zeros will be populated for all variables). Also, since an image tag is used to return the data to the server if the client has disabled downloading of images this system will fail. A rare "big" you may also encounter is that client systems with multiple displays will return the resolution of the primary display even if the browser is currently shown a secondary display.

If successful however the system returns five variables for use in your applications. These variables are placed in a session-resident structure called "ResData" that contains the following keys:

Session.Resdata.ResWidth
Session.Resdata.ResHeight

The width and height of the client display in pixels. For example a standard VGA screen would return "640" and "480" respectively.

Session.Resdata.ResAvailWidth
Session.Resdata.ResAvailHeight

The width and height of the client display in pixels minus any "hard" items like the Windows 9x/2000 taskbar, the MS Office tool bar, etc. In general this can be seen as the full size of a program window, extreme edge to extreme edge, when it is maximized. It should be understood that this is not the available area for web page content, but rather the available browser program space. You must still take into account space being used for browser chrome and system controls (toolbars, scrollbars, etc). For example if the standard Windows taskbar was "Always on Top" on a 640x480 display these values might be "640" and "452" respectively.

Session.Resdata.ColorDepth

The color depth, in bits, of the client display. This break down like this: 4bit = 16 colors, 8bit = 256 colors, 16bit = 16,000 colors, 24 bit = 16,000,000 colors, 32bit = 16,000,000 colors and 8bit alpha masking. The human eye generally has trouble distinguishing between 16bit and higher displays; you may safely rule that any client 16bit or above is "high color".

The Code

We have made these files, and a single pixel Gif file, available for download as a compressed zip file: GetRes.zip (1.15kb).

The third line of Code Listing 1, GetRes.cfm, must be modified. The variable "FauxGifPath" must point to the location of the FauxGif.cfm file on your server. The file initializes five variables in the Session.ResData session structure to zero. This is done to facilitate the common "if resolution width is greater than 640" logic. Defaulting the values to zero when they are unknown ensures the client will be treated as the lowest common denominator.

Code Listing 2 presents the FauxGif.cfm file. As in GetRes.cfm the variable RealGifPath (line 3) must be set to the system path (NOT the URL) of the gif file to be returned. Note this file will only populate the data if three criteria have been met: the session.resdata structure must exist, the URL.ScreenData variable must exist, and the URL.ScreenData variable must be a list of five items. If needed in your environment you could further check that each element of the list is numeric, but we've never found that neccessary. The code sets the values recieved and then, in line 19, sends the gif to the browser.

Using this Code

When creating a truly dynamic display you really shouldn't need this code at all. Your content should ebb and flow to whatever size the client is currently set to. However as the web get more complex there are many cases where content content cannot be resized dynamically but rather must be locked in a display space. This is the case with Java displays such as CF Grid or CFTree, display plug-ins like Flash and Shockwave, and certain browser features like floating frames. Knowing, even roughly, what your client is capable of allows you to tailor such objects better.

As noted these script can be modified to meet your specific needs. One simple modification would be to use CFFile to create a log file of captured resolutions. You can then perform metrics on the gathered information, perhaps correlating it to other data gathered, to determine where the bulk of your visitors lie in the technology curve. You can then plan your site's upgrades and redesigns with an intelligent eye to the actual capabilities of your users.