Silverlight.js Reference
Microsoft Silverlight will reach end of support after October 2021. Learn more.
The Silverlight.js file provides JavaScript helper functions for embedding the Silverlight plug-in in a Web page and for customizing the Silverlight installation experience.
You can use the createObject and createObjectEx functions to dynamically embed a Silverlight plug-in in a Web page. These functions generate HTML object elements from the specified parameters. For more information, see How to: Add Silverlight to a Web Page by Using JavaScript.
You can use most of the remaining functions to improve the standard Silverlight installation or upgrade experience. For example, in some cases, you can automatically refresh the browser after the plug-in is installed, or avoid a refresh altogether. For more information, see WaitForInstallCompletion.
The Silverlight.js file is installed with the Silverlight SDK in the following location: %ProgramFiles%\Microsoft SDKs\Silverlight\v2.0\Tools. However, Silverlight.js depends on browser implementation details that can change between Silverlight releases. For this reason, it is recommended that you periodically check for an updated version from the Silverlight.js page of the MSDN Code Gallery. For more information about the Silverlight SDK, see Silverlight Tools.
Silverlight.supportedUserAgent.js is another JavaScript helper file that you can use with Silverlight.js. The Silverlight.supportedUserAgent.js file provides a supportedUserAgent function that determines whether the user's browser is supported by Silverlight. This functionality is not included in the Silverlight.js file because it is highly dependant on current Web browser implementations. Because browsers evolve very quickly, this function will need to be updated much more frequently then the Silverlight.js file. If you need the supportedUserAgent function, you should check for updates on the Silverlight.supportedUserAgent.js page regularly.
The following sections provide a brief, alphabetical reference for the Silverlight.js functions intended for developer use. This reference does not include support functions and internal helpers, which you can learn about in the Silverlight.js file itself.
The Silverlight.js file encapsulates its functions and variables within a Silverlight object, which you can retrieve from the HTML DOM window object. The following sections use the "Silverlight" prefix in the syntax blocks for this reason.
This topic contains the following sections.
- createObject
- createObjectEx
- default_error_handler
- getSilverlight
- isBrowserRestartRequired
- isInstalled
- onGetSilverlight
- onSilverlightInstalled
- WaitForInstallCompletion
- Related Topics
createObject
Generates either an HTML object element that embeds the Silverlight plug-in using the specified parameter values or alternative HTML if Silverlight is not installed.
Syntax
Silverlight.createObject(source, parentElement, id, properties, events, initParams, userContext);
-or-
objectElement = Silverlight.createObject(source, null, id, properties, events, initParams, userContext);
Parameters
source
The URI of the application to load. See Source (Silverlight Plug-in Object).
parentElement
The HTML element in which to insert the generated HTML, or null, to return the generated HTML instead of injecting it.
id
The id attribute value of the generated object element.
properties
An array of name and value pairs. See Remarks.
events
An array of event name and function name pairs, which will be added to the generated object element as child param elements.
initParams
A string that contains name and value pairs separated by commas; for example, "name1=value1,name2=value2,name3=value3".
userContext
A value that is passed to your onLoad event handler when the event occurs.
Return Value
If parentElement is null, the generated HTML object element or alternative HTML; otherwise, no value is returned.
Remarks
All parameters are optional except the source parameter.
If you specify a parentElement value, the createObject function sets the element's innerHTML property to the generated or alternative HTML. Otherwise, the createObject function returns the HTML.
The properties and events array parameters are added to the generated object element as child param elements. You can use the properties parameter to set properties including background, enableHtmlAccess, maxFrameRate, and windowless. You can use the events parameter to specify handlers for events such as onLoad and onError.
For information about these properties and events, see Silverlight Plug-in Object Reference.
You can specify a required Silverlight version by adding a properties parameter named version. For more information, see Silverlight Plug-in Versioning.
To specify alternative HTML to use when Silverlight is not installed, add a properties parameter named alt with the alternative HTML as its string value. If you do not provide an alt value, the createObject function will generate default installation HTML. The default installation HTML calls the getSilverlight function and passes it the version value if you have specified one.
The createObject function provides special handling for the onLoad event. If you provide an onLoad handler, createObject will replace it with a function that calls your handler and passes it the following arguments:
A direct reference to the generated object element.
The userContext value.
The onLoad event's sender argument value.
This special handling is useful to identify the loaded plug-in when you use a single onLoad handler with multiple plug-in instances in a Web page.
For more information, see How to: Add Silverlight to a Web Page by Using JavaScript.
createObjectEx
Calls the createObject function using parameter values specified in a single array parameter.
Syntax
Silverlight.createObjectEx(params);
-or-
objectElement = Silverlight.createObjectEx(params);
Parameters
params
The createObject parameter values as a single array. For more information, see the createObject parameter list.
Return Value
See the createObject return value.
Remarks
See the createObject remarks.
default_error_handler
Provides a default handler for the onError event that displays error data in a popup dialog box.
Syntax
Silverlight.default_error_handler = function(sender, args) { ... }
Parameters
sender
The plug-in for which the error occurred.
args
The event data. For more information, see ErrorEventArgs.
Return Value
The function that handles the event.
Remarks
You will typically suppress error handling in production code by setting default_error_handler to null.
getSilverlight
Attempts to download the specified version of the Silverlight installer.
Syntax
Silverlight.getSilverlight(version);
Parameters
version
A string that represents the requested version of Silverlight, or an empty string ("") to request the latest version. For information about the version number, see Silverlight Plug-in Versioning.
Return Value
None.
Remarks
When you use createObject or createObjectEx, the default installation HTML specifies that the getSilverlight function is called when the user clicks the installation image. If you provide your own installation HTML, you should also call this function when the user requests installation.
The getSilverlight function calls the onGetSilverlight function if you have specified one. This enables you to respond when a user requests the Silverlight installer but before the installer download begins.
The getSilverlight function will then generate and follow the Silverlight installation URI for the specified Silverlight version. This will typically display a download prompt to the user without requiring navigation to a different Web page. However, if a user is on an unsupported platform, this function will navigate the browser to a Microsoft Web page that describes the problem.
isBrowserRestartRequired
Indicates whether the Silverlight plug-in is already installed when the Web pages loads, requiring a browser restart if the plug-in is upgraded.
Syntax
bool = Silverlight.isBrowserRestartRequired;
Return Value
true if the Silverlight plug-in is already installed, requiring a browser restart upon upgrade; otherwise, false.
Remarks
The WaitForInstallCompletion function calls this function to determine whether to automatically refresh the browser after Silverlight is installed.
You can use isBrowserRestartRequired to determine whether Silverlight is installed, and to display a message that a browser restart is required when you upgrade.
isInstalled
Indicates whether the specified version of Silverlight is installed.
Syntax
bool = Silverlight.isInstalled(version);
Parameters
version
A string that represents a Silverlight version number. For information about the version number, see Silverlight Plug-in Versioning.
Return Value
true if the specified version of Silverlight is installed; otherwise, false.
Remarks
The createObject and createObjectEx embedding functions call the isInstalled function to determine whether a requested version of Silverlight has been installed. The return value determines whether the embedding functions will generate an HTML object element or alternative HTML that prompts the user to install or upgrade.
The WaitForInstallCompletion function calls the isInstalled function to determine whether Silverlight has been installed since the last time it checked.
onGetSilverlight
Called by the getSilverlight function to indicate that a user has requested the Silverlight installer.
Syntax
Silverlight.onGetSilverlight = function() { ... };
Parameters
None.
Return Value
The function that the getSilverlight function calls.
Remarks
When you use createObject or createObjectEx, the default installation HTML specifies that the getSilverlight function is called when the user clicks the installation image. You can also use getSilverlight with your own installation HTML.
The getSilverlight function calls the onGetSilverlight function if you have specified one. This enables you to respond to installation requests without modifying the installation HTML. The onGetSilverlight function is called before the installer download begins.
Some browsers block unintended file downloads by mapping download requests to user actions. If the onGetSilverlight function takes too long, then the browser may block the download. Therefore, it is very important for an onGetSilverlight function to avoid performing long-running operations unless you start them asynchronously. You can start asynchronous operations by using the setTimeout method.
onSilverlightInstalled
Called by the WaitForInstallCompletion function to refresh the browser when it detects that Silverlight has been installed.
Syntax
Silverlight.onSilverlightInstalled = function() { ... };
Parameters
None.
Return Value
The function that the WaitForInstallCompletion function calls.
Remarks
The WaitForInstallCompletion function calls the onSilverlightInstalled function when it detects that Silverlight has been installed. However, this does not occur when the user has upgraded Silverlight from an earlier version. In this case, the user must restart the browser.
You will typically use the isBrowserRestartRequired function to determine whether an upgrade is required, and then display the appropriate message.
The default onSilverlightInstalled function refreshes the browser window. You can replace this behavior in a handler for the Web page's onLoad event. You can disable the automatic refresh by setting the function to null, or you can set it to your own function. For example, instead of refreshing the browser, you can use createObject or createObjectEx to insert a new HTML object element directly into your Web page. This will embed the newly-installed plug-in without requiring a browser refresh.
WaitForInstallCompletion
Periodically checks for new Silverlight installations and automatically refreshes the browser window after install.
Syntax
Silverlight.WaitForInstallCompletion();
Parameters
None.
Return Value
None.
Remarks
New Silverlight installations require a browser refresh so that the Web page can load the Silverlight plug-in. However, Silverlight upgrades require a browser restart instead of just a refresh.
When you use Silverlight.js, the WaitForInstallCompletion function is called by default when the page loads and a user has not already installed Silverlight. After a new Silverlight installation is complete, the WaitForInstallCompletion function calls the onSilverlightInstalled function to refresh the browser. You can replace onSilverlightInstalled with your own function to disable or customize this behavior.
See Also