Wahlin on .NET

Understanding Silverlight's CreateObject and CreateObjectEx Methods

Dan walks you through the properties and sample code for each, plus why you might want to use one over the other.

A Silverlight control is instantiated in a Web page by calling one of two methods: createObject() and createObjectEx(). Both methods are static members of a JavaScript class named Silverlight that's defined in Microsoft's Silverlight.js file (refer to my previous column for more information on the role of Silverlight.js). Although the two methods perform the same task, the syntax required to call each of the methods is somewhat different.

In this column, I'll look at each of the methods, describe the parameters they accept and explain why you might choose one over the other.

Using the Silverlight.createObject() Method
The Silverlight.createObject() method is used to create a new instance of a Silverlight control and embed it in a Web page. It's a cross-browser method that automatically handles detecting browsers and determining which technique should be used to instantiate the control. If the control isn't already installed, the method will provide the end user with information on how to install it. The following table shows the main parameters accepted by createObject().

Parameter

Description

source

Path to the source XAML file to be rendered by the Silverlight control.

parentElement

DOM element in the Web page that acts as the host container for the Silverlight control.

id

ID that will be assigned to the instance of the Silverlight control in the DOM.

properties

Properties used to define control characteristics such as height, width, background color and more.

events

Used to define event handlers for Silverlight control load and error events.

initParams

User-defined initialization values that can be passed to a Silverlight control instance as it loads.

context

Unique identifier that can be accessed in the OnLoad event. Useful when multiple Silverlight controls may be defined in a page.

Before showing an example of using the Silverlight.createObject() method, let's examine the set of properties that can be passed using the properties parameter. The following table shows each of the properties and explains their overall purpose.

Property

Description

width

The width of the Silverlight control in the Web page.

height

The height of the Silverlight control in the Web page.

background

The background color of the Silverlight control. The default value is null which is equivalent to a white background.

isWindowLess

Determines if the control displays as a window-less control or not. The default value is false. The Silverlight SDK provides the following insight into the isWindowLess property:

For Windows, if the value is set to true and the background property value specifies an alpha value, the window-less mode enables HTML overlay where the HTML on the page blends with the contents of the plug-in, including its background. For Macintosh, the plug-in always acts as a windowless plug-in, and the value of this property is ignored in run-time behavior.

frameRate

Determines the maximum number of frames that the control should render per second.

inplaceInstallPrompt

Determines whether the in-place installation prompt appears if the specified version of the Silverlight plug-in is not installed. The default value is false. When set to false, the user will be taken to the Silverlight installer page on Microsoft's Web site.

It's important to note that this property should NOT have single or double quotes around the value. See Listing 1 for an example.

version

Used to specify the version of the Silverlight control required to run the application.

ignoreBrowserVer

Determines if browser versions should be ignored when determining whether the Silverlight control will be run or installed. The default value is false.

The code below shows an example of how to use the Silverlight.createObject() method. Recall that this method is normally placed in a file named CreateSilverlight.js (see my previous column for more information), although it can be placed directly in the Web page, as you'll see in the source code download accompanying this article. Looking through the code, you'll see that the properties and event handlers are defined using JavaScript Object Notation (JSON) syntax. JSON provides a cross-browser way of defining property names and values.

Silverlight.createObject(
  'XAML/Basic.xaml',
  document.getElementById('SilverlightContainer'),
  'slControl',
  {
    width: '500',
    height: '500',
    background:'#ffffffff',
    inplaceInstallPrompt:false,
    isWindowless: 'false',
    version: '1.0',
    framerate: '24'
  },
  {
    onError: null,
    onLoad: null
  },
  null,
  null
); 

Using the Silverlight.createObjectEx() Method
In addition to the createObject() method, the Silverlight JavaScript class also exposes a createObjectEx() method that can also be used to instantiate a Silverlight control.

What's the difference between the two methods? Not a whole lot, actually. The createObjectEx() method uses JSON syntax to pass all of the parameter values whereas the createObject() method uses JSON for only some of the parameters, such as the properties and event handlers.

I personally prefer the createObjectEx() method because it clearly states what each parameter passed to the method represents. This can simplify maintenance down the road. However, it's completely up to you as to which method to use; both accomplish the same goal.

Listing 2 shows an example of how to use the createObjectEx() method. As you look through the code listing, notice how all of the parameter values are prefixed with a name that identifies the parameter value and that all of the parameters are wrapped with { and } characters.

  source: 'XAML/Basic.xaml',
  parentElement: document.
     getElementById('SilverlightContainer'),
  id: 'slControl',
  properties: {
    width: '500',
    height: '500',
    background: '#ffffffff',
    inplaceInstallPrompt: false,
    isWindowless: 'false',
    version: '1.0',
    framerate: '24'
  },
  events: {
    onError: null,
    onLoad: null
  },	
  initParams: null,
  context: null 
});

Although this article describes using the createObject() and createObjectEx() methods from scratch so that you understand the purpose of each parameter, keep in mind that the Silverlight template functionality available through Visual Studio .NET 2005 and 2008 add-ins will automatically add this code for you so that you don't have to worry about all of the details.

In the next column, I'll discuss how the load and error events can be wired to event handlers so that you can be notified when a Silverlight control loads or errors out.

About the Author

Dan Wahlin (Microsoft MVP for ASP.NET and XML Web Services) is the founder of The Wahlin Group which specializes in .NET and SharePoint onsite, online and video training and consulting solutions. Dan also founded the XML for ASP.NET Developers Web site, which focuses on using ASP.NET, XML, AJAX, Silverlight and Web Services in Microsoft's .NET platform. He's also on the INETA Speaker's Bureau and speaks at conferences and user groups around the world. Dan has written several books on .NET including "Professional Silverlight 2 for ASP.NET Developers," "Professional ASP.NET 3.5 AJAX, ASP.NET 2.0 MVP Hacks and Tips," and "XML for ASP.NET Developers." Read Dan's blog here.

comments powered by Disqus
Upcoming Events

.NET Insight

Sign up for our newsletter.

I agree to this site's Privacy Policy.