JavaScript API for Silverlight
Microsoft Silverlight will reach end of support after October 2021. Learn more.
In some cases, the JavaScript API for Silverlight is required or is more appropriate than the managed API. This topic discusses these cases and provides links to more information on the JavaScript API in Silverlight.
This topic contains the following sections.
- Prerequisites
- Programming Model Considerations
- Scenarios for Using the JavaScript API
- Documentation for the JavaScript API
- Technical Specifics of the JavaScript API
- Related Topics
Prerequisites
You should read Application and Programming Models and understand the basic differences between the managed API and the JavaScript API. You should also understand the HTML DOM and how the Silverlight programming models and object tree relate to the browser DOM; for more information, see Silverlight Programming Models, XAML, and the HTML DOM.
Programming Model Considerations
The JavaScript API for Silverlight is the programming model that was available in version 1.0 of Silverlight. It uses a small subset of the objects that are currently available in Silverlight 2, plus a handful of objects that are specific to the JavaScript API. The subset considerations also affect which objects you can define in XAML. The Silverlight XAML parser only creates objects in the object tree for this subset, because the object tree is created based on the fixed native-code implementation that underlies the JavaScript API. In other words, the subset and limitation considerations that apply for the JavaScript API for Silverlight are much more substantial than which language you choose to write your code-behind logic in; the programming model / API choice you make determines which objects are available for use in your application.
If you have already developed for Silverlight 1.0, you are probably already familiar with the JavaScript API for Silverlight. The JavaScript API is similar to programming for the HTML DOM, and in fact is executed in the browser's scripting engine just like scripting to the DOM, but the Silverlight model extends into the object tree that is created when a XAML page is loaded as content for the Silverlight plug-in. This enables you to handle events on specific objects that you define in XAML, get or set property values or execute object methods at run time, modify the structure of the XAML-created object tree at run time, and so on.
In terms of the architecture, the JavaScript API is enabled on a Silverlight plug-in by opening a pathway into the Silverlight object tree, wrapping the scripting calls, and passing them to the plug-in object natively. In Internet Explorer the wrapping is done by IDispatch::Invoke calls; other browsers potentially use different wrapping paradigms depending on their plug-in and scripting architecture.
Scenarios for Using the JavaScript API
Splash Screens
A splash screen is an initial content area that is displayed to the user while other content is still loading. In terms of design and purpose, a splash screen has relatively low UI and interactivity requirements. The main purposes of a splash screen are the following:
Present an interesting visual.
Provide feedback to the user that the application (or browser host) is still functioning as expected and that the download is progressing.
Give specific information on download progress.
The first two functions can often be accomplished entirely in XAML, without any code-behind at all. Providing download progress requires a relatively minimal API to obtain information from the networking layer that performs the download. For these reasons, a splash screen is best implemented by using the JavaScript API and loading a XAML page (supported by script code-behind) for SplashScreenSource. The JavaScript API can load the splash screen without activating the Silverlight CLR and related assemblies, which shortens startup time. For more information on splash screens and how to implement them, see Silverlight Splash Screens.
Silverlight 1.0–Era Content and Maintenance
The Silverlight 2 plug-in supports a compatibility mode that supports applications written in the Silverlight 1.0 time frame. In particular, the plug-in can initialize based on the Silverlight 1.0–era string for application passed to the object element, and/or a version of "1.0" passed to Silverlight.js for initialization. Sites that were originally written for Silverlight 1.0 should generally continue to function for clients that have the Silverlight 2 plug-in.
.gif "Note") Note: |
|---|
If you do use Silverlight.js for initialization, you should consider updating the Silverlight.js used in your original deployment, because there may have been updates to the script logic that account for different browser agent strings and other technical changes that have occurred since the Silverlight 1.0 release. See How to: Add Silverlight to a Web Page by Using JavaScript. |
Silverlight 2 continues to support the JavaScript API by providing JavaScript access to the object tree and supporting a Source value that specifies a single XAML page. If you have an existing Silverlight 1.0–era application and you are adding just a few specific features or enhancements, then your business and technical decision-making process might determine that it is best to work the new features into the existing code base and continue to use the JavaScript API.
Developer Level of Experience
If you have extensive experience with JavaScript overall, continuing to use the JavaScript API might be the best use of your skill set. However, many features that are present in Silverlight 2 require the managed API and are not available to JavaScript.
Other Considerations
If your use of Silverlight content in a larger HTML page has relatively minimal requirements, or if you use the HTML DOM extensively in order to integrate many different HTML content areas and other plug-ins or controls on a single page, your decision-making process might determine that the JavaScript API offers the integration solution with the lowest overhead.
Documentation for the JavaScript API
The majority of the documentation for Silverlight 5 covers the managed API. For instance, if you want to learn more about animation, you might go to Animation Overview, which contains XAML examples that are mostly the same for both APIs. But the topic also contains managed code examples and addresses some managed code-specific scenarios. You should still be able to learn the concepts independent of what languages the code examples are in.
For the JavaScript API, this documentation set does contain a full set of reference topics for all objects, properties, methods, events, and enumerations that are available to the JavaScript API. These reference topics provide syntax both for XAML and for JavaScript, members lists for objects, and example code that uses XAML with JavaScript for the code-behind (or occasionally JavaScript only). The following are useful entry points into the JavaScript API reference for Silverlight:
New JavaScript API for Silverlight Version 2
Silverlight 2 provides additional objects beyond the Silverlight 1.0 object set, which can be used in the JavaScript API. This is enabled because these objects have a native implementation that is exposed in the same way as the initial 1.0 objects were. You can create these objects by instantiating from XAML, and subsequently script to the object tree. In order to use these objects, the client that runs your Silverlight-based application must also be a Silverlight 2 client.
The additional objects for JavaScript API are included in the JavaScript API for Silverlight documentation (as well as properties, methods, events, and enumerations). These are documented at a basic level. New objects and new members are noted with a Version Information section in the reference pages, whereas objects and members that existed in Version 1.0 do not have a Version Information section.
Technical Specifics of the JavaScript API
There are a few technical specifics of the JavaScript API that are different from the managed API and extend across multiple JavaScript API elements. For more information, see the following:
JavaScript and Case Sensitivity
JavaScript object, method, and property names are not treated as case sensitive when processed by IDispatch or parallel mechanisms that surface the Silverlight JavaScript API to the hosting browser script engine. Therefore, you can mix initial upper case in the XAML event attribute value and lower case in the actual method definition if you wish. However, the Silverlight documentation syntax and titling in descriptive text generally standardizes the case for objects, properties, methods, events, enumerations, and enumeration values using initial capitalization as well as some internal capitalization (sometimes known as "Pascal casing"). This is done for two reasons:
XAML is case sensitive, because it follows XML rules. The XAML syntax and equivalent scripting are usually presented on a single page, so there was a need to standardize on the XAML-enforced casing. The titling you see in Silverlight documentation is in the correct case form for a XAML object element or attribute.
The managed API treats all members as case sensitive, using the Pascal conventions. Presenting the JavaScript reference with equivalent casing promotes a cleaner migration pathway.
Note that JavaScript example code provided in the Silverlight documentation often does not follow that convention, and instead follows the generally used coding style convention for JavaScript, which is initial lowercase (camel casing).