The GetExtPropertiesEx method (which stands for "get extended properties") provides access to advanced information regarding the property settings of the visitor's browser. To get the value of certain properties (as listed below) this method must be called so BrowserHawk can perform a more extensive check on the browser.
Note to users of BrowserHawk versions prior to 5.0: The GetExtPropertiesEx method has replaced the original GetExtProperties method. Although the original method is still available in this version, it has been depreciated as of BrowserHawk 5.0 and as such will likely be removed in a future version. GetExtPropertiesEx offers many advantages and improvements over GetExtProperties. To get any of the benefits provided by this version of BrowserHawk, you must use the GetExtPropertiesEx method.
The following properties require that you call the GetExtPropertiesEx method in your script prior to accessing the property value in order to obtain meaningful results:
ActiveXEnabled, VBScriptEnabled, VBScriptBuild, BrowserBuild, CookiesEnabled, ConnectionSpeed, JavaEnabled, JavaScriptEnabled, JavaScriptBuild, JavaVersion, JavaVendor, MSJVMBuild, Plugin_JavaVer, NetMeetingBuild, LangUser, LangSystem, TimeZoneDiff, BrowserDateTime, BrowserDateTimeMs, FontSmoothing, TextSize, Height, ServicePack, Width, HeightAvail, WidthAvail, ConnectionType, Firewall, OpenPorts, SSLEnabled, ImagesEnabled, ColorDepth, MSXML, Referrer, Plugin_Flash, Plugin_FlashVerEx, Plugin_Director, Plugin_DirectorVerEx, Plugin_QuickTime, Plugin_QuickTimeVerEx, Plugin_Acrobat, Plugin_AcrobatVerEx, Plugin_RealPlayer, Plugin_RealPlayerBuild, Plugin_MediaPlayer, Plugin_MediaPlayerVerEx, Plugin_iPIXViewer, Plugin_SVGViewer, Plugin_CrystalReports, Plugin_ViewPoint, Plugin_Authorware, Plugin_Mapguide, Plugin_Custom, and Plugin_Citrix.
Note: To use the GetExtPropertiesEx method you must have either the Professional or Enterprise Edition of BrowserHawk and use the component from an ASP page. ColdFusion developers should see the cf_examples.zip file in their BrowserHawk installation directory for information on how to use this method in conjunction with CFM pages.
Syntax:
bhObject.GetExtPropertiesEx [requestType] [,htmlForBodyTagAsString] [, pageTitleAsString] [,waitMsgAsString]
requestType – BrowserHawk communicates directly with the browser in order to collect the test results from the GetExtPropertiesEx method. You can control the way in which this communication is performed by setting the requestType to either 0 (auto-select), 1 (cookie based), 2 (query string based), or 3 (POST based). If no value is specified, a default of 0 is used. See the 'Setting the RequestType' section below for details on this setting.
htmlForBodyTagAsString – this optional parameter is used to tell BrowserHawk to add additional HTML to the <BODY> tag which it sends as part of the test page it loads to detect the special properties. The most popular use of this parameter is to specify the BGCOLOR tag so that the test page has the same background color as the rest of your site, or to provide HTML BrowserHawk should use in order to create a customized "Please wait" page. Note that if specifying customized HTML is may be necessary to set the DocTypeTag property to ensure the browser displays your HTML properly.
pageTitleAsString – this optional parameter is used to tell BrowserHawk what text to insert in between the <TITLE> tags used by the test page it loads to detect the special properties. If you wish to use this parameter but not the htmlForBodyTagAsString parameter, you must pass an empty string as the value for htmlForBodyTagAsString.
WaitMsgAsString – this optional parameter is used to display a message in the user's browser while the extended properties are detected. This is helpful for letting the user know to please wait while the test is performed. In many cases the test is performed so quickly that the message may only appear for a fraction of a second. However if you are testing a lot of properties or time intensive properties (such as connection speed – see the last section of this topic for more information) there could be a delay of several seconds, depending on their computer. You can also pass HTML in this parameter if you wish to display a temporary page or more advanced formatting.
Note: Before calling the GetExtPropertiesEx method you must call the SetExtProperties method to indicate which properties you want to check.
When the GetExtPropertiesEx method is invoked, BrowserHawk silently sends a test page to the user's browser, determine the values for the properties requested (as set by the SetExtProperties method), and then continues with the loading of your page.
The GetExtPropertiesEx method MUST be called before the <HTML> tag is sent to the browser. Therefore the best place to invoke this method from is the top of your ASP script, preferably as the first ASP code to execute in the script. Any line of your script that comes after calling the method can then access these properties to get the appropriate values. If you try accessing these special properties before calling GetExtPropertiesEx, these properties will contain default values.
Tip: See the section on Detecting Extended Properties for an important discussion on the various requestTypes that can be used when performing extended property checks.
Before calling this method you must first call SetExtProperties and pass in a string containing the names of the properties you want this method to detect. Note that detecting all plug-ins may cause a delay in the loading of the page while the detection is performed. This is because BrowserHawk now detects over 100 properties, and performing all tests at once can be a time consuming operation. Therefore it is recommended for optimal efficiency that you ask BrowserHawk to detect just the plug-ins and other extended information you are interested in rather than everything.
The time it takes to execute the test will depend on a variety of factors, including the number of properties you are testing for, and how fast it takes certain tests to execute. Most tests execute almost instantaneously. However some test, such as connection speed, Java version/vendor, and RealPlayer build number can take several seconds to execute depending on the user's computer speed and in some cases the speed of their connection.
GetExtPropertiesEx only works with Internet Explorer, Netscape, Mozilla, Firefox, Opera, Chrome, and Safari browsers. For all other browsers or search engines this method performs no operations and returns immediately. Therefore, it is not necessary to test the browser type prior to calling this method.
Pass in a requestType of 0 (auto-select) to have BrowserHawk automatically select the most appropriate requestType for the user and the situation in which you are using this method.
If you have a load balanced web farm, and you are testing for disabled cookies or using a requestType of 0 or 1, you must set the CookieDomain property to your root domain (i.e. "mycompany.com") prior to calling GetExtPropertiesEx. Otherwise BrowserHawk will not be able to properly determine the browser settings assuming a different web server answers the redirect issued by this method.
If you use GetExtPropertiesEx from the Session_OnStart event in global.asa you must do so as the last line of code in that event, as code which follows the call to GetExtPropertiesEx will not be executed.
If you use the GetExtPropertiesEx method from ASP code that is executed with a POST request, you must specify a value of 0 or 3 for the requestType parameter.. Otherwise the Request.Form collection will be emptied.
A side effect of using the requestType of 2 is that your query string will be modified to contain extended information for the properties you ask BrowserHawk to check. These values are mandatory and cannot be avoided when cookies are disabled. Any information you have stored on your own in the query string will however be preserved. Use the requestType of 0 or 1 to minimize the use of the query string.
A side effect of this method with all requestTypes in the loss of the referrer information from any page that uses this method. If you need to capture the referring URL to a page that uses this method, simply you must specify "referrer" as a parameter when calling SetExtProperties. To get the referrer then simply check the BrowserHawk Referrer property. Note that for your convenience any of BrowserHawk's reserved name/value pairs are automatically removed from the referrer.
If the user changes their browser settings (such as the window size, cookie enabled/disabled settings, etc) and then presses their Reload button on your test page, BrowserHawk will disregard the new settings and return the properties as originally detected. This behavior is by design. This is necessary because it is not possible to detect the difference between a user pressing Reload, and the browser requesting the page again due to a print or 'Save Page As' request by the user. Without this behavior, In the later cases the browser would print/save the BH test page instead of your actual page. With this in mind, if you ask the user to change their settings, provide them with a link back to the test page and ask them to click on it to retry after making the changes, rather than pressing their Reload button.
Using this method to detect the Adobe Acrobat plug-in and/or its version number may cause the Acrobat splash screen to appear for users with Internet Explorer on Windows who are running Acrobat 4. While we realize the appearance of this splash screen is less than ideal, it is an unfortunate side effect of the testing and cannot be avoided. You will need to asses whether detecting this plug-in is worth the trade-off in having the splash screen appear. This does not apply to Acrobat 5 and later.
Use the Translate method to translate the various properties into a meaningful value for display to an end-user.
After calling the GetExtPropertiesEx method, store the results for the special properties you are interested in into a session variable if you may need this information again later during the visitor's session. It is not recommended that you call this particular method for each page request that a user makes.
If the visitor's JavaScript is disabled the GetExtPropertiesEx method will set the JavaScriptEnabled property to False, and all other properties which depend on this method being called will contain their default values. Therefore after calling GetExtPropertiesEx you should check to make sure JavaScriptEnabled is not False before relying on the values of the other properties.
For visitors using Internet Explorer version 3.0 or 3.01 only: After calling the GetExtPropertiesEx method visitors with this browser will experience different behavior from their browser's Back button. For these visitors, their Back button will keep returning them to the current page. In order to back up to the previous page, the visitor will have to press their back button twice within a couple of seconds to actually back up. This is an unfortunate side effect of the test that only affects users of IE 3.0 and 3.01. If you find this bothersome the alternative is to check to see if the visitor has this browser and if so do not call GetExtPropertiesEx. This issue only affects visitors with IE 3.0 or 3.01.
In certain cases where the visitor is using an old IE browser which does not have a properly installed and working VBScript scripting engine, or in rare cases where the visitor's browser does not properly process the client-side script this method sends it, accessing a page which uses this method may cause a client-side scripting error message or a blank page to result.
Three optional parameters are available with the GetExtPropertiesEx method. The first parameter is used to pass any HTML Attributes you want added to the <BODY> tag used during the silent test invoked by GetExtPropertiesEx. This allows you to keep the same background color and/or background image on the user's browser during the silent test, making this test transparent.
For example, if your site uses a black background with your company logo as a background image, BrowserHawk will use the same for you during its test. In this case you would use the following code to do this:
Instead of calling GetExtPropertiesEx with no parameters, you would use:
bh.GetExtPropertiesEx 0,"BGCOLOR=#000000 BACKGROUND=/comp_logo.gif"
Without specifying this optional parameter, the users screen - in this example - would go from black to white (assuming white is the browser's default background color when none is specified, which is typically the case) and then load your ASP page, taking the screen back again to black. By using this optional parameter you can ensure that the user's browser screen color and background image remain consistent, thereby eliminating the white screen flicker that will be seen otherwise.
The second parameter is used to control what the GetExtPropertiesEx sends to the browser in the <TITLE> tag to set the title bar in the browser. Although the test can be very quick (less than a second depending on what you are testing), you may want to display a message in the title bar, for example:
bh.GetExtPropertiesEx 0, "BGCOLOR=#000000", "Please wait..." or bh.GetExtPropertiesEx 0, "", "Please wait..."
You can also get fancy and specify the HTML needed to display a customized "Please wait" type of page which matches the look and feel of the rest of your site, including your common header and footer.
Note: If the user has their JavaScript disabled and they are using IE on the Macintosh, the browser window will appear blank for a few seconds before your page is loaded and JavaScriptEnabled is set to false. Using this optional parameter makes it easier for these users to know that a test is in progress instead of just looking at a blank browser window for these couple of seconds. Again this applies only if their JavaScript is disabled.
Examples:
See the showbrow.asp, extproperties.asp, cookies.asp, and speed.asp for examples of the GetExtPropertiesEx method in action. ColdFusion users should see the examples in cf_examples.zip. These examples are located in the directory where you installed BrowserHawk.
See Also: