PluginDetect.getVersion(pluginName): [Returns string or null]
Returns the version (as a string) of the installed plugin. If multiple versions are detected, then the highest installed version is returned. When getVersion() returns a version, it only means that the plugin is installed. It does NOT necessarily mean that the plugin is enabled.
Returns null when the version could not be determined (when plugin is not installed/not enabled, or plugin is installed but the version information is unavailable).
By default, the returned version string is comma delimited and has the format of "A,B,C,D". If you wish to change the getVersion() delimiter, then use:
PluginDetect.getVersion(delimiter) where delimiter is a string with exactly 1 character.
For example,
PluginDetect.getVersion("."); // set delimiter
var version = PluginDetect.getVersion("QuickTime"); // version has the format of "A.B.C.D"
PluginDetect.isMinVersion(pluginName, minVersion): [Returns number]
Returns 1 if plugin is installed (& enabled) and plugin version is >= minVersion.
Returns 0.5 if plugin detection has been initiated but is not yet completed. The +0.5 number only occurs for NOTF (Not On The Fly) detection of the plugin. This result means that the plugin is installed (& enabled), but the plugin version is unknown at this point in time. The version info may or may not be available at a later time. When the plugin detection has been completed, the isMinVersion() method will return a different number.
Returns 0 if plugin installed (& enabled) but version is unknown (unable to determine if version >= minVersion).
Returns -0.1 if plugin is installed & enabled, but plugin version is < minVersion.
Returns -0.2 if plugin installed but not enabled. Some browsers occasionally reveal enough info to make this determination.
Returns -0.5 if plugin detection has been initiated but is not yet completed. The -0.5 number only occurs for NOTF (Not On The Fly) detection of the plugin. This result means that it is not known yet whether the plugin is installed or what the plugin version is. When the plugin detection has been completed, the isMinVersion() method will return a different number.
Returns -1 if plugin is not installed or not enabled.
Returns -2 if ActiveX is disabled (for Internet Explorer, this prevents plugin detection).
Returns -3 if you supplied a bad input argument to the isMinVersion() method.
NOTE: Some of the return values are only possible for certain plugins. For instance, 0.5 & -0.5 are possible for Java and Generic PDF Reader detection, because those plugins sometimes require NOTF detection. On the other hand, Flash will never return 0.5 or -0.5 because it is always OTF (On The Fly) detection.
Also, the -0.2 return value is only returned for some plugins, but not all. This depends entirely on how much info the browser makes available to PluginDetect.
PluginDetect.onDetectionDone(pluginName, f, ...): [Returns number]
This method is used for any plugin that requires both OTF and NOTF detection. For details on how to use this method with a specific plugin, see the specific plugin pages (such as for Java and Generic PDF Reader).
The method will initiate plugin detection if needed, and will execute the event handler f after the plugin detection results become available. The event handler f automatically receives the PluginDetect object as an input argument such that we have f(PluginDetect){ ... }.
Returns 1 if plugin detection is done (OTF) and handler f has been executed.
Returns 0 if plugin detection is not done yet (NOTF) and so handler f has not been executed yet.
Returns -1 if error (plugin name input argument not specified correctly).
PluginDetect.beforeInstantiate(pluginName, f):
Executes the event handler f immediately before PluginDetect attempts to instantiate the plugin. [By instantiate, we mean that an instance of the plugin is inserted into your web page. This will cause the plugin to start up and run, assuming it is installed.] The event handler automatically receives the PluginDetect object as an input argument such that we have f(PluginDetect){ ... }.
Sometimes during detection, it may be necessary for PluginDetect to instantiate (or attempt to instantiate) the plugin. Should this attempt be neccessary, the event handler f will run first, and then the plugin will attempt to instantiate. [Note: If the plugin is installed and enabled, then it instantiates. If it is not installed or not enabled, then it will not instantiate. Either way, the handler f will run before the attempt is made.]
In order for the beforeInstantiate() method to work correctly, you must place it BEFORE detection is started for the plugin. In other words, use it before getVersion(pluginName), isMinVersion(pluginName), and onDetectionDone(pluginName). As an example:
var PD = PluginDetect;
var F1 = function($){ ... }; // $ input arg is the PluginDetect object
PD.beforeInstantiate('Java', F1);
var F2 = function($){ var version = $.getVersion('Java'); alert(version); };
PD.onDetectionDone('Java', F2, 'getJavaInfo.jar');
PluginDetect.getInfo(pluginName, ...): [object]
Returns an object with several useful properties. For details on how to use this method with a specific plugin, see the specific plugin pages (such as for Java and Generic PDF Reader).
PluginDetect.onWindowLoaded( f ):
Executes the event handler f after the browser window has fully loaded, and after the plugin detection results are available. The event handler f automatically receives the PluginDetect object as an input argument such that we have f(PluginDetect){ ... }. You are free to use getVersion(), isMinVersion(), onDetectionDone(), and beforeInstantiate() inside event handler f.
Event handler f without user input arguments:
If the user does not specify any input arguments for event handler f, then the relevant PluginDetect methods are in the format of
PluginDetect.onDetectionDone(pluginName, f, ...)
PluginDetect.onWindowLoaded(f)
PluginDetect.beforeInstantiate(pluginName, f)
When the handler f is executed it automatically receives the PluginDetect object as input such that we have f(PluginDetect){ ... }.
Event handler f with user input arguments:
You may specify up to 3 inputs (ie. arg1, arg2, and arg3) for the event handler. The trick is to use an array such as [f, arg1, arg2, arg3]. The relevant PluginDetect methods are in the format of
PluginDetect.onDetectionDone(pluginName, [f, arg1, arg2, arg3], ...)
PluginDetect.onWindowLoaded( [f, arg1, arg2, arg3] )
PluginDetect.beforeInstantiate(pluginName, [f, arg1, arg2, arg3])
When the handler f is executed it automatically receives the PluginDetect object as input such that we have f(PluginDetect, arg1, arg2, arg3){ ... }.
pluginName: [string input argument]
This is the name of the plugin such as 'Java', 'QuickTime', 'DevalVR', 'Shockwave', 'Flash', 'WindowsMediaPlayer', 'Silverlight', or 'VLC'
minVersion: [string or number input argument]
This is the minimum plugin version.
Can be a string such as '1,5,0,0' or '1.5' or '1,5,0,1' or '1.5.0.1' etc...
Can be a number such as 0 or 1.5 or 1.50 etc...
If minVersion is not specified, then PluginDetect will assume minVersion is '0'.
Strings are more versatile than numbers since '1,5,0,1' cannot be expressed as a number.
<div id="plugindetect"></div> container: [optional HTML element in your web page to assist in plugin detection]
PluginDetect sometimes needs to add <object> and/or <applet> tags to your web page to accomplish plugin detection (for Java, DevalVR, WindowsMediaPlayer, Silverlight, RealPlayer, Flash, Adobe Reader, PDFReader). These <object>/<applet> tags are all placed into the same <div id="plugindetect" ></div> container. If the user does not specify the <div id="plugindetect" > container in the web page, then the PluginDetect script will automatically add the container to the page when needed. When detection has been completed, the <div> and its contents will be removed from the DOM.
If you wish to place your own plugindetect <div> into your web page, then you should obey the following rules:
1) The <div> container must be placed inside the <body></body>. You are allowed to nest the <div> inside another <div> if you wish.
2) The <div> must have an id of 'plugindetect' such that we have:
<div id='plugindetect'></div>
3) The PluginDetect script must be able to find the <div> when it is doing detection. It finds the <div> using document.getElementById('plugindetect'). All this means is that the <div> must be rendered by the browser by the time that the plugin detection is occurring. For example, you are allowed to do this:
<div id='plugindetect'></div>
<script type="text/javascript">
var version = PluginDetect.getVersion('Flash');
</script>
You are also allowed to do this:
<script type="text/javascript">
var T = function(){var version = PluginDetect.getVersion('Flash');};
PluginDetect.onWindowLoaded(T);
</script>
<div id='plugindetect'></div>
But you should NOT do this (because detection occurs before the div is rendered):
<script type="text/javascript">
var version = PluginDetect.getVersion('Flash');
</script>
<div id='plugindetect'></div>
4) Do not set the ccs visibility:hidden or display:none for the <div>. This could prevent the instantiated plugins from running properly.
5) PluginDetect automatically sets the <div> css properties for width, height, outline, border, padding, margin, display, and visibility. So you do not have to bother setting those yourself.
6) You are allowed to set the <div> css properties for position, left (or right), and top (or bottom). Note that position:absolute means that the <div> is positioned relative to its parent, and that it does not displace any other elements in your web page.
Here are a few examples of the <div> (we leave out the plugin detection code here for simplicity)...
i) No css settings at all
<body>
<div id='plugindetect'></div>
</body>
ii) Here the <div> is positioned in the top left corner of the <body>
<body>
<div id='plugindetect' style='position:absolute; left:0px; top:0px;'></div>
</body>
iii) Here the <div> is positioned in the top right corner of the <body>
<body>
<div id='plugindetect' style='position:absolute; right:0px; top:0px;'></div>
</body>
iv) Here the <div> is positioned in the top left corner of its parent <div>
<body>
<div style='position:relative;'>
<div id='plugindetect' style='position:absolute; left:0px; top:0px;'></div>
<div>
</body>
7) I do not recommend that you specify an absolute position that is off the screen, because I cannot guarantee how an instantiated plugin will behave in that case. You are free to experiment if you like, however. Here is an example where the <div> is off screen and therefore completely hidden from view:
<body>
<div id='plugindetect' style='position:absolute; left:-9999px; top:0px;'></div>
</body>
NOTE: For some plugins, there is a more complete set of instructions available on the individual plugin pages.
There are also a few other methods/properties of PluginDetect that you may find useful:
PluginDetect.hasMimeType( mt ): [returns mimetype object from navigator array or returns null]
The input mt is a string or an array of strings that specifies a mimetype.
For example, let us say that mt = 'video/quicktime'. If the mimetype mt is present and enabled in the browser, then PluginDetect.hasMimeType('video/quicktime') will return the mimetype object (from the navigator array) corresponding to that mimetype. If the mimetype mt is not present or not enabled in the browser, then PluginDetect.hasMimeType('video/quicktime') will return null.
On the other hand, let us say that mt specifies multiple mimetypes such that mt = ['video/quicktime', 'image/x-quicktime']. Then PluginDetect.hasMimeType() will return the mimetype object for either of these 2 mimetypes if either one is present and enabled. If neither mimetype is present and enabled, then PluginDetect.hasMimeType() will return null.
PluginDetect.isIE: [Boolean]
Returns true if the browser is Internet Explorer.
Returns false if the browser is not Internet Explorer.
PluginDetect.verIE: [null or number]
Returns version number of Internet Explorer.
Returns null if the browser is not Internet Explorer
PluginDetect.ActiveXEnabled: [Boolean]
Returns true if browser is Internet Explorer and ActiveX is enabled in the browser settings (ActiveX must be enabled for PluginDetect to work).
Returns false otherwise.
PluginDetect.isGecko: [Boolean]
Returns true if the browser is Gecko based (ie. Firefox, Mozilla, Netscape, Flock, SeaMonkey, K-Meleon, etc...).
Returns false if the browser is not Gecko based.
PluginDetect.verGecko: [null or string]
Returns a version number (as a string) of the Gecko version if the browser is Gecko based. The string contains the CVS branch tag of the source code used to create the version of Gecko in your browser. The branch tag is contained in navigator.userAgent and follows the string 'rv:'.
Returns null if the browser is not Gecko based.
PluginDetect.isSafari: [Boolean]
Returns true if browser is Safari, false otherwise.
PluginDetect.verSafari: [null or string]
Returns a version number for Safari 3+.
PluginDetect.isChrome: [Boolean]
Returns true if browser is Chrome, false otherwise.
PluginDetect.verChrome: [null or string]
Returns a version number (as a string) of the Chrome browser.
Returns null if the browser is not Chrome.
PluginDetect.isOpera: [Boolean]
Returns true if browser is Opera, false otherwise.
PluginDetect.verOpera: [null or number]
Returns a version number of the Opera browser.
Returns null if the browser is not Opera.
var status = PluginDetect.isMinVersion("Flash", "8");
var version = PluginDetect.getVersion("Flash");
// By the time the Javascript interpreter reaches this line, detection has already been completed.
var status = PluginDetect.isMinVersion("Java", "1.6", "getJavaInfo.jar" );
// If status is -0.5, then it means that detection is not completed yet (NOTF).
//
We need to wait, and then we can check the value of isMinVersion again.
var displayResults = function($$){
var status = $$.isMinVersion("Java", "1.6");
var version = $$.getVersion("Java");
alert(status);
// etc...
}; // end of function
// Execute displayResults when detection completed.
// onDetectionDone() will work for both OTF and NOTF.
PluginDetect.onDetectionDone("Java", displayResults, "getJavaInfo.jar");