Chapter 11 - Adding Client Capabilities to Server Controls Using the ASP.NET AJAX Control Toolkit

In this chapter, we delve into the details of the toolkit a little further as we develop as series of extender controls that demonstrate the rich features the toolkit provides.

Add Attributes to the Property

To fully implement the ability to add nested image entries to our Image Rotator extender, we need to add a couple of attributes, as shown in Listing 11.8, to our ImageList property, which provides hooks for the designer to integrate with our property and properly assign the image values.

The DesignerSerializationVisibility attribute is added to the property to ensure that the designer will serialize the contents of the property during design time. The setting of DesignerSerializationVisibility. Content instructs the designer to generate code for the contents of the tag and not the tag itself.

The PersistenceMode attribute is the other piece to this puzzle and is responsible for adding the <ImageUrl .. /> entries inside our ImageRotator tag as we add values to the property in the Properties window. The setting of PersistenceMode.InnerProperty speci.es that the property is persisted as a nested tag inside the ImageRotator, as shown in Listing 11.7.

Listing 11.8 Designer-Specific Attributes for the ImageRotatorExtender Class

[ParseChildren(true, "ImageList")]

public class ImageRotatorExtender : ExtenderControlBase
{

    [DesignerSerializationVisibility(
    DesignerSerializationVisibility.Content)]
    [PersistenceMode(PersistenceMode.InnerDefaultProperty)]
    public ImageUrlList ImageList
    {
 
    }
}

Add Editors to Assist in Assigning Values

The use of editors in your extenders can greatly enhance the user experience during design time and in some cases can lead to more accurate entry of data. Recall from Chapter 5 that we entered images to the ImageList property by adding URL entries and separating them using commas. This rudimentary approach would not be expected by a consumer of a professional control. In this version of the ImageRotator, we want to enhance the data entry of the images by providing an editor that can be used to add image URL entries and have those entries placed into the body of our ImageRotator HTML tag. If we go back to the ScriptManager control, this is the experience it provides when adding web service or script references while in the Properties window.

The ImageList property in this version of the ImageRotator uses two editors to provide a rich design-time experience when adding ImageUrl entries. The .rst editor is a Collection editor, shown in Figure 11.5, and is designed to assist in adding, editing, and removing values that are based on a Collection. The editor is automatically associated with our ImageList property because the type of the property is a Collection. The second editor we will use is the ImageUrlEditor, shown in Figure 11.6, which the ImageUrl entry uses to assist the user in entering a URL. This editor is associated with the Url property of the ImageUrl class, as shown in Listing 11.9, by adding the Editor attribute to the property. We use the Editor attribute to con.gure which editor to use when adding values to the property in the designer. In our case, we are using the ImageUrlEditor to provide the user with a clean way to .nd an image located in a web application and assign the value to the ImageUrl property. The use of the associated UrlProperty attribute provides a .lter that identi.es speci.c .le types that can be used to .lter against the ImageUrl property.



Figure 11.5 Image URL Collection Editor

Listing 11.9 ImageUrl Class

[Serializable]
public class ImageUrl
{
    [DefaultValue(""), Bindable(true), Editor("System.Web.UI.Design.ImageUrlEditor,System.Design, Version=2.0.0.0, Culture=neutral,PublicKeyToken=b03f5f7f11d50a3a", typeof(UITypeEditor)),
    UrlProperty]
    public string Url { get; set; }
}

Figure 11.6 Image URL Editor

Create a Type Converter to Support Serialization

The use of complex types presents a few challenges in the ASP.NET AJAX Control Toolkit during the script generation process. The problem arises in how the ASP.NET AJAX Control Toolkit serializes your extender control properties as it creates the $create statement. By default, the toolkit tries to get the default string representation of the value your property represents. In most cases, this is an easy task because most simple types convert to a string relatively easily. If you are using complex types, however, this can present a problem because the default ConvertToString() representation of a complex object is its type name. To resolve this issue, you must create a type converter and associate it with the complex type. When the ASP.NET AJAX Control Toolkit encounters a type during script generation, it looks to see whether the type has a converter. If it does, it uses the converter to convert the data instead of using the default ConvertToString() method. In this section, we walk through creating a System.Component Model.TypeConverter that will be used to convert our ImageUrlList type into a JavaScript Object Notation (JSON) string that can be consumed on the client.

The ImageListConverter, shown in Listing 11.10, is designed to convert the ImageList to a JSON array of image URLs that are then passed back to the client. The creation of this type converter now enables us to return a data format that the client can use instead of a string that contains the type name of the ImageList. For the type converter to be used, we need to associate it with the ImageList type. We do this by adding the TypeConverter attribute to the ImageList class, as shown in Listing 11.11, and assigning the type of the ImageList to it. Now when the toolkit performs a Convert ToString on the ImageList, the JSON string representation of the Image List will be returned.

NOTE Use of the DataContractJsonSerializer

In more complex situations, you might use the DataContract JsonSerializer that we discussed in Chapter 8, "ASP.NET AJAX Communication Architecture," which replaces theSystem.Web.UI. JavaScriptSerializer class as the new JSON serializer to convert your data to JSON format.

Listing 11.10 ImageListConverter Type Converter Class

public class ImageListConverter : TypeConverter
{
    public override object ConvertTo(ITypeDescriptorContext context,
    System.Globalization.CultureInfo culture, object value,
    Type destinationType)
    {
        Collection<ImageUrl> imageList = value as Collection<ImageUrl>;
        if (imageList != null && destinationType == typeof(string))
        {
            StringBuilder builder = new StringBuilder();
            builder.Append("[");
            bool first = true;
            foreach (ImageUrl imageUrl in imageList)
            {
                if (first)
                {
                    first = false;
                }
                else
                {
                    builder.Append(",");
                }
                builder.Append("\"");
                builder.Append(imageUrl.Url.Replace("~/", ""));
                builder.Append("\"");
            }
            builder.Append("]");
            return builder.ToString();
        }
        return base.ConvertTo(context, culture, value, destinationType);
    }
}

Listing 11.11 ImageUrlList Collection Class

[Serializable]
[TypeConverter(typeof(ImageListConverter))]
public class ImageUrlList : Collection<ImageUrl>
{
}