Silverlight and the Rich Client Browser

Serving Up Silverlight-Enabled Web Pages

A Silverlight-enabled page is a regular Web page that you can create using any development platform, whether a classic ASP or HTML page, an ASP.NET page, an ASP.NET AJAX page, or even a PHP page. The host Web page must meet a couple of key requirements. First off, it must reference a particular JavaScript file that contains the object model to drive the Silverlight engine. Second, the host page must include some boilerplate JavaScript code to initialize the engine if installed, or to display the install prompt otherwise as in Figure 1.

The Silverlight object model is contained in a file named silverlight.js that you get out of the box when you install on the server machine the Silverlight SDK. In the host page, you reference this file from your server using a classic <script> tag.

<script type="text/javascript" src="silverlight.js"></script>

The file contains a JavaScript object named Silverlight. This object exposes essentially methods to test whether the plug-in is installed and to generate the markup that will incorporate the plug-in in the page as an <object> tag (see Figure 2). A Web page can contain multiple instances of the Silverlight plug-in each bound to a different WPF content.

[Click image to view at full size]

Figure 2: The DOM of a HTML page that contains a Silverlight plug-in.

The Silverlight plug-in may appear everywhere in the host page. You decide size and location of the plug-in by using the following combination of HTML markup and JavaScript code.

<div id="Host"> <script type="text/javascript"> createSilverlightHost(); <P> </script> </div>

In this case, the Silverlight plug-in will appear within the surrounding <div> tag. If you want it to flow with the remainder of the page, you replace the <div> element with a <span> element. The JavaScript function createSilverlightHost is piece of boilerplate code that you add to, or reference from, each Silverlight-enabled page.

Listing One shows the typical body of the function.

function createSilverlightHost()
{  
 Silverlight.createObject(
     "page.xaml",                   
     document.getElementById("Host"),                   
     "SilverlightControl1",          
     {                                
         width:'300',                
         height:'200',               
         version:'1.0'               
     },
     {
         onError:null,      
         onLoad:null        
     },
     null);                 
}

The Silverlight.createObject method is ultimately responsible for instantiating the Silverlight plug-in when the browser gets to render the portion of page where the plug-in is destined to live. You pass the method the URL to the WPF content to download and render as well as the parent DOM element and the ID to use to reference the plug-in programmatically. It should be noted that the Silverlight initialization script can be placed anywhere in the page. In other words, the parent element of the plug-in in the page is not inferred from the position of the initialization <script> tag, but is rather explicitly specified as a parameter to the Silverlight.createObject method.

function createSilverlightHost() {  
    Silverlight.createObject(contentURL,                   
        document.getElementById("Host"),                   
        "SilverlightControl1",  ... );
}

The net effect of the Silverlight.createObject method is the dynamic creation an <object> tag that is added a child to the specified parent element. The third argument to the method is just the unique ID for the newly created <object> element. You can later use this ID to reference the plug-in programmatically. The Silverlight.createObject method accepts the arguments listed in Table 1.

The properties to configure the plug-in are listed in Table 2.

Most of these properties are optional; in a realistic page you typically assign an explicit value to width, height, and version. These properties are used to initialize the Silverlight plug-in, but only a few of them are programmatically exposed through the Silverlight object and can be retrieved at run time from JavaScript code. These properties are isWindowless, background, and enableHtmlAccess. The corresponding runtime properties take the following names: Windowless, Background, and EnableHtmlAccess. You access these properties using the settings property on the plug-in object, as in the following code snippet:

var plugin = document.getElementById("SilverlightControl1");
plugin.settings.Background = "yellow";

The Silverlight plug-in also features a limited event model based on two events -- load and error. The load event occurs after the WPF content in the Silverlight plug-in has completely loaded. The error event is fired if any error occurs during the processing of the WPF content. You can define JavaScript handlers for these events using the events properties of the Silverlight.createObject method (see Listing One).

The Silverlight plug-in can either be hosted in a portion of the container page or cover the entire page. If you want the plug-in to expand up to cover the full browser area, then you set width and height properties to 100 percent.