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.

• By Dan Wahlin
• 10/29/2007

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().

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.

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.

• Get Code Download