In Web Connection 5.20 I made a breaking change to remove the wwWebAjax control that was introduced just a couple of revs back in 5.10. Usually I’m very wary about making changes like this but I think in this case the update to the newer model is warranted.

First, wwWebAjax still ships with Web Connection and you can continue to use it if you choose. However, by default the code does not get compiled any longer in the framework. If you want to keep using it you can set:

#DEFINE WWC_LOAD_OLDWWWEBAJAX          .T.

In your wconnect_override.h. This provides backwards compatibility. Note that the control has been removed from the visual control library used in Visual Studio however so you can’t drag and drop this control onto a page, nor will you get Intellisense for it any longer.

Why change?

So why this break? The wwWebAjax control was fine in functionality but it rolled several different functonalities into a single control which resulted in a control interface that required setting many settings in order to make anything happen. In addition, the client library that was driving the control was pretty limited and the original implementation addressed the control’s scenarios and little more. Since then the library has grown in functionality and sophistication and the old control simply didn’t fit any longer.

Here is what is different in this release:

• Break out of wwWebHoverPanel and wwWebMethodCallback as separate controls
• Client classes that match server controls
• Object oriented JavaScript implementations that are extensible
• Consistent model for client and server controls
• Rich client side library for common DOM oriented tasks

For most of you that are upgrading the first point is the most critical one as it will require code changes. The changes are not drastic, but they require touching each of the AJAX server controls, the client side initiation code and the handling code.

The matching client classes is the primary reason for the rebuild. All the server side controls – wwWebHoverPanel, wwWebMethodCallback, wwWebDragPanel, wwModalDialog – all have matching client classes that can be completely driven through client code. IOW, the server controls are not even required (with the exception possibly of the wwWebMethodCallback control which requires specific URL and POST formats). All of the client library code is indepdendant of the server code. And there’s a ton of useful functionality in the client side library in general that can be used for general purpose functionality. Here’s a short list:

• SetText/SetHtml – consistent value assignments
• Get/Set Location, Get/SetBounds of controls
• Get/Set Opacity
• ShowShadow/HideShadow
• FadeIn/FadeOut
• CenterInClient centers control/element
• Array and Cursor List databinding
• wwToolTip Control for quick messages
• wwEvent wrapper gets consistent event properties and hookups
• wwDebug object for debug output to screen
• String and Array extensions
• wwHttp HTTP client functionality (same site only)

Which can be used with or without the server controls. The client library is not particularily rich, but it provides many common use features in an easy to use and understand manner. You can see a number of the features used in the demos and of course the high level control implementations make extensive use of the functionality.

Updating existing wwWebAjax Control Code

So if you used wwWebAjax in your application you’ll probably want to update to the new controls to get all the updated functionality. The new controls have many new features.

A word about updating the Control Library

If you are a running a Web Connection project in Visual Studio make sure that you udpate the WestWindWebControls.dll in the BIN directory to the version that ships in:

<your wconnect folder>\VisualStudio\WebConnectionWebControls\bin\Debug\

Either by copying this file into your project BIN directory or by adding the project to your Visual Studio solution and recompiling. I personally prefer the latter since it ensures that when an update occurs with Web Connection all you have to do is recompile the project to get the latest version.

Some people have noted problems with the toolbox after updates. First the wwWebControlAjax is no longer in the control library so it will show an error on the page. If you set the compatibility flag in the Web Connection configuration file this doesn’t matter – the error is only related to the designer and the code will run anyway.

Make sure that the toolbox entry and the DLL in the BIN directory are in sync. The best way to do this is to update DLL in the BIN folder as described above, then exit Visual Studio and then re-register the control from Web Connection. To do this:

DO WCSTART to bring up the Web Connection Menu and click Configure Visual Studio 2005 which re-registers the toolbox, recopies the Web Connection Add-in (which has a few new features as well such as support for non-IE default browsing) and reregisters the WCSX editor extension.

This should ensure that toolbox data and the actual DLL are in sync. Note: I’ve found that occasionally the toolbox get corrupted and fails to drop items onto the page. I’m not sure why this occurs exactly but usually the steps to remedy this are:

• Remove the Web Connection Web Controls section
• Re-run the registration from the Web Connection menu

If all else fails, add the WebConnectionWebControls project to Visual Studio and use the generic section that gets created (WebConnectionWebControls) from an active project. From there you should ALWAYS be able to drop a control because it matches the compiled control library.

wwWebHoverPanel

Let’s start with wwHoverPanel. Hover panels now can be draggable and closable, the hover behavior is much cleaner and there are many more display options for the control to display the popup. You can also load content into a specific element inside of the panel rather than always replacnig the entire panel content.

The overall behavior of the control is the same, but the control interface has been changed. When you drop the new control on a page you typically don’t need to set any properties on it – the defaults are ready to call back to the current page. All you need to do is make the initiation call. The easiest thing to do might be to simply replace the wwWebAjax control and add a wwHoverPanel instead. Most likely you’ll only need to set a couple of properties on the control to duplicate the 5 or 6 properties you typically had to set before. Alternately just rename the tag from ww:wwWebAjax to ww:wwWebHoverPanel and watch for the red squiggle errors in Visual Studio. A typical wwWebHoverPanel tag looks like this:

<ww:wwWebHoverPanel ID="LookupPanel" runat="server"

              ServerUrl="/wconnect/webcontrols/SmallCustomerForm.wcsx"

              EventHandlerMode="ShowHtmlAtMousePosition"            

              NavigateDelay="250"

              PostbackMode="Post"            

              ScriptLocation="WebResource"

              Style="display: none; background: white;border:solid 1px lightgray;"

              PanelOpacity="0.89"

              ShadowOffset="8"

              ShadowOpacity=".30"

              HtmlTargetClientId="PanelContent"

> 

    <!-- Note: These div panels are only used in the closable box sample

               In the standard hover sample content is loaded directly

               into the LookupPanel. The DragPanel example loads content

               into the PanelContent area, and makes the header the DragHandleId

    -->

    <div id="PanelHeader" class="gridheader">Customer Info</div>

    <div id="PanelContent"  style="padding:10px;background:cornsilk;"></div>

</ww:wwWebHoverPanel>

Note that I left in some default properties here. Post and WebResource are default settings as is the ShowHtmlAtMousePosition flag – those can actually be omitted unless changed. Notice also that you can now design the hoverpanel as indicated by the embedded <div> tags embedded in the panel and the HtmlTargetClient id. There are many more options like makng the panel not auto close, making it closable and draggable and so on. Check the documentation walk through for more info on that as well as the sample.

To invoke the hoverPanel once you’ve set up the control above is slightly different than before:

LookupPanel.startCallback(event,"id=1");

When the control is created a public variable with the same name as the control ID is created in JavaScript and you can use that object to call the startCallback method to initiate the callback. There are additional parameters for a POST buffer and a callback handler that notifies you when the response returns but before the panel is shown so you can potentially abort the rendering or modify the result.

wwWebMethodCallback

Method callbacks pretty much work the same but the client side interface is much cleaner and makes it much easier to make multiple simultaneous callbacks. As with the HoverPanel control this control has a matching client class that encapsulates the callback mechanics. It’s much easier to create separate control instances for simultaneous callbacks and there’s more flexibility in handling the result data and error information.

To drop a wwMethodCallbackControl on a page is simpler with fewer properties. In fact all of the following are optional:

<ww:wwWebMethodCallback ID="Proxy" runat="server"

PostBackMode="Post"

PostBackFormName="form1"

ScriptLocation="WebResource"                          AllowedPageMethods="Helloworld,AddNumbers" >

</ww:wwWebMethodCallback>

To initate a callback is similar to before but you call a method on the Proxy object which is the a global variable with the same name as the control:

Proxy.callMethod("AddNumbers",[12,22],AddNumbers_Callback,OnError);

Proxy in this case is a global instance variable. You can also create a new instance like this:

var Proxy2 = Proxy_GetCallback()

Proxy2.callMethod("Helloworld",["Rick"],AddNumbers_Callback,OnError);

Notice that callmethod now takes an array of parameters rather than just plain parameters (which was difficult to parse) and takes a callback handler and an optional error handler. Both are optional, but you typically want to implement both. The script code for this might look like this:

function AddNumbers()

{

    var Num1=$('txtAdd1').value; 

    var Num2=$ ('txtAdd2').value;

    // *** Note that you have to pass the value as a number!

    Proxy.callMethod('AddNumbers',[Num1 * 1.0,Num2 * 1.0],AddNumbers_Callback,OnError);

}               

function AddNumbers_Callback(Result)

{

    $('txtAddResult').value = Result;

}  

function OnError(Error)

{

     //alert("An error occurred on the server:\r\n\r\n" + Error.message);

     wwModalDialog.messageBox(Error.message,"An error occurred");

}

With wwWebAjax the callback and error handler were one and the same which resulted in having to check for errors on every call. Now with the separate handlers the main callback handler code can be much cleaner as you are guaranteed a result value.

Note also that the parameters that are passed are passed as typed values. AddNUmbers() on the server expects numeric values and so the values sent from the client have to be passed as numeric values. You can see the user input is converted to numeric in the above code. Of course you can still pass string values, but it depends on how the server expects parameters to arrive.

Obviously these changes will break existing code. Each and every method callback will have to be fixed up, but I think the changes are minor and quickly performed. Each callback handler will need to be cleaned up as well, but that will mostly mean removing the error check code.

To keep things in perspective, the Web Connection Chat sample that ships with the samples and  uses these method callbacks that has about 10 callback handlers took about 10 minutes to convert and test and have running with the new control.

Summary

I realize that this is somewhat irregular for Web Connection to break backwards compatibility but in the end I think this will be well worth the changeover. Further I believe that adoption of the existing AJAX control was probably rather light and although I appreciate the early adopters <s> it was a sacrifice that felt justified in making.