Remote Scripting

• Download source and binaries - 46.9 Kb
• Download binaries only - 8.31 Kb

Contents

• Introduction
• Demo
• Usage
• Notes

Introduction

How many times have you been on a web page and you selected a value in a drop down box, only to suddenly see the whole page refresh so that it can fetch values for another drop down box? I see it all the time in car web sites. You select the Make of the car and the whole page is reloaded to bring back all the corresponding Models. Then you select the Model and the whole page is reloaded again to bring back all the corresponding Trims. Annoying, isn't it?

Some sites avoid this problem by preloading all the possible alternatives in memory. This works, but there are times when the amount of data is just too overwhelming for all the possible combinations.

Remote Scripting offers a better alternative. Instead of the whole page refreshing, a hidden request is made to the server to execute a method which returns back just the data that needs to be changed on the page. The result is a smoother user experience. Indeed, Remote Scripting brings some of the benefits of a traditional fat-client application to a web application. It can be used to refresh individual controls, to validate controls, or even to process a form without having to post the whole page to the server. It's cool stuff and it works on all major browsers!

Over the years, I've seen two popular remote scripting implementations. Back in the days of Visual InterDev 6.0, Microsoft provided client and server-side include files inside its _ScriptLibrary directory. I used it in a few projects and it worked quite well. The only problem I found was that it used a Java applet to handle the communications, so it tended to be sluggish at times. Then I started doing JSP and I found a better alternative called JSRS. Depending on the browser, it created a hidden element on the page that submitted the request to the server which then responded back to it. It was more efficient, but it only allowed the remote calls to be asynchronous.

Now with ASP.NET, I've once again needed to use Remote Scripting. I initially wrote a small class library in C# that provided support for both Microsoft's and JSRS's clients. But then I decided to see if I could come up with a better client implementation, and I believe I did. I came up with a hybrid solution based on both of the existing implementations, which I believe looks and works better. This article presents my Remote Scripting client and server side implementation for ASP.NET. Enjoy!

Demo

The downloadables include a file called rsDemo.aspx which has a fully working example of this code. It also demonstrates how to populate the drop downs using data from an XML file (rsDemo.xml). The link below goes to the demo page. When you change the Type, the Amount is repopulated using Remote Scripting.

• Demo Page

Usage

I've strived to make my Remote Scripting implementation as simple and easy to use as possible. There are just a few simple steps to take on the client and server side to get it working. Be sure to look at the rsDemo.aspx file to get the complete picture.

Client-side

1. Include rs.js in your .aspx page, like this:

   <script language="'JavaScript'" src='/scripts/rs.js'></script>

2. Use RS.Execute to invoke the remote method using JavaScript, like this:

   function dropdown_onchange()
   {
     RS.Execute("page.aspx", "RemoteMethod", 
                "optionalParam1", "optionalParam2", ...., 
                callback, optionalErrorCallback,
                optionalCallbackParam2, optionalCallbackParam3, 
                optionalCallbackParam4);
   }

   The page.aspx file is where the RemoteMethod will be executed. The RemoteMethod's parameters are optional, so don't pass anything if they're not needed. The callback function (which is not a string parameter) is also optional and if passed will be called when the server's response is received. Its first parameter will be the value returned by the RemoteMethod, converted to a string. If there's a chance for error, you can also pass a second callback method that will receive the error description. If it's not passed, an alert box will be shown in case of error. If you pass optionalCallbackParam2, optionalCallbackParam3, or optionalCallbackParam4, they will also be passed to the callbacks. Keep in mind that RS.Execute is asynchronous, so the callbacks are the only way to know when and what was returned from the server.

3. If you care about the RemoteMethod's result, add a callback method to get it, and optionally do the same for error messages:

   function callback(result)
   {
     alert("The remote method returned this: " + result);
   }
   
   function errorCallback(result)
   {
     alert("An error occurred while invoking the remote method: " + result);
   }

Server-side

1. Make sure AMS.Web.RemoteScripting.dll file is deployed to your site's bin directory.
2. At the top of the Page_Load method, add these two lines:

   if (AMS.Web.RemoteScripting.InvokeMethod(Page))
     return;

   This accomplishes several things. First, it checks if the client is making a remote request on the page. If not, this method returns false (and Page_Load proceeds). If there is a client request, the remote method is invoked, its return value is written to the response, and it is then sent back to the client immediately.

   If your page does not have a Page_Load method (and you don't want to add one), you can just place those two lines at the top of your page inside <% %> tags.

3. Add the remote method as a public instance or static member of your Page class:

   public string RemoteMethod(string param1, string param2, ... )
   {
     return "This is what the client sent me: \n" + param1 
            + "\n" + param2 + ... ;
   }

   If you just need to read a field's value, you can use a property instead of a method:

   public string RemoteProperty
   { 
     get { return m_someField; };
   }

   The return type does not need to be a string but it will be converted to a string before going back to the client. The parameters must all be of type string, and the method (or property) must be public or you'll receive a System.MissingMethodException error.

   As an alternative to remotely executing a public method or property of the Page, you may also directly execute a public method or property of a control on the page. For example, if you want to retrieve the Text property of a TextBox control called "txtAmount", you can pass "txtAmount.Text" as the name of the remote method in RS.Execute.

Notes

I added a method called ReplaceOptions inside rs.js. It makes it convenient to repopulate a drop down box with the results of a remote method. It expects the result string to be formatted like this:

"<option value='0'>Text 0</option><option selected value='1'>Text 1</option>..."

You can use it like this inside the callback:

function callback(result)
{
  RS.ReplaceOptions(document.form.theDropDown, result);
}

An even better alternative is RS.ReplaceOptions2, which may be passed directly to RS.Execute as the callback function:

function dropdown_onchange()
{
  RS.Execute("page.aspx", "RemoteMethod", 
             "optionalParam1", "optionalParam2", ...., 
             RS.ReplaceOptions2, document.form.theDropDown);
}

RS.ReplaceOptions2 takes the same parameters as RS.ReplaceOptions but in the opposite order so that it can be used as a callback. This allows you to do everything in one call!

The RS object also has a member called debug that you can set to true (RS.debug = true;) to show the hidden elements used for communicating with the server.

On the server side, you'll see that the RemoteScripting class is designed to handle any of three possible clients: Mine (RS), JSRS, and Microsoft's (MSRS). The type of client is determined based on the parameters passed into the request. If you have your own client implementation, my architecture makes it easy to add an implementation for it by deriving from the RemoteScriptingClient class.

Microsoft is the only remote client implementation that supports synchronous calls to the server, so if you absolutely need that, you can use it. All you need on the client is the rs.htm and RSProxy.class files from the _ScriptLibrary directory. I personally don't recommend it since it ties up the browser until the response is sent back and it requires the browser to support Java. Nevertheless, I added support for it inside the RemoteScriptingClient class.

Something else to point out: for drop downs that are populated and repopulated based on remote scripting calls, I recommend you remove them from the ViewState (EnableViewState=false), since you'll need to populate them on every trip back to the server. In other words, regardless of whether IsPostBack is true or not, you'll need to populate these drop downs, so it will be a waste to save them to the ViewState.

History

• Version 1.0 - Mar 12, 2004.
  • Initial release.
• Version 2.0 - Sept 3, 2004.
  • Enhanced RS.Execute to allow passing of up to three additional parameters to the callbacks (aside from the result of the remote method).
  • Enhanced RemoteScriptingClient.InvokeMethod to allow execution of a method or property of a control of the page. Thanks to Jonathan Marbutt for the idea and his implementation.
  • Fixed bug that didn't allow remote scripting to work with the Opera browser. Thanks to Christoph Weber for reporting it.
  • Fixed bug that prevented remote scripting from working in SSL sites. Thanks to Peter for reporting it and providing the solution.
  • Fixed bug that was filling the call pool when remote methods were executed over 100 times. Thanks to emadns and Anonymous for reporting it.
  • Fixed bug that was taking the result string and replacing any slashes (/) with \/.
• Version 2.1 - Feb 7, 2005.
  • Fixed small problem in RemoteScriptingCall.setResult of rs.js when simultaneous calls were made to RS.Execute. Thanks to Eddy A for reporting it and providing the solution.
  • Fixed bug with RS.ReplaceOptions of rs.js which wasn't properly handling values containing angle brackets. Thanks to pussicatt0102 for reporting it.
  • Updated the rsDemo.aspx page to demonstrate how to make it work with a Submit button.