What's new in the Silverlight 2 Beta 2 SDK's Silverlight.js file?

  • Article

The Silverlight.js file was updated with several important improvements in the Silverlight 2 Beta 2 SDK. These improvements were focused on two key areas: better experiences out-of-the-box for end users and easier customization of those experiences for developers. To these ends we added functionality that was frequently implemented on Silverlight web sites, we fixed known bugs, and we removed Silverlight 1.0-functionality which did not add value in Silverlight 2. The updated file is also designed with <object> tag instantiation in mind, making interactions between Silverlight.js and <object> tags easier than ever.

Better End-User Experience

When you use the Silverlight.createObject function to instantiate the Silverlight control on your web page there is a default prompt that is displayed to users who do not have the right version of Silverlight installed. In Silverlight 1.0 the default prompt looked like this:

 sl1indirectinstallmedallion

Clicking on this image linked to www.microsoft.com/silverlight/install.aspx. A user would visit the Silverlight Web site, install the control, and return to the originating Web site to view the content.

We improved this model for the end user through better UI, reduced clicks during installation, and automatic content loading.

Improved UI

We updated the graphic that is displayed so that it is better at integrating with a wide range of Web sites:

As you can see, this graphic ( it is the same png on all three backgrounds) has a transparent border which helps blend the site's background color with the installation image. It even works over top of other images, thereby giving users an integrated feeling without any additional work on the part of the developer.

Reduced installation clicks

We reduced clicks by pointing the hyperlink associated with this image directly to the Silverlight installer. Therefore, instead of visiting Microsoft.com, installing, and returning, the user now clicks on the image and installs Silverlight without ever leaving the page.

Automatic Content Loading

Once the user finishes installing something needs to happen to let them see Silverlight content. In 1.0 that something was either a browser refresh or a browser restart, depending on the browser. I have recently blogged about avoiding both of these experiences through script. This behavior has been added to Silverlight.js and is on by default. Therefore, any page which references the new Silverlight.js file will get the auto-refresh behavior, where available.

Better Developer Experience

All of the new user experience functionality was implemented with the developer in mind. Therefore, we have introduced a number of new events, methods, and properties to help customize any portion of the installation experience.

Improved UI

While the new install prompt image is designed to work with a large variety of sites, we understand that it may not be sufficient for all scenarios. Therefore, a developer can now pass an alt parameter to Silverlight.createObject. The value of this parameter should be a chunk of valid HTML encoded as a javascript string. If the createObject method finds that the Silverlight control is not available then it will load this HTML instead of the default image displayed above.

Reduced Installation Clicks

For the alt HTML to be useful it must know how to start the download of the Silverlight installer. To help with this, we added the Silverlight.GetSilverlight method. When this method is called it determines which installer link to use and navigates the browser to that link. In most cases, this will lead directly to the installer and therefore keep the user on the current page.

Automatic Content Loading

By default, including the Silverlight 2 Beta 2 version of Silverlight.js in a web page will cause the file to detect if a user has any version of Silverlight installed. If the user does not then an installation monitoring process, Silverlight.WaitForInstallCompletion, is started. This process will occasionally check to see if Silverlight has been installed. Once it detects that installation is complete it will refresh the page so that the user has immediate access to the page's Silverlight content without any additional user action.

If a web author does not like the refresh experience then this process can be disabled by setting the value of Silverlight.onSilverlightInstalled to null. Silverlight.onSilverlightInstalled is treated as an event handler and will be called when Silverlight.WaitForInstallCompletion detects that installation is complete. This can be used to enable more interesting installation scenarios. For example, a dev could set Silverlight.onSilverlightInstalled to a function which dynamically injects Silverlight object tags into a page, thus avoiding a browser refresh all together.

onSilverlightInstalled can also be combined with another new Silverlight.js event, SilverlightonGetSilverlight, to give users a guided installation experience. Silverlight.onGetSilverlight gets called whenever someone calls Silverlight.GetSilverlight. This should happen whenever the user clicks a button which starts the Silverlight installation process. Therefore, a site author can have a DIV which tells the user to "install Silverlight".  When the user clicks the installation button, that click causes a call to Silverlight.GetSilverlight --> Silverlight.onGetSilverlight. When Silverlight.onGetSilverlight is called, it can change the contents of the DIV to "Silverlight is installing. Make sure you approve the installation." Once the user finishes installing Silverlight, Silverlight.onSilverlightInstalled is called. This can change the DIV to say "Thank you for installing Silverlight. <Name of your app> is loading..." and set a timeout which then dynamically injects a Silverlight <object> tag in a few seconds.

New Members

Silverlight.onSilverlightInstalled Event

Occurs when the Silverlight plug-in has finished installing

Scripting (Runtime) Silverlight.onSilverlightInstalled = functionName;
Event Handler Parameters

The event handler should expect no parameters.

Remarks

The onSilverlightInstalled event occurs after a user finishes installing the Silverlight plug-in on a machine without a previous version of Silverlight. The event will not fire if the user is upgrading from a previous version.

By default, onSilverlightInstalled is set to a function which refreshes the browser on the current page. If this is not the desired behavior then onSilverlightInstalled should be set to null or another javascript function during the page's OnLoad event.

Silverlight.WaitForInstallCompletion

Triggers Silverlight.onSilverlightInstalled event when Silverlight is installed.

Silverlight.isBrowserRestartRequired

Boolean value set at page load time. If true then any upgrade of the Silverlight control will require a browser restart. Otherwise, onSilverlightInstalled will be triggered when installation is complete.

Silverlight.GetSilverlight

Begins the Silverlight installer download process.

Scripting

 Silverlight.GetSilverlight(versionString);
Parameters

versionString

 stringA string that represents the requested version of Silverlight. See Silverlight Versioning.
Return Value

None.

Remarks

The method will generate and follow the Silverlight installation URL appropriate for the requested Silverlight version. This will typically result in the Silverlight installer being downloaded without navigating away from the current web page. The user will only be navigated away from the web page if they are found to be using an unsupported platform. If that is the case, they will be brought to a Microsoft Web site which will help them understand the problem.

Silverlight.onGetSilverlight Event

Occurs when Silverlight.GetSilverlight is called. Enables developers to capture click events on the Silverlight installation image without modifying the default image.

Scripting (Runtime) Silverlight.onSilverlightInstalled = functionName;
Event Handler Parameters

The event handler should expect no parameters.

Remarks

Some browsers block unintended file downloads by mapping download requests to user actions. If the handler for onGetSivlerlight clicked takes too much time to return then the browser may block the download. Therefore it is very important for the onGetSilverlight handler to avoid performing long-running operations unless they are started asynchronously. Long-running operations can be started asynchronously by using the setTimeout method.

Silverlight.createObject alt Parameter

Defines alternate HTML to use when an appropriate version of Silverlight is not available.

Usage
     var altHTML = "<a href='javascript:Silverlight.getSilverlight(\"{1}\");' style='text-decoration: none;'>"+<br>                  "<img src='{2}' alt='Get Microsoft Silverlight' style='border-style: none'/></a>"; 

    Silverlight.createObject(
        "plugin.xaml",                      // Source property value.
        parentElement,                      // DOM reference to hosting DIV tag.
        "myPlugin",                         // Unique plug-in ID value.
        {                                   // Plug-in properties.
            width:'1024',                   // Width of rectangular region of plug-in in pixels.
            height:'530',                   // Height of rectangular region of plug-in in pixels.
            background:'white',             // Background color of plug-in.
            isWindowless:'false',           // Determines whether to display plug-in in windowless mode.
            framerate:'24',                 // MaxFrameRate property value.
            version:'1.0'                   // Silverlight version.
            alt: altHTML                    // Alternate HTML to display if Silveright is not installed
        },
        {
            onError:null,                   // OnError property value -- event-handler function name.
            onLoad:null                     // OnLoad property value -- event-handler function name.
        },
        null,                               // initParams -- user-settable string for information passing.
        null);                              // Context value -- passed to Silverlight.js onLoad event handlers.
Remarks

Be sure to call Silverlight.getSilverlight to initiate the installation process.

Fixes

The Silverlight 2 Beta 2 version of the Silverlight.js file fixes a known issue in the Silverlight.isInstalled method. You can learn about the fix here: Firefox 3 support added to Silverlight 2 Beta 2 SDK's Silverlight.js.

Removed Members

The following members were removed from Silverlight.js. These members were previously used to determine the browser type that the client was using and to offer correct installation experiences for each browser type. This updated version of the file has removed its dependencies on specific browsers and instead relies on features common to the IE and Mozilla browser families. The primary usage scenarios for these members was to determine if the user should be asked to restart their browser after they start the installation process. However, this scenario can now be implemented in a more reliable fashion by checking if(Silverlight.isBrowserRestartRequired) in their handler for Silverlight.onGetSilverlight.

  • Silverlight.ua
  • Silverlight.available
  • Silverlight.detectUserAgent
  • Silverlight.supportedUserAgent

Comments

  • Anonymous
    June 25, 2008
    Emil Stoychev with a Silverlight Twitter Widget, Kathy Kam on the missing WatermarkedTextBox, Adam Kinney

  • Anonymous
    July 02, 2008
    Silverlight.js is now available for download on MSDN Code Gallery via http://code.msdn.microsoft.com/silverlightjs

  • Anonymous
    July 31, 2008
    I'm working on the "guided install" you suggest (and your post is very helpful, thanks). I basically have it working in IE7 and FF3 now. One question: in Firefox 3, when I call getSilverlight the only options Firefox gives the user are "Save" and "Cancel" so the user has manually to go to their Downloads directory and run the .exe. After the install when I inject the object tag into the div, I still need to refresh the page (refresh isn't needed in IE7). Does that sound right? Thanks!

  • Anonymous
    August 07, 2008
    GRISJUAN, The refresh should not be required in any browser, assuming that the user does not have a previous version of Silverlight installed. You can overwrite the value of Silverlight.onSilverlightInstalled  with a new function that injects the object tag for you. This way, you can use the detection logic in Silverlight.js and still get the injection behavior you are looking for. You should also examine the value of Silverlight.isBrowserRestartRequired. If a user is doing an upgrade then they will need to restart their browser before using the newer control. The recommendation for this scenario is to wait for the user to click the installation link. Once they do, replace your installation prompt with something like "Thanks for upgrading Silverlight. When installation is complete, please restart your browser and come back to <YOUR URL>." This way the user understands what is going on every step of the way. As to the Firefox Save/Cancel dialog, that user experience is outside of your site's control. However, a Firefox user is likely to be comfortable with the Firefox experience around downloads and therefore should not have problems with finding and running the installer. Thanks, Piotr

  • Anonymous
    August 20, 2008
    The comment has been removed

  • Anonymous
    September 17, 2008
    grisjuan, can you share a pointer to your app? I would like to take a closer look at what is going wrong. Piotr

  • Anonymous
    September 27, 2008
    It's not a 'real' app ... I was just studying the installation experience. I'll redo the whole app from scratch now that an RTW is available and I'll report back in a couple of weeks. Thanks!