Brian Mains Blog

Differences in AJAX Control Toolkit Controls and Extenders Client State

2008-08-20T19:59:00Z

Sorry for the long title, but I wanted to post about some of the differences between the controls and extenders client component's client state, which are defined for AjaxControlToolkit.ControlBase and AjaxControlToolkit.BehaviorBase on the client. In developing an AJAX Control Toolkit control, I've come to find some of the differences. One of the key differences is with client state.

Client State is a hidden field mechanism that stores data about the current state of the AJAX control. For an AJAX control toolkit extender that supports client state, on the client the get_ClientState and set_ClientState properties are avaialble to read/write data to this hidden variable. This works really easily on the client, plus it allows the server to access the value through the ClientState property, and load/save the client state value.

For a control, however, a control developer needs to override the SupportsClientState property, and return true. Furthermore, there are no equivalent properties on the client. Instead, the get_clientStateField and set_clientStateField get and set the reference to the field, so it's possible to read and write the values using this reference through get_clientStateField().value. This only works if SupportsClientState is set to true. Controls also have to use the LoadClientState and SaveClientState methods to load/save state. State is loaded whenever LostPostData occurs and saved when the hidden field is registered.

Another interesting variation is that the control base class uses the ScriptManager's RegisterHiddenField, whereas the extender creates its own hidden field reference so that the developer can work directly with the ClientState property.

AJAX Errors: is undefined

2008-08-20T12:44:00Z

One of the errors that frustrated me when developing AJAX controls was when I got <Namespace> is undefined, even though the script appeared to be correct. I couldn't figure it out right away because the class was registered correctly and the namespace was defined properly as well. So what could be the issue?

To help make AJAX development easier, I use a CodeSmith script to generate the shell AJAX component code, which works really well. This time when I got the error, it was for a component I created manually without the script. As soon as I replaced my code with the CodeSmith template generation code, the component began to work.

What this means is that while sometimes the error may be a missing component reference (like the System.Web.Extensions assembly or the AJAX Control TOolkit dll), more often the issue could be an issue with the formatting of your script, like a missing comma or curly brace, something like that. Something small that even VS wasn't picking up with its limited error checking.

So, a word of caution: write your script, and check it twice

TDD and Object Development

2008-08-16T20:00:00Z

When using TDD practices, you may think ahead a little bit to a situation in the future. For instance, suppose you have this:

public class CustomerClassification
{
   public CustomerClassification(string name, string type)
   {
      this.Name = name;
      this.Type = type;
   }

   public string Name
   {
      get { return _name; }
      set { _name = value; }
   }

public string Type
{
     get { return _type; }
     set { _type = value; }
   }
}

It's tempting to think that the property values will need to be change for some reason in the future, even though your current tests and current development of the application don't identify a need for a setter. I'd recommend that you leave out the setter until you actually see a need for adding it in. The reason is that this is more inline with TDD (implement it only when you need it), plus setters may cause problems in the future (changing values that shouldn't be changed as the constructor would be the only point of entry).

A perspective in the light of TDD... this may not always be a valid reason and I'm definitely not against setters,but it's something to consider.

AJAX $find Usefulness

2008-08-11T02:23:00Z

Every AJAX control or extender you build has an ID on the client, accessible through get_id and set_id. This ID is a unique ID and doesn't have to match the ID of the control it's given on the server, but the script registration process ensures that the server and client match. So, using the ID, $find can reference the client component of any AJAX control on the page like so:

<ajax:TabContainer ID="tc" runat="server">

</ajax:TabContainer>

The client component has a handy set of features, such as getting or setting the active tab index (through get_activeTabIndex and set_activeTabIndex) or polling the collection of tabs. Each AJAX component has a client architecture you can take advantage of; it may take some getting used to that fact, but if you dig through the AJAX control toolkit code available on http://www.codeplex.com, you'll learn more about what is available to you on the client.

AJAX Properties in Description

2008-08-11T02:13:00Z

I may have mentioned somewhere in my blog that AJAX components go through a process of describing the properties and events (at least) so that the server component can push down values to the client. This process happens in the GetScriptDescriptors method. The ScriptDescriptor,which has three deriviatives, notes a component's properties and events by using the following approach:

ScriptBehaviorDescriptor descriptor = new ScriptBehaviorDescriptor("<full client class name>", targetControl.ClientID);
descriptor.AddProperty("highlightCellOnMouseOver", this.HighlightCellOnMouseOver);
descriptor.AddProperty("highlightRowOnMouseOver", this.HighlightRowOnMouseOver);

return new ScriptDescriptor[] { descriptor };

Notice a few things: first off, the AJAX component I'm creating is a custom extender. You can tell this because I used ScriptBehaviorDescriptor (I would have used ScriptControlDescriptor for an AJAX control). The AddProperty method adds properties for the description process; in this way, the AddProperty method passes along a value established on the server to the client, to act as a default value of sorts.

In reality, on the client side those properties have the following definition:

get_highlightCellOnMouseOver : function()
{
return this._highlightCellOnMouseOver;
},

set_highlightCellOnMouseOver : function(value)
{
if (this._highlightCellOnMouseOver != value)
{
this._highlightCellOnMouseOver = value;
this.raisePropertyChanged("highlightCellOnMouseOver");
}
},

get_highlightRowOnMouseOver : function()
{
return this._highlightRowOnMouseOver;
},

set_highlightRowOnMouseOver : function(value)
{
if (this._highlightRowOnMouseOver != value)
{
this._highlightRowOnMouseOver = value;
this.raisePropertyChanged("highlightRowOnMouseOver");
}
},

So theoretically they can be changed during the client's lifecycle, but at least a default value is established on the server.

AutoCompleteExtender Client API

2008-08-04T02:12:00Z

I previously posted about the format that a web service method has to be in for the AutoCompleteExtender to work. This blog post focuses on some of the other capabilities of this extender. In an example web method, I concatenate text and return the concatenation using LINQ as follows.

[WebMethod]

public

string[] GetTopSearchPhrases(string prefixText, int count) {

SearchManager manager = SearchManager.GetManager();

SearchPhraseCollection phraseCollection = manager.GetTopSearchPhrases(prefixText, count);

return (from p in phraseCollection select string.Format("{0} ({1} occurrence(s))"
, p.Phrase, p.ResultCount.ToString())).ToArray();

}

What I want to do is get the results as:

Microsoft .NET (21 occurence(s))
Microscopes (122 occurence(s))

And so on. But, when the user selects an item in the list, I do not want the parenthesized text to appear in the textbox. To trim this, I added a javascript event handler for the OnClientItemSelected event, that does this:

//Ensures that the parenthesized text isn't passed on

function

autoComplete_itemSelected(sender, e) {

var text = e.get_text();

if (text.indexOf('(') > 0) {

text = text.substring(0, text.indexOf(

'('));

if (text != null && text.length > 0)

text = text.trimEnd();

}

var targetElement = sender.get_element();

targetElement.value = text;

}

What this does is it gets the text of the item currently selected. Then, if the text contains a parenthesis, it strips it out. If the text happens to be not null, it's trimmed (to remove the extra spacing from " (" in the text; I'd rather programmatically trim than do a -1 just in case I change the formatting of the output string later and forget to change the accompanying event handler.

Lastly, the sender is the AutoCompleteExtender client class, and get_element() returns a reference to the target textbox. The value is overridden (as the AutoCompleteExtender assigns the selected value to the textbox, but our event handler occurs after that assignment, wiping out any changes already performed).

You may wonder where get_text() came from; the event argument is AutoCompleteItemEventArgs, which has a get_text(), get_value(), and get_item() properties. The latter is information about the item itself, whereas the first two contain the information about the items in the list. You wouldn't know without the documentation what this event arg was. I found this out by looking in the AJAX control toolkit code myself. I could have put a debugger breakpoint in the code and figured it out that way as well.

Developing AJAX Controls

2008-08-03T02:18:00Z

When developing AJAX-ified controls using the AJAX framework from microsoft and the AJAX control toolkit, you have to rethink the control development approach a little bit. After all, the key to making AJAX controls work is rendering code on the client-side, and being the AJAX uses managed scripts, the scripting process has to be well thought out. It's not that overtly difficult to create custom controls, but it does usually require large amounts of code. I start off my scripts from a script that I have for CodeSmith. This script is really helpful in that regard.

Although preparation is needed, a paradigm shift is also needed as well. Before control developers spent time rendering logic in the server-side, writing out the HTML to the browser in the Render method. Now, with ASP.NET AJAX, it's beneficial to render that logic on the client-side instead. This is because controls can take advantage of more features this way.

For instance, take the CheckBoxList control. How advantageous would it be to be able to dynamically add/remove items to the list? However, the logic exists on the server side to create the interface, and I ran into a problem this way because the client code had to know what the server is rendering in order for it to take advantage.

If all of the rendering was done on the client-side, this moves the logic to one place, which allows client-side refreshing of the interface (even rebinding from data streamed through a web service). This really makes controls more advanced, but more cumbersome as client-side code becomes more verbose and difficult to manage.

July 17th Presentation

2008-08-02T20:49:00Z

Although the presentation is already done, the powerpoint and code samples I used for a presentation on AJAX custom controls and extenders is available on the Central Penn's .NET user group web site at: http://www.central-penn.net in the downloads section.

The Central Penn .NET user group is a group for the central Pennsylvania that discusses anything .NET related. They have some good speakers at their presentations, so if you get a chance, come on out the third Tuesday of the month. You may catch me presenting again sometime in the future; I am planning on speaking for their Code Camp the first Saturday of December.

AutoCompleteExtender Web Service

2008-08-02T01:17:00Z

If you've worked with the AutoCompleteExtender, you know that the extender returns a nice drop down list that only contains items with the keywords entered. As you type more and more characters, the results in the list are filtered by the characters currently entered, until the item sought after is the only one left, or no items are left.

Personally, I had a really hard time getting this to work, and what I didn't realize is that the service requires a specific layout. This layout should be in the form:

[WebMethod]
public string[] GetAutoCompleteResults(string prefixText, int count) { }

or, if using a context key:

[WebMethod]
public string[] GetAutoCompleteResults(string prefixText, int count, string contextKey) { }

Then the AutoCompleteExtender can hook up to the service and call this method, providing real-time filtered results.

AJAX Web Services

2008-07-31T22:16:00Z

Connecting to web services in AJAX is really easy. To setup a web service that can be called on the client, simply do the following. Create a web service in Visual Studio; add one to the web project by right-clicking on the desired folder and selecting the new item option. Select the web service option, which creates an ASMX. This is the extension for a service in the web project.

Add the following attribute: [System.Web.Scripts.Service.ScriptService] When the project runs, a client proxy is generated automatically for you, one that matches your namespace/class name. If you create a service in namespace Mains.Examples, with a service name of ArticleCodeGenerator, the following can be run on the client without having to write any code:

    function onFailure(results, userContext, methodName)
    {
        //called when failure occurs
    }
</script>

<asp:Label id="lblTemplate" runat="server" />

The way the service method is setup is illustrated in the following:

ServiceMethod( <any parameters separated by commas>, <success callback>, <failed callback>, <context>);

The success or failed callback has to meet the template shown above; results contains a reference to the object returned from the method. If an actual object and not a primitive type, the object is converted using JSON. The context object can in reality be anything, and is often passed a value to the UI control (as shown in many examples).

Add a reference to the service to the script manager:

<asp:ScriptManager ...>
   <Services>
       <asp:ScriptReference Path="..path to ASMX" />
   </Services>
</asp:ScriptManager>

That's how easy it is to include web services into AJAX. Even cooler is how Visual Studio provides intellisense for this object.

AJAX: Working with Events

2008-07-17T18:14:00Z

Events in ASP.NET AJAX are quite unlike the events in the .NET framework. Rather than having explicit events and event handlers, the framework provides a workaround to this approach that doesn't require any custom syntax definitions to JavaScript itself, while still being able to expose the capability.

The approach is to expose events using an events property. This events property is defined in the Sys.Component class, the base class of all controls and extenders. The get_events() property setter returns an object of type EventHandlerList. This object can add event references to client events stored in a key. For instance, the following methods add, remove, and raise an event. These methods are located in the prototype definition, which is why the function declaration is at the end.

add_propertyChanged : function(handler) {
    this.get_events().addHandler("propertyChanged", handler);
}

remove_propertyChanged : function(handler) {
    this.get_events().removeHandler("propertyChanged", handler);
}

raise_propertyChanged : function()
{
    var handler = this.get_events().getHandler("propertyChanged");
    if (handler != null)
        handler(this, Sys.EventArgs.Empty);
}

Working with events are done by methods that map the name of the event to a handler. The event is referenced by a string that uniquely identifies the event. Any clients registering to this event would register the name of a JavaScript method. This JavaScript method would be the event handler for the event in the ASPX page that the control or extender resides in.

It's up to something in the AJAX control or extender to call raise_propertyChanged. When some member does (property or method), this then triggers the propertyChanged event. An event handler in the ASPX would receive notification of it, and would be passed the sender and event argument (though the method doesn't have to accept these parameters). An event handler can be wired up like so:

Anything that triggers this event will call the propertyChangedHandler JavaScript method. This method is a client-side event handler for our purpose. Something in the component actually needs to call raise_propertyChanged() to fire the event, but our event handler will catch it.

In ASP.NET AJAX components, the typical way to expose events is through a property (as oxy moronic as that may be). The property stores the name of the JavaScript event handler (propertyChangedHandler) and passes it to the client script when the component is described. In an ASP.NET AJAX component, this is done using GetScriptDescriptors, with a statement as shown below:

descriptor.AddEvent("propertyChanged", this.OnClientPropertyChanged);

It's by convention to include "OnClient" for event handlers to a client event. Using the AJAX Control Toolkit approach, events can be declared using the following approach:

[
ExtenderControlEvent,
ClientPropertyName("propertyChanged")
]
public string OnClientPropertyChanged
{
get { .. }
set { .. }
}

At runtime, the AJAX component is dynamically described by using the metadata defined in the attributes of the property definition, which it sees that the OnClientPropertyChanged property contains the name of a method that is an event handler. This event handler is passed to the add_propertyChanged method. When that event is raised, the event handler defined here gets fired.

AJAX: Working with Properties

2008-07-17T16:00:00Z

In JavaScript, there really isn't such as thing as properties. Essentially a read/write property is represented by two methods, one with a "get_" prefix and one with a "set_" prefix. However, the ASP.NET AJAX framework separates this as just a method; for instance, the following property definition is shown below:

//note the function declaration after is the prototype syntax, as properties are note
get_text : function()
{
return this._text;
}

set_text : function(value)
{
if (this._text != value)
{
this._text = value;
this.raisePropertyChanged("text");
}
}

In javascript, you can't reference the property via "text" and work with it like a property in .NET. You have to use the get_text() and set_text("text") method calls; however, in .NET, you can work with it like a "text" property when you describe it. Every ASP.NET AJAX server control needs to describe its client counterpart in the GetScriptDescriptors method; to describe a property can simply be done by:

descriptor.AddProperty("text", this.Text);

Notice the property doesn't need to specify "get_" or "set_" at all; it can simply reference it as "text" (the framework appends a "get_" or "set_" when it makes the actual assignment. Also, the second parameter of AddProperty pushes down the current value of Text stored on the server-side, which acts as the initial value at load time.

If you use the AJAX Control Toolkit approach to developing custom controls or extenders you don't need to define GetScriptDescriptors; rather, the framework does it for you using reflection of attributes, shown below:

[
ExtenderControlProperty,
ClientScriptResource("text")
]
public string Text { .. }

ExtenderControlProperty notes that Text should be described as a property, while ClientScriptResources states what the property is named. You don't need to use ClientScriptResource if the server-side property name matches the client side name, but the matching is case sensitive and our script uses lower camel case instead of upper as on the server, which is why I defiend the attribute. At runtime, the previous descriptor.AddProperty statement is created automatically for us and the script is described correctly.

AJAX Control Toolkit's ComponentReferenceAttribute and ElementReferenceAttribute

2008-07-17T13:25:00Z

If you've done custom development using the AJAX Control Toolkit, you know that the approach the framework takes is an attribute-based approach. If you haven't looked at this before, check out this brief example (there are some other sections on the site that are helpful): http://www.asp.net/AJAX/AjaxControlToolkit/Samples/Walkthrough/CreatingNewExtender.aspx. There are som explanations of the attributes that can be used here: http://www.asp.net/AJAX/AjaxControlToolkit/Samples/Walkthrough/ExtenderClasses.aspx.

The ComponentReference is a very useful attribute, which I didn't see in the links above. This attribute can be used on a property that holds the ID of a control. It will internally find the control reference and provide a reference to the AJAX class for that control. Let's assume the following property as an example:

public string AjaxControlID { .. }

The AjaxControlID property stores the ID of a control that emits an AJAX script. An AJAX control has both a server-side component and a client-side component. For instance, the TabContainer control has an AjaxControlToolkit.TabContainer server component and an AjaxControlToolkit.TabContainer client component. ComponentReference is a shortcut way, by using the ID, to gain reference to the client component (thie client component has a get_id getter that has the same ID as the control.

While ComponentReference gets a reference to the client component, ElementReference gets a reference to the HTML element that the client component extends. Every AJAX control and extender works with some underlying HTML element; an extender targets a different HTML element with its javascript, while a control renders its own interface, which means it extends the HTML element it renders.

So if we have a server property:

[
ExtenderControlProperty,
ClientScriptResource("extenderControl"),
ComponentProperty
]
public string ExtenderControlID
{
get { .. }
set { .. }
}

Which maps to the client class's property getter/setter defined in the prototype definition:

get_extenderControl : function()
{
return this._extenderControl;
}

set_extenderControl : function(value)
{
this._extenderControl = value;
}

The reference to the component for the extender is accessible on the client side; _extenderControl references the custom AJAX class for the extender. If the property used ElementReference, it would reference the HTML element that the extender represents.

LINQ to SQL and Data Context Awareness

2008-07-17T12:56:00Z

If you have developed applications with LINQ to SQL, you know that one of the features of these objects are that they are aware of the DataContext they were created in. This can have issues in ASP.NET if you do not cache the DataContext it belonged to, because each LINQ to SQL business object knows which context it was created in, and if it isn't the current one, then an exception is thrown.

It's possible to create new business objects without them being known by the DataContext; when you first create an object, until that object is passed along to the DataContext through InsertOnSubmit, the data object can be a temporary holder of data disconnected from the database. It's also possible to create relationships for the data that are also disconnected from the database, so you can build a whole tree of relationships of objects rather easily, all in disconnected form.

If you like to use that approach, use caution. If you add one object as a reference to a disconnected object that is DataContext-aware, then all of the other disconnected objects related to that object will all be queued up for insertion, which is a HUGE pain. If you get a lot of duplicated data, this is the first place to look; is a DataContext-aware object reference being assigned anywhere? If so, remove it, and make a reference by key.

That can pose problems because one of the nice features of LINQ to SQL is being able to drill-down an object model using the PK/FK properties, but in disconnected mode, all of the data has to be disconnected, and reference data won't work because you aren't usually creating it on the fly. Creating temporary matching records isn't typically a good idea as well, because if they aren't removed, data will be duplicated, plus removing the objects later may damage the reference for the real value potentially.

So what are the options here? I'd recommend storing as little disconnected data as posslble, or make sure you tread lightly.

AJAX Descriptors

2008-07-16T02:56:00Z

So what is the purpose of the descriptor? The descriptor describes information about the component, such as properties, events, and methods. For properties, the descriptor states the name and type of the property, as well as whether the property is read-only or if null values are allowed.

So what does that govern? I was changing a component and found out that it governs a lot because whenever I changed the definition of the property, an exception was thrown at runtime, stating that a readonly property had a setter definition. So the ASP.NET AJAX framework is aware about your structures through the descriptor, and does perform validation.