The Web.UI 2006.2 release brings a brand-new client-side API that uses Microsoft’s AJAX Library syntax across the board: new property accessors, new naming conventions, a new client event mechanism, and more. The new API looks the same even in the non-ASP.NET AJAX builds, providing a way to future-proof your code even if you are not immediately moving to ASP.NET AJAX. Furthermore, everything has also been designed with backward compatibility in mind, so your old code will also work and nothing should break when you simply pop in the new assembly. It is highly recommended, however, that old client-side code which uses ComponentArt APIs be migrated as soon as possible to the new system. Here’s how: Accessing control objects With Web.UI 2006.2, it is no longer necessary to use the server-side ClientObjectId property to determine the client object ID in most cases. The only situation where this is still the case is when the control is in a repeated template, which results in its assigned ID not being unique. In that case, we still use the old way of referring to the client object by its unique ID: var myControl = <%= Control.ClientObjectId %>; In all other cases, simply using the assigned server-side ID will suffice. Regardless of how many nested containers the control is placed in (user controls, master pages, UpdatePanels, etc), it will use the assigned ID as its client-side object identifier if it is available. This makes it possible for the developer to write server-side and client-side code using the same identifiers in the vast majority of situations, never having to worry about hard-to-predict ID prefixes. Accessing properties One of the main differences between the old and new ways of doing things is how we access object properties. Every property now has its own get and, unless it is read-only, set methods. To get the value of an object's property, we call the object's get_propertyName method. For instance, to access TreeView's nodeCssClass property, we would call TreeView1.get_nodeCssClass() Similarly, when setting a property, we would use its set method. For example: TreeView1.set_nodeCssClass('NodeClass'); Batch updates In those cases where setting a property potentially affects the look of the control on the page, doing so will cause the control to re-draw itself. Multiple property sets may therefore cause unnecessary control re-draws, affecting performance. To avoid this, we notify the control that we are about to perform a batch of updates by calling its beginUpdate method. When the updates are done, a call to endUpdate causes the control to re-draw. Here is an example: TreeView1.beginUpdate(); TreeView1.set_cssClass('TreeClass'); TreeView1.set_nodeCssClass('NodeClass'); TreeView1.set_itemSpacing(3); TreeView1.set_marginWidth(15); TreeView1.endUpdate(); The beginUpdate and endUpdate methods are inherited from Sys.UI.Control and are a standard AJAX Library mechanism. Note that the render method is still present in controls that need occasional re-drawing, but it now rarely (if ever) needs to be called explicitly. Navigator node collections Navigation controls with client-side interfaces (Menu, TreeView, NavBar and TabStrip) now have collection classes for their items. These classes should be used to access menu items, tree nodes, etc. To access the collection of top-level Menu items, for instance, we no longer call the Items method – we would instead get its items property, which returns an object of type MenuItemCollection: var topItems = Menu1.get_items(); // get the top items var firstItem = topItems.getItem(0); // get the first item in the collection To add a new item, we no longer use the AddItem method – instead, we add the item to the appropriate collection. For instance, to add a new item to the first item’s sub group, we would do the following: firstItem.get_items().add(newItem); Calling methods By convention, method names now start with a lowercase letter. Therefore, in most cases, updating method calls to new syntax will require just that change. For instance, instead of calling Grid’s GetSelectedItems method to check which items are selected, we would use the lowercase equivalent: var selectedItems = Grid1.getSelectedItems(); Handling events Web.UI 2006.2 introduces a new way of defining client event handlers on the server. Each control with client events now has a ClientEvents property, which is an object containing all of that control’s client events and their handlers. For example, to handle NavBar’s itemSelect event on the client, we would no longer set its ClientSideOnItemSelect property. Instead, we would define the handler in the control’s ClientEvents block: < ComponentArt : NavBar runat = "server" ID = "NavBar1" ... > ... < ClientEvents > < ItemSelect EventHandler = "NavBar1_OnItemSelect" /> </ ClientEvents > </ ComponentArt : NavBar > Before Web.UI 2006.2, client-side event handlers had different signatures depending on the event. To comply with AJAX Library methodology, all event handlers now have the same signature: function eventHandler(sender, eventArgs) The first parameter, sender, is the control object which raised the event (for instance, a NavBar). The second, eventArgs, is an object of a class deriving from Sys.EventArgs and, depending on the event, contains various properties related to the event. For instance, NavBar’s itemSelect event passes a parameter of type NavBarItemEventArgs, which contains an item property, pointing to the NavBarItem involved in the event. To handle this event on the client, we might define a function that looks like this: function NavBar1_OnItemSelect(sender, eventArgs) { alert ('Selected item: ' + eventArgs.get_item().get_text()); } Conclusion That’s all there is to it! At any time now or in the future, check out the client-side API reference for further enhancements and additions. Happy translating! Share this post: email it! | bookmark it! | digg it! | reddit!
