What is the Silverlight.js file?
Silverlight.js is a JavaScript helper file used when adding a Silverlight application to a web page via JavaScript. It defines a number of methods to help with this, most importantly createObject and createObjectEx. Other notable functions and event handlers include:
The Silverlight.js file is installed along with the Silverlight 2 SDK (which is part of the Silverlight Tools for Visual Studio 2008 SP1 install). By default, you will find the Silverlight.js file at "C:\Program Files\Microsoft SDKs\Silverlight\v2.0\Tools".
So how do I create a Silverlight object using Silverlight.js?
Another way to ask this is how do I host a Silverlight application? There are three ways: by way of the Silverlight server control included in the Silverlight 2 SDK (the best approach for ASP.NET developers), by using Silverlight.js, or through an explicit <object> tag. Since this post is about the JavaScript approach I'll move forward with the second option, though I'll touch briefly on the lattermost also.
Using Visual Studio 2008, you can create a quick sample project by going to "File | New Project", selecting "Silverlight Application", click OK, select "Automatically generate a test page to host Silverlight at build time", click OK again. Then, right-click on your new project and add an HTML page. Last, under Debug options, make that HTML page the default start page. OK, maybe that wasn't 'quick'. ;-)
Alternatively, you can just download the sample project at the bottom of this post.
Anyway, depending on how you created your Silverlight project, you may first need to copy the Silverlight.js into your local project directory. Then, define a reference to Silverlight.js like you would any other JavaScript file:
1: <script type="text/javascript" src="Silverlight.js"></script>
Now, you have two options with which to create the Silverlight object:
- Use createObject or createObjectEx
- Explicitly define the Silverlight control via an <object> tag
Let's attack approach #1 first.
Using createObject/createObjectEx
The difference between the createObject and createObjectEx is that createObjectEx takes JSON-formatted parameters. If you dig into createObjectEx in the Silverlight.js file you'll see that it actually just makes a call into createObject:
1: // createObjectEx, takes a single parameter of all createObject parameters enclosed in {}
2: Silverlight.createObjectEx = function(params)
3: {
4: var parameters = params;
5: var html = Silverlight.createObject(parameters.source, parameters.parentElement, parameters.id, parameters.properties, parameters.events, parameters.initParams, parameters.context);
6: if (parameters.parentElement == null)
7: {
8: return html;
9: }
10: }
I'll demonstrate using createObjectEx.
At this point, once you have a basic HTML page and included the Silverlight.js file in the <head> section you should have something like this:
1:
2: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
3:
4: <html>
5: <head>
6: <title>Using Silverlight.js</title>
7: <script type="text/javascript" src="Silverlight.js"></script>
8: </head>
9:
10: <body>
11: <!-- silverlight control gets hosted here -->
12: </body>
13: </html>
Now let's add the actual Silverlight control.
Add the following createObjectEx code into the body of your HTML page:
1: <div id="slHost" style="height:100%";">
2: <script type="text/javascript">
3: Silverlight.createObjectEx(
4: {
5: source: "ClientBin/Silverlight.js.xap",
6: parentElement: document.getElementById("slHost"),
7: id: "slControl",
8: properties: { width: "100%", height: "100%", version: "2.0" },
9: events: {}
10: } );
11: </script>
12: </div>
If you run your project now you'll get… a blank (white) web page. We can spruce that up real easy with a background which will at least allow you to see the control. Here is the complete HTML with JavaScript and a blue background property added:
1:
2: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
3:
4: <html>
5: <head>
6: <title>Using Silverlight.js</title>
7: <script type="text/javascript" src="Silverlight.js"></script>
8: </head>
9:
10: <body>
11: <!-- silverlight control gets hosted here -->
12: <div id="slHost" style="height:100%";">
13: <script type="text/javascript">
14: Silverlight.createObjectEx(
15: {
16: source: "ClientBin/Silverlight.js.xap",
17: parentElement: document.getElementById("slHost"),
18: id: "slControl",
19: properties: { background: "blue", width: "100%", height: "100%", version: "2.0" },
20: events: {}
21: } );
22: </script>
23: </div>
24: </body>
25: </html>
Let's break down the JSON-formatted parameters passed into createObjectEx.
| source |
Your Silverlight control's XAP file. |
| parentElement |
Specifies the HTML object hosting your Silverlight control. |
| id |
Your control's unique identifier. |
| properties |
The control's properties, such as height and width. |
| events |
Any events your control handles. For example, onLoad or onError. |
That's it. You now have a fully functioning, albeit not very useful, Silverlight control embedded into an HTML page using Javascript.
Using <object>
Another way to embed a Silverlight control onto a web page is with the <object> tag. Using this approach, you don't need the Silverlight.js file at all. This means, of course, that you lose some of the ease-of-use it provides. If losing such functions as buildPromptInstall or isInstalled is not a big deal, then the <object> approach might be the way to go.
Here is an example using the <object> tag, taken directly from a new Visual Studio project that uses an ASP.NET web project to host the control:
1: <body>
2: <!-- Runtime errors from Silverlight will be displayed here.
3: This will contain debugging information and should be removed or hidden when debugging is completed -->
4: <div id='errorLocation' style="font-size: small;color: Gray;"></div>
5:
6: <div id="silverlightControlHost">
7: <object data="data:application/x-silverlight-2," type="application/x-silverlight-2" width="100%" height="100%">
8: <param name="source" value="ClientBin/TagCloud.xap"/>
9: <param name="onerror" value="onSilverlightError" />
10: <param name="background" value="white" />
11: <param name="minRuntimeVersion" value="2.0.31005.0" />
12: <param name="autoUpgrade" value="true" />
13: <a href="http://go.microsoft.com/fwlink/?LinkID=124807" style="text-decoration: none;">
14: <img src="http://go.microsoft.com/fwlink/?LinkId=108181" alt="Get Microsoft Silverlight" style="border-style: none"/>
15: </a>
16: </object>
17: <iframe style='visibility:hidden;height:0;width:0;border:0px'></iframe>
18: </div>
19: </body>
This isn't really a recommended approach; Microsoft provides the Silverlight.js file because it handles some of the cross-platform compatibility you might run into. You're sort of taking matters into your own hands by taking the <object> tag approach.
Conclusion
Microsoft has provided a number of ways to host a Silverlight control on a web page. Using Silverlight.js and JavaScript is just one of those approaches. Personally, I'll likely use the ASP.NET server control approach, but I'm glad for having delved a bit into this alternative method of hosting Silverlight controls.
Download: Silverlight.js Sample Project
Further Reading
Silverlight.js Reference
MSDN Code Gallery: silverlight.js
How to: Add Silverlight to a Web Page by Using JavaScript